A skill is a markdown file (plus optional helpers) that teaches Claude how to do a specific thing well. Not memory, not a hook, not a tool — just a recipe Claude reads when triggered.
There's a whole vocabulary floating around — skills, hooks, memory, agents, tools, MCP. They each do something different. This chapter pins down what a skill actually is, when it's the right answer, and when something else fits better.
The whole story in one line: a skill is a markdown file Claude reads when triggered, so it can do a specific thing the same way every time. Everything else in this chapter is making that precise.
A skill is a markdown file that teaches Claude how to do a particular thing well. That's it.
It lives on disk at ~/.claude/skills/<name>/SKILL.md. When something triggers it, Claude reads the file and follows the instructions inside. Not a plugin. Not a hook. Not a tool. Just a recipe.
The simplest mental model: imagine you've explained how to do X to Claude five times in five different chats. You're tired of typing it. So you write it down once, name it, drop it in the skills folder — and now Claude has it forever. Every time you'd repeat that recipe, that's a skill candidate.
This is the single most important sentence in this chapter:
Claude decides whether to auto-invoke a skill based on the description field alone.
Every skill starts with a YAML frontmatter block — the metadata bit between the two --- lines. Two fields matter:
The name has to match the folder name — it's how the skill is addressed. But the description is what Claude reads at session start to decide what each available skill is for. A good description is:
claude-api skill literally includes a "SKIP:" clause for non-Anthropic SDKs.Too vague ("helps with YouTube stuff") and the skill won't fire when the user expects it to. Too eager ("use whenever the user asks anything") and it fires for everything — becoming noise.
There are exactly two paths. Knowing both is enough.
The user types /skill-name <args>. Direct, intentional, always works no matter how the description is written. This is the path that's never ambiguous — useful for skills you want to fire only when you ask.
The user says something natural like "can you grab the transcript of this video?" — and Claude scans the descriptions of all available skills, looking for a match. If one fits well, it auto-invokes. This is the magic path: a well-written skill feels like Claude just knows what to do.
A well-tuned skill is invoked the same way both ways. The trigger phrases in the description are exactly the words natural users will say. If you find yourself thinking "I always have to type the slash command for this skill" — your description needs work.
SKILL.md is the front door. Everything else is up to you.
The conventional layout:
~/.claude/skills/<name>/ SKILL.md # required — the recipe README.md # optional — narrative docs scripts/ # optional — shell/node helpers templates/ # optional — prompt templates, file stencils references/ # optional — extended docs SKILL.md links to
The cardinal rule: SKILL.md is concise. Claude reads it on every invocation, so weight matters. Heavyweight content — long examples, full prompt templates, deep reference docs — moves to files SKILL.md links to. Claude only follows those links (with the Read tool) when actually needed.
This is the same instinct that drives any good README: keep the top of the file short and skimmable. Put the depth where someone who needs it can find it.
Four different things often get confused. Pick the right one and your tool feels inevitable; pick the wrong one and you'll fight it forever.
| Primitive | What it is | When to use |
|---|---|---|
| Skill | A markdown recipe Claude reads when triggered | The same kind of workflow comes up repeatedly and you want to encode the how |
| Memory | Persistent files holding facts about user / project | You want Claude to remember non-obvious things across sessions (preferences, context, decisions) |
| Hook | Shell command in settings.json, fires on events |
Something must run automatically every time X happens (after commits, on file change) |
| Agent | A sub-task Claude delegates | A bounded job worth running in a separate context (research, parallel writes, focused builds) |
The quick decision flowchart:
Try the picker below — it asks you the same four questions one at a time and shows what to reach for.
youtube-transcriptThe youtube-transcript skill ships with the CLI, is tiny, and does one thing well — a perfect example of the form. Here's what it looks like under the hood.
name and description. The description names the trigger phrases — "transcript", "subtitles", "captions" — and the URL format hint.scripts/get_transcript.py that the body references.Total file size: about 50 lines. Total job: extract a YouTube transcript in one consistent shape, every time. No more, no less.
Skills come in two broad shapes. The minimal one fits on a phone screen. The structured one references supporting files. Both are valid — pick the shape that fits how often you'll touch the skill and how big the recipe really needs to be.
Two skill styles. The minimal one fits on a phone screen; the structured one is what book-builder itself looks like under the hood. Both are valid — pick the shape that fits how often you'll touch the skill.
/Users/daffy/... baked in makes the skill non-portable. Fine for personal skills, brittle for shared ones.templates/ or references/ and have SKILL.md link to them.