Skills & Commands

Let's clear up the mystique. A skill is a text file. That's it.

It's a file containing instructions that Claude reads when a specific situation comes up. Think of it like a cheat sheet you'd give a new team member: "When someone asks you to do X, here's exactly how we do it."

Without skills, Claude relies on its general training. It'll do a decent job at most things. But "decent" and "exactly how you want it" are different. Skills close that gap for tasks you do repeatedly.

Claude Code gives you two ways to create skills, depending on how much structure you need.

The simple way: Create a .md file (a plain text file with a .md extension) in ~/.claude/commands/. The file name becomes the slash command. review.md becomes /review. This still works and is fine for getting started.

The recommended way: Create a directory in ~/.claude/skills/<name>/ with a SKILL.md file inside. This supports metadata at the top of the file (name, description, allowed tools) and is the official approach going forward. Commands and skills have been unified — both work the same way, but the skills/ path is where new features land.

Claude Code also ships with built-in skills you can use right away: /batch (parallel changes across files), /simplify (review code quality), /debug (troubleshoot issues), and /init (auto-generate a CLAUDE.md by analysing your codebase). Type / in any session to see what's available.

Where the folders live

The setup prompt creates the commands directory for you:

~/.claude/commands/

If you're setting things up manually, create it with mkdir -p ~/.claude/commands.

Let's look at one in detail so you understand how it works. The setup prompt creates a writing review skill at ~/.claude/commands/review.md. Here's what's inside:

Review the provided text for clarity, conciseness, and effectiveness.

Focus on:
1. Sentences that are unclear or could be misread — suggest specific rewrites
2. Unnecessary words or phrases that can be cut without losing meaning
3. Claims or arguments that aren't supported — flag what's missing
4. Tone consistency — does anything feel out of place for the intended audience?

Rules:
- Maximum 7 feedback points. Prioritise the most impactful ones.
- For each issue, provide the specific replacement text, not just a description of the problem.
- If the writing is genuinely good, say so briefly and don't manufacture criticism.

How it works

When you type /review in Claude Code, it looks in ~/.claude/commands/ for a file called review.md, reads it, and uses those instructions to handle your request. The instructions override Claude's default approach with your specific process.

That's the entire mechanism. No APIs, no configuration. A text file and a slash command.

Here are skills that have been tested across different workflows and consistently earn their token cost. Here's the overview — then we'll walk through each one.

/summarise — Structured Summaries

Problem it solves: Claude's default summaries vary wildly in format and length. Sometimes you get three sentences, sometimes three paragraphs. Sometimes it includes analysis you didn't ask for.

File: ~/.claude/commands/summarise.md

Summarise the provided content using this structure:

**Key Points** (3-5 bullet points, one sentence each)
- Focus on decisions, conclusions, and action items
- Skip background, methodology, and context the reader already knows

**Notable Details** (only if genuinely important)
- Anything surprising, concerning, or time-sensitive

Rules:
- Total summary should be under 150 words
- If the source material is short (under 500 words), the summary should be proportionally shorter — don't pad it
- Never include your own analysis or opinions unless explicitly asked

/draft — First Drafts That Are Actually Useful

Problem it solves: When you ask Claude to write something, it tends to produce polished-sounding but generic output. You end up rewriting most of it. This skill produces a rougher draft that's closer to what you'd actually write — easier to edit, faster to finalise.

File: ~/.claude/commands/draft.md

Create a first draft based on the brief provided.

Approach:
- Write at about 80% polish. Good enough to edit, not so polished that it sounds generic.
- Match the tone and register described in the brief. If none specified, use the tone from my CLAUDE.md preferences.
- Structure the content logically but don't over-format. Headings where they help, not everywhere.
- Include placeholders like [SPECIFIC EXAMPLE NEEDED] or [VERIFY THIS CLAIM] where I'll need to add my own knowledge.

Rules:
- Don't include a title unless asked.
- Don't add a conclusion that summarises what the draft just said.
- Length: follow the brief. If no length specified, aim for concise — better to be too short than too long.

/decide — Decision Analysis

Problem it solves: When you're stuck between options, Claude's default response is to list pros and cons of each. That's fine but doesn't push toward a decision. This skill structures the analysis around actually choosing.

File: ~/.claude/commands/decide.md

Help me make a decision. I'll describe the options and context.

For each option:
1. **Best case** — what happens if this goes well
2. **Worst case** — what happens if this goes badly
3. **Most likely case** — what realistically happens
4. **Reversibility** — how easy is it to undo this choice

Then:
- **My recommendation** — which option I'd pick and the one specific reason why
- **What would change my recommendation** — the one piece of information that, if different, would make me pick a different option

Rules:
- Be opinionated. I'm asking for a recommendation, not a balanced non-answer.
- Keep the entire analysis under 300 words.
- If the options are so close that it genuinely doesn't matter, say that.

/explain — Learn Something Properly

Problem it solves: Claude's default explanations often start too basic or too advanced. This skill adapts to your stated level and uses examples from domains you already understand.

File: ~/.claude/commands/explain.md

Explain the concept I'm asking about.

Process:
1. Start with a one-sentence plain-language definition
2. Give one concrete example that demonstrates the concept in action
3. Explain the "why" — why does this concept matter, or why does it work this way
4. Common misconception — one thing people often get wrong about this

Rules:
- Ask me one question first if you're unsure about my background level
- Use analogies from my work domain (check my CLAUDE.md for context)
- If the concept has prerequisites I might not know, flag them before explaining
- Keep the total explanation under 250 words unless I ask for more depth

/organise — File Management with Safety

Problem it solves: Letting Claude move files around is powerful but risky. This skill forces a "plan first, act second" pattern.

File: ~/.claude/commands/organise.md

Help me organise files in the specified directory.

Process:
1. First, scan the directory and list what's there (file types, approximate count, any obvious patterns)
2. Propose an organisation plan — folder structure, naming conventions, what goes where
3. WAIT for my approval before making any changes
4. After approval, execute the plan and show me a before/after summary

Rules:
- Never move, rename, or delete files without explicit approval
- If you're unsure where something belongs, put it in a folder called "_unsorted" rather than guessing
- Preserve original file names unless I specifically ask for renaming
- Don't create a README or index file for the new structure unless asked

You've now seen the pattern. A skill is:

1. A specific task you do repeatedly
2. A structured approach to that task (what to do, in what order)
3. Rules that prevent common problems (length limits, safety checks, format requirements)
4. A file in ~/.claude/commands/

When to create a skill

Create a skill when you notice yourself giving Claude the same instructions more than twice. If you've said "keep the summary under 5 bullet points" in three separate conversations, that's a skill waiting to be written.

Don't create skills for things you do once. Don't create skills that are so vague they don't change Claude's behaviour ("be helpful and thorough" — that's what Claude already does). A good skill has specific, testable instructions.

The template

[One line describing what this skill does]

Process:
1. [First step]
2. [Second step]
3. [Additional steps as needed]

Rules:
- [Rule that prevents a common problem]
- [Length or format constraint]
- [Safety check if the skill involves file operations]

Keep skills under 200 words. Longer skills cost more tokens to load and don't necessarily produce better results. If your skill is getting long, you're probably trying to handle too many cases. Split it into two skills instead.

Testing a skill

After creating a skill:

1. Run the slash command with a real task
2. Check whether Claude followed all the instructions
3. If it ignored something, make that instruction more specific
4. If it did something you didn't want, add a rule preventing it

Two or three rounds of testing is usually enough to get a skill working well.

Let's be transparent about the cost. Each skill file is loaded when you invoke the command. A 150-word skill is roughly 200 tokens. If you invoke three skills in a session, that's about 600 tokens spent on skill instructions.

Compare that to giving the same instructions manually: you'd type them out each time (consuming tokens from your side) and risk inconsistency (consuming more tokens in correction rounds). Skills are cheaper than the alternative they replace.

The five skills we installed above total approximately 800-1,000 tokens if invoked all at once — which you never would. In practice, you invoke one or two per session. That's 200-400 tokens for consistently better output.

You now have a toolkit. Five tested skills, the knowledge to build your own, and a clear understanding of when to create one. Your CLAUDE.md tells Claude how to behave. Your skills tell it how to perform specific tasks. Together, they make Claude Code feel less like a general-purpose chatbot and more like a tailored assistant that knows your playbook.

Next up: the automation layer. Hooks let things happen automatically — before and after Claude acts — without you having to ask. Module 7.