Every small business has a few jobs that are done the same way every time, by whoever remembers how. The weekly newsletter. Onboarding a new client. The month-end tidy-up. The steps live in someone's head, or in a document nobody opens.
A skill is that document, written so Claude Code can follow it. And unlike the binder on the shelf, Claude actually reads it, at the moment the job comes up.
What a skill is
A skill is a folder with a file called SKILL.md inside. The file has two parts: a short header that says what the skill is for, and a set of instructions. Claude uses a skill in one of two ways:
- Automatically, when what you ask matches the skill's description.
- On demand, when you type a slash and its name, like
/newsletter-draft.
The useful trick is that the instructions only load when they're needed. Until then, Claude sees just the name and description. So unlike CLAUDE.md, which loads every session, a long procedure in a skill costs almost nothing on days you don't use it.
Skills in Claude Code follow the Agent Skills open standard, so the same basic format works in other tools that support it. Claude Code adds a few extras on top.
Where skills live
| Type | Path | Available in |
|---|---|---|
| Personal | ~/.claude/skills/skill-name/SKILL.md | All your projects on this computer |
| Project | .claude/skills/skill-name/SKILL.md | This project, for anyone who has it |
| Plugin | Inside an installed plugin | Wherever the plugin is turned on |
If a personal and a project skill share a name, the personal one wins. One catch: Cowork and cloud sessions don't read the skills folder on your computer. For those, you enable the skill on your claude.ai account instead.
The anatomy of a skill
Here's the smallest useful skill:
---
description: Formats show notes for a podcast episode. Use when the user asks for show notes or an episode summary.
---
1. List the guest, three key points and every link mentioned.
2. Keep it under 200 words.
The part between the --- lines is the frontmatter, a short block of settings at the top of the file. Everything after it is the body: the procedure itself. Bigger skills add folders next to SKILL.md for reference material and scripts.
In Claude Code, every frontmatter field is optional, but you should always write a description. These are the ones you'll actually use:
| Field | What it does |
|---|---|
name | The command name. Defaults to the folder name |
description | What the skill does and when to use it. This is the trigger |
when_to_use | Extra trigger phrases, added to the description |
argument-hint | A hint shown while you type the command, like [topic] |
disable-model-invocation | Set to true so only you can start it, never Claude on its own |
user-invocable | Set to false to hide it from the menu, so only Claude uses it |
allowed-tools | Tools Claude can use without asking, during the turn that runs the skill |
There are a few advanced fields too, such as running a skill in a separate sub-agent, and the skills docs list them all. If you plan to upload a skill to claude.ai or use it through the API, stick to name, description, license, compatibility, metadata and allowed-tools; those places reject other fields, and they require name and description. Names should be lowercase letters, numbers and hyphens, up to 64 characters.
The description decides when a skill loads
In every session, Claude sees a list of your skills: each name and description, nothing more. When your request matches a description, Claude loads that skill's full instructions and follows them. The description is the whole trigger, so write it like it matters:
- Say what it does, then when to use it. "Drafts the weekly newsletter from this week's notes. Use when the user asks for a newsletter, this week's issue, or to turn notes into an issue."
- Use the words you'd actually type. If you say "issue," not "edition," put "issue" in the description.
- Write in the third person. Anthropic's guidance is to describe what the skill does ("Drafts the newsletter"), not to speak as it ("I can help you draft").
- Put the main use first. The description (plus
when_to_use) is cut off at 1,536 characters in the list, and with many skills installed, Claude Code drops descriptions for the ones you use least.
If a skill has side effects, like sending, publishing or deleting, add disable-model-invocation: true. Then Claude can't start it on its own; it only runs when you type the command. Its description also stops taking up space in Claude's list.
Bundling reference files and scripts
A skill folder can hold more than SKILL.md: a voice guide, templates, examples, a script. Link to them from SKILL.md so Claude knows what each file is for and when to open it. Claude reads them only when the task needs them; scripts are run, not read.
Anthropic suggests keeping SKILL.md under 500 lines and moving detail into separate files. Keep links one level deep, from SKILL.md straight to the file, so Claude doesn't have to chase a trail.
To run a bundled script reliably, refer to it with ${CLAUDE_SKILL_DIR}, which Claude Code replaces with the skill's own folder, wherever you happen to be working.
Example 1: the weekly newsletter draft
The folder:
.claude/skills/newsletter-draft/
├── SKILL.md
├── voice.md (how you sound, with do and don't examples)
└── template.md (the issue structure)
---
name: newsletter-draft
description: Drafts the weekly newsletter issue from this week's notes in the house voice. Use when the user asks for a newsletter draft, this week's issue, or to turn notes into an issue.
argument-hint: [optional theme]
---
# Weekly newsletter draft
Theme from the user, if any: $ARGUMENTS
## Steps
1. Read every file in notes/ changed in the last 7 days. If there are none, stop and say so.
2. Read [voice.md](voice.md) and the two most recent issues in issues/ for tone.
3. Choose one main idea. Use the user's theme if they gave one.
4. Write the issue using [template.md](template.md): three subject line options,
an opening, the main piece, two quick links, and the sign-off.
5. Save it to drafts/YYYY-MM-DD-slug.md and show me the subject lines.
## Rules
- 600 to 900 words.
- Every fact, number and quote must come from the notes. If it isn't there,
leave it out or mark it [CHECK].
- Never send, schedule or publish anything. Draft only.
Ask "can you draft this week's issue?" and Claude should pick it up on its own. Or type /newsletter-draft pricing mistakes to set the theme yourself. The last rule matters: a skill should draft, and a human should press send.
Example 2: the client onboarding checklist
This one creates files, so it's set to run only when you call it. It also uses named arguments: the arguments field gives each position a name you can use in the body.
.claude/skills/client-onboarding/
├── SKILL.md
├── checklist.md (your standard onboarding tasks, with day offsets)
└── welcome-email.md (the welcome email template)
---
name: client-onboarding
description: Sets up a new client folder, onboarding checklist and welcome email draft.
disable-model-invocation: true
argument-hint: [client name] [start date]
arguments: [client, start]
---
# Onboard $client, starting $start
## Steps
1. Make a short slug from the client name (lowercase, hyphens).
Create clients/[slug]/.
2. Copy [checklist.md](checklist.md) to clients/[slug]/onboarding.md.
Fill in the client name, and turn each task's day offset into a real date
counted from the start date.
3. Draft the welcome email from [welcome-email.md](welcome-email.md) into
clients/[slug]/welcome-email.md. Fill in only what you know. Mark gaps [ASK].
4. Add a row to clients/index.md: name, start date, status "onboarding".
5. End with a summary: files created, and every [ASK] gap.
## Never
- Send the email. I review and send it myself.
- Store payment details, passwords or ID documents in these files.
Run it with /client-onboarding "Harbor Studio" 2026-07-15. The quotes keep a two-word name together as one argument.
Test it, then iterate
A skill that loads isn't the same as a skill that works. Test both.
- Start a fresh session. Leftover context from writing the skill hides gaps in the instructions.
- Check that Claude sees it. Ask "What skills are available?" or run
/skillsto see the list. - Try prompts that should trigger it, and some that shouldn't. "Draft this week's issue" should; "fix a typo in last week's issue" probably shouldn't.
- Compare with and without. Run the same request with the skill turned off (in
/skills, highlight it and press Space until it reads off). If the output isn't clearly better with the skill, the instructions aren't pulling their weight. - Fix the page, not the chat. When Claude gets something wrong, edit
SKILL.md. Claude Code notices changes to skill files during a session, so no restart is needed.
Two common problems and their fixes. If a skill fires when you don't want it, make the description more specific or add disable-model-invocation: true. If Claude follows a skill at first and then drifts in a long session, put the most important rules near the top; after the conversation gets compacted (summarized to save space), Claude Code may keep only the start of a skill, so run it again to reload it.
For a more structured approach, Anthropic's skill-creator plugin runs test prompts with and without the skill, grades the results and suggests description tweaks. Install it from inside Claude Code:
/plugin install skill-creator@claude-plugins-official
Short, single-file prompts you only ever trigger yourself can also live as custom slash commands. And if a skill is going to touch a lot of files, try it in plan mode first.
Pick the job you've explained most often this year. Write it down, run it five times, and fix the page every time Claude gets it wrong. That's the method.
Sources
- Extend Claude with skills, Claude Code docs
- Skill authoring best practices, Claude Platform docs
- Best practices for Claude Code, Claude Code docs
- Extend Claude Code, Claude Code docs
- Agent Skills, the open standard