08 — Skills

Skills are Claude's internal how-tos — concrete procedures for recurring task types. The difference between a skill and a slash command: commands are explicit (you type /plan), skills are automatic (Claude recognizes the situation and applies the right procedure without being asked).

The Core Idea

A skill is a Markdown file that tells Claude how to handle a specific type of situation — with a precise sequence of steps, not general advice. When Claude encounters a matching context, it applies the skill automatically.

The result: consistent behavior without you having to re-explain your process every session. Write the procedure once. Claude follows it whenever the situation arises.

How Auto-Invocation Works

Skills are matched on context, not keywords. Claude reads the current situation — what you're asking, what's in scope, what just happened — and pulls the relevant skill if one exists.

A debugging skill might fire whenever Claude encounters a failing test. A planning skill might fire whenever you describe a new feature. You don't type a trigger word; Claude infers when the skill applies.

This is the key distinction from slash commands. Commands are deliberate invocations. Skills are ambient — they shape Claude's behavior without requiring you to remember to apply them.

You can also write skills with explicit gate conditions: a preamble that tells Claude exactly when (and when not) to invoke the skill. More on that below.

Skill Structure

Skills live in ~/.claude/skills/. Each is a Markdown file:

# Skill: Systematic Debugging

## When to apply
When a bug is non-obvious after reading the error message, or when
a fix has been attempted once and failed.

## Procedure
1. Verify infrastructure first — network, auth, env vars, API access
2. Read the full error message, not just the last line
3. Identify what changed recently (git log, recent edits)
4. Form a hypothesis before touching any code
5. Test the hypothesis with the minimal possible change
6. If the fix works, understand why before moving on

## Do not
- Jump to code changes before completing step 1
- Apply multiple fixes simultaneously
- Assume the error message is the root cause

The gate condition ("When to apply") is what makes this a skill rather than a generic instruction. Without a gate, the skill fires everywhere, which dilutes it.

Categories Worth Building

If you're starting from scratch, the highest-ROI skill categories are:

Workflow skills — how you want Claude to plan, execute, and verify work. A planning skill that always waits for confirmation before touching code. A verification skill that checks the actual production behavior, not a proxy for it.

Domain skills — deep context for your specific stack or domain. If you work in a specific framework, a skill that encodes how your team does things (naming conventions, file structure, patterns to avoid) will pay off on every feature.

Quality gates — skills that Claude applies before calling something done. Code review criteria, accessibility checks, performance considerations. Things you'd otherwise have to remember to ask for.

Communication skills — how Claude writes commit messages, PR descriptions, technical docs. Encode your style once; get consistent output forever.

Writing Your Own

A skill that works well has three properties:

Specific scope. It handles one type of situation, not a broad category. "How to debug failing tests" is better than "how to debug things."

Concrete steps. Numbered, ordered, unambiguous. "Verify infrastructure first" is concrete. "Be thorough" is not.

A clear gate. When should this skill fire? When should it not? Write that explicitly. A skill without a gate is an instruction that runs everywhere, which usually means it gets ignored everywhere.

Start with the thing you've explained to Claude three or more times. Write down how you actually want it handled, step by step. That's your first skill.

Skills Worth Installing

The superpowers plugin bundles most of the highest-ROI skills. Install it, then pick which to wire into your workflow.

brainstorming (superpowers) — fires when you're starting something new without a defined shape. Stops Claude from jumping to implementation before the problem is clear.
writing-plans (superpowers) — produces a structured plan doc before any code gets written. Invoke explicitly when a task spans multiple files and the path is unclear.
systematic-debugging (superpowers) — forces hypothesis-driven debugging. Fires when a bug is non-obvious or a fix has already failed once. Blocks the "try random things" loop.
verification-before-completion (superpowers) — verifies actual production behavior before Claude claims done. The difference between "tests pass" and "the thing works."
tdd-cycle (superpowers) — enforces RED / GREEN / REFACTOR discipline if you do TDD. Worth adding if you find Claude skipping the red phase.
frontend-design — design-review skill for UI work. Fires when building a new page or when you give visual feedback on existing UI.