Skills, explained by monkey
(plus a starter skill)
A skill is a saved set of instructions in a SKILL.md file. Claude pulls it in when it's relevant, or you run it yourself with /its-name. Here's a starter skill to paste, and everything that makes skills worth it.
If you paste the same long prompt again and again, it belongs in a skill. A skill is a folder with a SKILL.md file in it: a short description at the top, your instructions underneath. Claude always sees the name and description, and loads the full instructions only when your request matches the description or when you type / and the skill's name.
The starter skill: summarize-changes
This skill reads your uncommitted changes, sums them up in two or three bullet points and lists anything risky. First make its folder in your terminal:
mkdir -p ~/.claude/skills/summarize-changes
Then save this as ~/.claude/skills/summarize-changes/SKILL.md:
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice.
Now type /summarize-changes, or just ask "what did I change?" and Claude loads it by itself. Use it inside a git project, since it reads your changes with git.
What each part does:
- description: what the skill does and when to use it. Claude reads this to decide when to load the skill, so name the moments: what changed, a commit message, reviewing a diff.
- No name line? The folder name becomes the command, so this one is /summarize-changes. Set a name in the frontmatter and that's what you type instead.
- The line starting with ! runs git diff HEAD before Claude reads the skill, so your live diff is already pasted in when Claude starts.
- Everything under ## Instructions: what Claude does with it.
Got your own prompt you keep pasting? Ask Claude to turn it into a skill:
Here's a prompt I paste all the time: [paste it]. Turn it into a skill at ~/.claude/skills/[a-short-name]/SKILL.md, with a description that says what it does and when to use it.
Where skills live
- ~/.claude/skills/<name>/SKILL.md: all your projects.
- .claude/skills/<name>/SKILL.md: this project. Commit it and your team gets it too.
Type /skills to see everything you have. Add, edit or delete a skill and Claude Code picks up the change in the same session, with no restart.
Two ways a skill runs
- By itself: Claude loads it when your request matches its description.
- By you: type / and its name, like /summarize-changes.
Keep risky skills for yourself
A skill that deploys, sends a message or posts something shouldn't run just because Claude thought it fit. Add disable-model-invocation: true to the frontmatter and Claude can't run it on its own. Only you can, with /name:
---
description: Deploys the site to production.
disable-model-invocation: true
---
It works the other way too: user-invocable: false is for background knowledge that only Claude should use.
The ! trick
Write an exclamation mark followed by a command in backticks, and Claude Code runs that command before Claude reads the skill. The output is pasted into the instructions, so the skill always starts from fresh information, like a diff or a test result, instead of Claude having to go and look.
## Current changes
!`git diff HEAD`
Swap git diff HEAD for any command whose output you want Claude to start from.
Skills and slash commands are the same thing now
Custom slash commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both give you /deploy and work the same way. Your old command files keep working. A skill is a folder, though, so it can also hold extra files next to its SKILL.md.
Why a skill beats a long CLAUDE.md
Everything in CLAUDE.md loads into every session. A skill only puts its description there, and its body loads when it's used, so a long checklist costs almost nothing until you need it. Keep CLAUDE.md for the short rules that always apply, and move long how-tos into skills.
Gotchas
- After Claude compacts the conversation, only the first 5,000 tokens of each skill you've used come back. Put the important rules at the top.
- Got lots of skills? The list of descriptions gets about 1% of the context window, so some get cut short and Claude may stop matching them. Each description, plus when_to_use if you set it, is capped at 1,536 characters.
- Broken frontmatter (the part between the --- lines) means /name still works, but Claude can't match the skill by itself.
- Claude Code ships some skills of its own, like /code-review, /debug and /loop.
Monkey believe in you. Now go build.
follow @nocodemonkey
