7.1
What A Skill Actually Is
Why this exists
You met the word back in 1.8 and got a one-line definition. Now you're going to open one and find out it's less mysterious than it sounds — and that the mystery was doing real damage, because people treat skills as magic and then can't work out why theirs don't work.
The idea
A skill is a document. You could print it.
That's the whole thing, and it's the part people refuse to believe. Not software. Not a plugin in the programming sense. A markdown file with instructions in it.
Three parts:
| Part | What it does |
|---|---|
| Name | What it's called |
| Description | When to use it — this is the load-bearing one |
| Body | The actual instructions |
Here's the mechanism, and it explains every skill that's ever failed to fire: Claude reads the descriptions, decides which one applies, and then follows that body.
So a skill with a brilliant body and a vague description never runs. The description isn't a summary — it's the trigger. "Formats documents" will sit there unused. "Use when the user asks to turn meeting notes into a client-ready summary" gets picked up, because it says when.
That single fact fixes most broken skills, and it's why 7.5 exists.
Why bother at all? Because you already repeat yourself. Every time you explain the same process to Claude — how you want a report laid out, the steps for adding a closer, what a good escalation message contains — you're writing an instruction you've written before. A skill is that instruction, written once, properly, and then followed consistently instead of re-explained inconsistently.
The difference between explaining and a skill is the difference between telling someone how to do it and handing them the procedure.
They're plain files on your machine. You can read them, edit them, copy them, delete them. Nothing is hidden. That's worth internalising now because the next four lessons all involve reading someone else's skill and deciding whether to trust it — and you can only do that because it's a document you can read.
Do
- Find the skills available to you. Ask Claude: "Where do my skills live and what do I have?"
- Open one in an editor. An actual file, not a description of one.
- Identify the three parts: name, description, body.
- Read the description and ask yourself: when would this fire? Is it obvious, or would you have to guess?
- Find a second skill with a weaker description. Note the difference.
- Copy a skill file into
annotated-skill.mdand add your own notes beside each part — what it does, why it's there, what would happen without it. - Write one line at the bottom: what would make this skill never fire?
- Now list three things you've explained to Claude more than once. Those are your first candidates for 7.4.
Step 7 is the check that you've got the mechanism. If your answer isn't something about the description, reread the idea.
Done when
Never do
Don't treat a skill as something you can't read. It's a text file. Every time you're unsure what one does, open it — and if you can't tell what it does from reading it, that's a fact about the skill, not about you.