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.

Here's a concrete example. Say you regularly ask Claude to review your writing. Without a skill, Claude gives generic feedback — "the introduction could be stronger," "consider varying sentence length." Polite, vague, not very useful.

With a review skill, Claude follows specific instructions: identify weak sentences and suggest replacement text, check for jargon the target audience won't know, flag claims that aren't supported by evidence, keep feedback under 5 bullet points. Same Claude, dramatically better output. Every time.

Claude Code's skill system uses two files for each skill. This seems redundant at first, but there's a good reason.

File 1: The command stub (.md file in ~/.claude/commands/) This is a short file that registers the slash command. It tells Claude Code: "this command exists, and here's where to find the full instructions." Think of it as the entry in a phone book — just a name and a pointer.

File 2: The skill file (.skill file in ~/.claude/skills/, or .md in ~/.claude/commands/) This is the full set of instructions. The actual knowledge, the step-by-step process, the rules. This is the cheat sheet.

For simple skills, you can put everything in a single .md file in ~/.claude/commands/. The two-file system is for more complex skills where you want to keep the registration lightweight and the instructions detailed.

Setting up the folders

If you haven't already:

mkdir -p ~/.claude/commands
mkdir -p ~/.claude/skills

Let's build one from scratch so you understand the anatomy. We'll create a writing review skill.

Step 1: Create the command file

Create ~/.claude/commands/review.md:

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.

Step 2: Use it

In Claude Code, type:

/review

Then paste or reference the text you want reviewed. Claude will follow the instructions in your skill file instead of doing a generic review.

What just happened

When you type /review, Claude Code 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, no installation steps. Create a text file, use the slash command. Done.

Here are skills that have been tested across different workflows and consistently earn their token cost. For each one, we'll explain what it does, why it helps, and give you the content to create the file.

/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.