Claude Skills: How They Work and How to Build One
August 12, 2026
A Claude skill is a folder with a SKILL.md file in it. That's the whole idea.
The folder holds instructions for a task you do often, and Claude reads it only when your request matches. Anthropic calls them Agent Skills; most people say Claude Skills. Either way, the useful parts to know upfront:
- Two required fields.
nameanddescriptionin YAML frontmatter. Nothing else is mandatory. - They cost almost nothing until used. Only the name and description sit in context — roughly 100 tokens per skill. The body loads when the skill fires.
- They run in three places: Claude Code, claude.ai, and the Claude API — and they do not sync between them.
- You can write one in ten minutes. A text file and a folder is genuinely the entire requirement.
The part that trips people up isn't writing a skill. It's running someone else's.
What a Claude skill actually is
Strip away the terminology and a skill is procedural knowledge on disk. Where a prompt is advice you give once in a conversation, a skill is advice Claude picks up on its own, every time the situation matches.
The minimum viable skill is one file:
---
name: changelog-writer
description: Write release notes from a git diff. Use when the user asks for a changelog, release notes, or a summary of what shipped.
---
# Changelog Writer
## Instructions
1. Run `git log --oneline` against the previous tag.
2. Group commits into Added / Fixed / Changed.
3. Write one line per entry in plain language, no commit hashes.
Two fields are required, and each has real constraints:
| Field | Rules |
|---|---|
name | Max 64 characters. Lowercase letters, numbers, and hyphens only. Cannot contain the reserved words "anthropic" or "claude". |
description | Non-empty, max 1024 characters. Must state what the skill does and when to use it. |
That second rule carries more weight than it looks. The description is the only thing Claude matches your request against when deciding whether to load the skill at all. A vague description means the skill quietly never fires. "Formats documents" loses to "Write release notes from a git diff. Use when the user asks for a changelog, release notes, or a summary of what shipped" — the second one names the trigger words a real person would type.
Beyond SKILL.md, a skill can bundle whatever else it needs: extra markdown references, executable scripts, templates, schemas. Anthropic's skill authoring guide covers the conventions in depth.
How progressive disclosure keeps skills cheap
The reason you can install thirty skills without wrecking your context window is an architecture Anthropic calls progressive disclosure. Content loads in stages, and each stage has a different price.
| Level | When it loads | Token cost | What it holds |
|---|---|---|---|
| 1. Metadata | Always, at startup | ~100 tokens per skill | name and description only |
| 2. Instructions | When the skill triggers | Under 5k tokens | The SKILL.md body |
| 3. Resources and code | Only when accessed | Nothing until read | Bundled files, scripts, reference docs |
The third row is the one worth dwelling on. Bundled files cost zero tokens until Claude actually opens them, so a skill can ship comprehensive API documentation or a dozen reference files without any context penalty for the ones a given task doesn't need.
Scripts are cheaper still. When Claude runs validate_form.py, the script's source never enters context — only its output does. That makes a bundled script meaningfully more efficient than asking Claude to generate the equivalent code on the fly, and more reliable, because it does the same thing every run.
Where skills work, and where they don't sync
Skills run across three surfaces, and the differences matter more than the docs' summary tables suggest.
| Surface | How you install | Sharing | Network access |
|---|---|---|---|
| Claude Code | Drop a folder in ~/.claude/skills/ (personal) or .claude/skills/ (project) | Personal, per-project, or via plugins | Full — same as any program on your machine |
| claude.ai | Upload a zip under Settings → Features | Individual user only; no org-wide management | Varies by user and admin settings |
| Claude API | Upload through the /v1/skills endpoints | Workspace-wide | None — no external calls, no package installs |
Custom skills do not sync across surfaces. A skill you upload to claude.ai is not available in the API. A skill in the API is not available on claude.ai. Claude Code reads from the filesystem and is separate from both. If you want the same skill in three places, you install it three times.
Anthropic ships four pre-built document skills — PowerPoint, Excel, Word, and PDF — but those are available on claude.ai and the API, not in Claude Code. The open-source skills repository is where community and Anthropic-published skills live, and it has drawn tens of thousands of shared skills since Agent Skills launched as a developer feature in October 2025. The specification is now published as an open standard at agentskills.io.
Build your first skill in about ten minutes
For Claude Code, which has the shortest path:
- Make the folder.
mkdir -p ~/.claude/skills/changelog-writer - Write
SKILL.md. Frontmatter withnameanddescription, then the instructions. Keep the body under roughly 500 lines — if it's growing past that, move detail into separate files and reference them. - Write the description last. Draft it by imagining the exact sentence a user would type. Then check that the words in that sentence appear in your description.
- Restart the session. Skills are discovered at startup, so a new or renamed skill won't appear until you restart.
- Test the trigger, not the output. Ask for the thing in your own words and confirm the skill fires at all. Most failures are discovery failures, not instruction failures.
Split reference material out early. Anthropic's own guidance is to keep SKILL.md lean and push detail into bundled files, precisely because level-3 content is free until it's read. A tight SKILL.md that points at REFERENCE.md beats one long file.
One caution worth taking seriously: install skills only from sources you trust. A skill is instructions plus executable code, so a malicious one can direct Claude to run commands or reach systems in ways its description never mentions. Anthropic's guidance is to audit every bundled file before use — scripts included — and to treat installing a skill the way you'd treat installing software. Skills that fetch content from external URLs deserve particular scrutiny, since the fetched content can carry instructions of its own.
The part nobody warns you about: running someone else's skill
Writing a skill for yourself is easy. Running one you saw someone post is where most people stop.
The friction is small individually and fatal in aggregate. You have to find the repo, work out whether it's a Claude Code skill or a claude.ai skill, get the folder onto the right path or zip it correctly, restart, discover it doesn't fire, read the description, edit it, restart again. Then you switch surfaces and do it over, because nothing syncs. None of that is hard, exactly. It's just enough friction that the skill stays in a bookmark folder.
That gap between seeing a workflow work for someone else and having it work for you is the problem Taku was built around — we wrote about the reasoning behind it in why we built an OS for AI. Taku is an AI-native desktop workspace where you can mirror a skill, app, or workflow someone has already got working, run it without assembling the environment yourself, then remix it into something that fits your own files. The app and workflow library is the starting point rather than a blank editor.
Taku is in Beta, and the honest framing is that it's aimed squarely at people who keep collecting AI setups they never get running. If you write your own skills fluently and enjoy the wiring, Claude Code already serves you well. If you've bookmarked five skills this month and run none of them, that's the gap.
FAQ
Are Claude Skills and Agent Skills the same thing?
Yes. "Agent Skills" is Anthropic's official name for the feature and the open specification; "Claude Skills" is what most people call them in practice. The anthropics/skills repository on GitHub is the canonical open-source collection.
Do Claude Code skills work in claude.ai?
No. Claude Code skills are filesystem-based, living in ~/.claude/skills/ or a project's .claude/skills/. claude.ai skills are uploaded as zip files through Settings. Neither surface can see the other's skills, and the same applies to the API — you install separately for each.
How many skills can I install before it slows Claude down?
Far more than you'd guess. Only each skill's name and description stay loaded, at roughly 100 tokens apiece, so the cost of an unused skill is close to nothing. The practical ceiling is discovery quality rather than context: with many skills whose descriptions overlap, Claude has a harder time picking the right one.
Why isn't my skill triggering?
Almost always the description. Claude matches your request against the description alone, so if it doesn't name the words a user would actually say, the skill stays dormant. Rewrite it to state what the skill does and the situations that should trigger it, then restart the session — skills are only discovered at startup.
Do I need to know how to code to write a skill?
No. A skill is a markdown file with two frontmatter fields, and plenty of useful ones contain no code whatsoever — just clear instructions for a task you repeat. Scripts are an optimization for when you want an operation to run identically every time, not a requirement. If you'd rather start from skills other people have already written and tested, a library of working setups is a faster on-ramp than a blank file.