SOP → SKILL.md
Build-along · ~12 min at your own keyboard
A skill is a checklist Claude loads on demand: a SKILL.md file describing when to use it and exactly what to do. Anything you've explained twice — how you quote, how you label email, how you write the Friday update — is a skill waiting to be written. Start from a complete working file and change it; the next lesson explains the top section in detail. A minimal SKILL.md looks like this: --- name: weekly-crew-update description: Use when asked for the weekly crew update or Friday update. --- 1. Read this week's files in job-notes/. 2. Write three sections: done, blocked, need. 3. At most two bullets per section, plain text-message tone. 4. End with one ask and a deadline. The part between the --- lines is the frontmatter: name and description. The description is how Claude decides when to use the skill.
The long version: Writing a skill ↗
Mac: Mac: mkdir -p .claude/skills/<name> in Terminal.
Windows: Windows: in PowerShell run mkdir .claude\skills\<name>. Check the file is SKILL.md, not SKILL.md.txt.
Do this
0/4Checkpoints
- ▸You should now see .claude/skills/<name>/SKILL.md in your folder.
- ▸You should now see your edited steps in the file.
- ▸You should now see a fresh session follow the skill without re-explaining.
The three ways this goes wrong
- The skill file is in the wrong place and never loads. — The path must be .claude/skills/<name>/SKILL.md, with the file named exactly SKILL.md.
- The skill runs but gets steps wrong. — Fix the steps by hand. You know the process; Claude guessed.
- Claude does not use the skill. — Check the --- lines are exact and the description says when to use it in the words you actually use, then restart the session.
Share what happened
Paste your whole SKILL.md (frontmatter and steps) and one line on what the fresh session did right without being told.
Strip API keys, passwords, and tokens before you paste. Swap them for [KEY].
🔒 Don't paste confidential, personal-health, or payment info.