Claude Code Skills: How to Build Reusable AI Workflows

Claude Code skills are markdown files stored in ~/.claude/skills/ that define reusable, step-by-step workflows. When Claude starts a session, it reads these files and follows them as process instructions. Unlike one-off prompts, skills enforce the same behavior every time -- across sessions, across projects, across team members. You create a .md file, define your workflow steps, and Claude treats it as an operating procedure.

Claude Code Skills vs Prompts -- What's the Difference?

A prompt tells Claude what to do. A skill tells Claude how to work.

Think of it like cooking. "Make dinner" is a prompt. A recipe with ingredients, temperatures, timing, and plating instructions is a skill. Both get you food. Only one gets you consistent results.

Prompts are great for one-off tasks. But the moment you find yourself repeating the same instructions across sessions -- "always write tests first," "always check for regressions before committing," "always brainstorm before building" -- that's a skill waiting to be extracted.

The practical difference:

• Prompts live in your head. You retype them. You forget steps. Quality drifts.
• Skills live in a file. Claude reads them every session. Quality is locked in.

I built over 50 skills across 160+ Claude Code sessions. Most of them were bad. The good ones share a pattern: they encode a process I was already doing manually, just more consistently than I could do it from memory.

How to Create Your First Claude Code Skill

File location

Skills live in ~/.claude/skills/. Create the directory if it doesn't exist:

mkdir -p ~/.claude/skills

Basic structure

A skill file is a markdown document with a header section and workflow steps. Here's the minimal format:

# Skill Name

Description: One sentence explaining when to use this skill.

## Steps

1. First thing Claude should do
2. Second thing Claude should do
3. Decision point or checklist
4. Final verification

How Claude discovers skills

When Claude Code starts a session, it reads every .md file in ~/.claude/skills/. Skills become available immediately. You don't need to register them, import them, or configure anything. Drop a file in the directory, start a new session, and Claude knows about it.

You can also reference skills from your CLAUDE.md file. This is how you create enforcement rules like "always use the TDD skill before writing implementation code." More on that in the advanced section.

Five Production-Tested Claude Code Skill Examples

These are the five skills that survived 160+ sessions. I've cut, rewritten, and tested each one across dozens of projects. They're complete files -- copy them directly into ~/.claude/skills/.

1. Brainstorming

The single most important skill. It prevents Claude from jumping straight to code before understanding what you actually want.

# Brainstorming

Description: Explore intent and requirements before writing any code.
Use when: Starting any new feature, component, or behavior change.

## Process

1. STOP. Do not write code yet.
2. Read the user's request carefully. Identify what they want
   to achieve, not just what they asked for.
3. Ask 2-3 clarifying questions about:
   - Scope: What's included and what's explicitly not?
   - Constraints: Performance, compatibility, dependencies?
   - Success criteria: How will we know this works?
4. Propose 2-3 approaches. For each one, name:
   - The approach in one sentence
   - The main tradeoff
   - Why you'd pick it or skip it
5. Wait for the user to pick an approach or redirect.
6. Only after agreement: proceed to implementation.

## Hard Rules
- Never skip this for "simple" changes. Simple changes
  have the highest rate of wrong assumptions.
- If the user says "just do it," still state your assumptions
  before writing code. One sentence is enough.

2. Test-Driven Development

This skill enforces the red-green-refactor cycle. It catches the most common Claude failure mode: writing code that works in theory but breaks in practice because nobody tested it.

# Test-Driven Development

Description: Red-green-refactor cycle for every implementation.
Use when: Implementing any feature or fixing any bug.

## Process

1. Before writing ANY implementation code, write a failing test
   that describes the expected behavior.
2. Run the test. Confirm it fails. If it passes, your test
   is wrong -- it's not testing the new behavior.
3. Write the minimum implementation code to make the test pass.
   No extra features, no premature abstractions.
4. Run the test. Confirm it passes.
5. Refactor if needed. Run the test again after refactoring.
6. Repeat for the next behavior.

## Hard Rules
- Never write implementation before a failing test exists.
- Never skip tests because the change is "too simple."
- If a test is hard to write, the interface is probably wrong.
  Fix the interface, not the test.
- Run the full test suite before claiming done.

3. Systematic Debugging

This one prevents the "try random things until it works" approach. Claude is especially prone to this -- it'll change three things at once and claim the bug is fixed without understanding what actually went wrong.

# Systematic Debugging

Description: Structured approach to finding and fixing bugs.
Use when: Any bug, test failure, or unexpected behavior.

## Process

1. READ the error message. The whole thing. Don't skip stack
   traces, warnings, or context lines.
2. Form a hypothesis. State it explicitly:
   "I think the bug is X because of Y."
3. Find evidence. Don't fix yet. Confirm your hypothesis by:
   - Reading the relevant source code
   - Checking recent changes (git log, git diff)
   - Reproducing the exact failure
4. Fix the ROOT CAUSE, not the symptom. If you're adding a
   null check, ask why the value is null in the first place.
5. Verify the fix by running the failing test or reproducing
   the original error scenario.
6. Check for similar bugs. If this broke here, does the same
   pattern exist elsewhere?

## Hard Rules
- Never change code without a hypothesis.
- Never change more than one thing at a time.
- "It works now" is not verification. Explain WHY it works.

4. Verification Before Completion

This is the guardrail that catches everything else. It prevents Claude from saying "done" before actually proving it.

# Verification Before Completion

Description: Prove it works before claiming done.
Use when: About to claim work is complete, fixed, or passing.

## Process

1. STOP before saying "done," "fixed," "complete," or
   "all tests pass."
2. Run the actual verification commands:
   - Tests: run the test suite, paste the output
   - Build: run the build command, confirm zero errors
   - Lint: run the linter if one exists
3. Check for regressions:
   - Did any previously passing tests break?
   - Did the build size change unexpectedly?
   - Are there new warnings?
4. Show evidence. Paste the actual command output.
   "All tests pass" without output is not verification.
5. Only after evidence is shown: report completion.

## Hard Rules
- Evidence before assertions. Always.
- If you can't run the verification command, say so.
  Don't guess at the result.
- A passing test suite with new warnings still needs
  to be reported. Warnings are future bugs.

5. Writing Plans

For anything that takes more than a few minutes, writing a plan first prevents the "I'm 80% done and just realized I need to redo everything" problem.

# Writing Plans

Description: Break complex work into tasks before coding.
Use when: Any task with 3+ steps or multiple files.

## Process

1. Define the goal in one sentence.
2. List every file that will be created or modified.
3. Break the work into sequential tasks. Each task should:
   - Have a clear deliverable
   - Be independently testable
   - Take no more than 10-15 minutes
4. Identify dependencies between tasks. Order them so
   each task builds on the last.
5. Flag risks: what could go wrong? What assumptions
   are we making?
6. Present the plan. Wait for approval before starting.

## Hard Rules
- Plans are living documents. Update them when reality
  diverges from the plan.
- If a task is taking 2x longer than expected, stop and
  re-evaluate the approach.
- Never skip the plan for "quick" multi-file changes.
  Those are the ones that break things.

How to Invoke Claude Code Skills

Automatic invocation

Claude reads the skills directory at session start. If you've described clear trigger conditions in each skill (the "Use when" line), Claude will apply the right skill at the right time without being asked. The brainstorming skill triggers when you request a new feature. The debugging skill triggers when there's an error. This is the ideal state -- skills working silently in the background.

Manual invocation

Sometimes you want to force a specific skill. Just say it:

• "Use the brainstorming skill before we start this."
• "Follow the TDD process for this fix."
• "Run verification before you call this done."

CLAUDE.md enforcement

The most powerful pattern is referencing skills in your CLAUDE.md file. This creates hard rules that apply to every session:

# In ~/.claude/CLAUDE.md

## Skill Enforcement
- Before building any feature: use the brainstorming skill
- Before writing implementation code: use the TDD skill
- Before claiming work is done: use the verification skill
- Never skip a skill for "simple" changes

This turns individual skills into an enforced workflow. Claude reads CLAUDE.md at session start and treats these as operating rules.

Skill chaining

Skills work best in sequence. Here's the chain I use for new features:

brainstorming -> writing-plans -> TDD -> verification

And for bug fixes:

systematic-debugging -> TDD -> verification

Each skill hands off naturally to the next. Brainstorming produces requirements. Writing plans turns requirements into tasks. TDD turns tasks into tested code. Verification confirms it all works.

Advanced Claude Code Skill Patterns

Skills with checklists

For skills that need every step confirmed, use explicit checkboxes in the process. Claude will work through them in order and won't skip ahead:

## Checklist
- [ ] Tests written and failing
- [ ] Implementation complete
- [ ] All tests passing
- [ ] No new warnings
- [ ] Build succeeds

Skills that reference other skills

A skill can tell Claude to invoke another skill. The writing-plans skill might end with "now execute the plan using the TDD skill for each task." This creates workflow composition without complex tooling.

Project-specific vs global skills

Global skills go in ~/.claude/skills/ and apply everywhere. But you can also put skills in a project's .claude/skills/ directory for project-specific workflows. A deployment skill for one project won't pollute another project's skill set.

When NOT to use a skill

Not everything needs a skill. If you're asking Claude a question, exploring an idea, or doing a true one-off task, skip the formality. Skills add value when you're doing the same type of work repeatedly. If you'll only do it once, a prompt is fine.

Building Your Own Claude Code Skills

Here's the process that actually works:

1. Start from a workflow you already repeat. Don't invent new processes. Extract the one you're already doing manually. If you catch yourself saying "I always do X before Y," that's a skill.
2. Write it like instructions for a junior developer. Be explicit about decision points. "If the test passes on the first try, your test is probably wrong" is the kind of instruction that prevents real mistakes.
3. Test it across 5+ sessions before trusting it. A skill that works once might just be coincidence. A skill that works across projects and contexts is actually good.
4. Iterate where Claude deviates. When Claude skips a step or misinterprets an instruction, that's feedback. Rewrite that step to be more explicit. The best skills are the ones where every sentence exists because Claude got it wrong without it.

The goal is not to write perfect skills on the first try. The goal is to write skills that get better every time Claude bumps into a new edge case. Treat them like code: version them, test them, improve them.