← Back to blog

How to Build Claude Code Skills That Actually Work

What You'll Learn

By the end of this guide, you'll know how to build Claude Code skills that trigger when they should, stay under context limits, and scale from a 20-line helper to a multi-file production system. Not the basics. The decisions that make a skill actually work versus break silently while you wonder why Claude is ignoring it.

I've built over 30 skills across four brands at this point. Some of them are single-file utilities. Some are full pipelines with researchers, writers, and reviewers working in sequence. The pattern I'm going to walk you through is the one that survived all of them.

Prerequisites

You need Claude Code installed and running. That's it. No special packages, no build tools.

Skills live in one of two places:

  • Personal: ~/.claude/skills/<skill-name>/SKILL.md
  • Project: .claude/skills/<skill-name>/SKILL.md inside any repo

Personal skills follow you everywhere. Project skills travel with the repo, so your team gets them through git. Pick based on who needs the skill.

Step 1: Write the Description First

This is the most important line in your entire skill. Not the body. Not the instructions. The description.

Here's why: Claude Code reads only the description at startup. It loads the full SKILL.md body only when a task matches that description. A weak description means your skill never fires. A broad description means it fires on everything and gets in the way.

Bad description:

description: Helps with writing tasks

That matches everything. Claude will load this skill when someone asks for a commit message.

Good description:

description: >
  Weekly business review generator. Reads project files, git history,
  and task lists to produce a structured review with wins, blockers,
  and next-week priorities. Triggers on "weekly review", "week in review",
  "what happened this week", or /weekly-review.

That's specific. It names the triggers. Claude knows exactly when to load it.

The rule: write the description like you're writing a search query that should match your skill and nothing else.

Step 2: Structure the SKILL.md

The frontmatter goes at the top. The body is your instruction set. Anthropic's official best practices say to keep the body under 500 lines. I've found that anything over 300 starts to degrade quality, especially on smaller models.

Here's the skeleton:

---
name: my-skill
description: >
  One paragraph. Specific triggers. What it does, when it fires.
---

# Skill Name

One sentence: what this skill does.

## Process

### Step 1: [Action]
[Clear instructions]

### Step 2: [Action]
[Clear instructions]

## Rules
- [Hard constraints Claude must follow]
- [Things to never do]

Notice what's not there: no lengthy explanations of why the skill exists, no background context about the domain, no examples of every edge case. That stuff goes in reference files.

Step 3: Move Heavy Content to References

This is where most people go wrong. They stuff everything into SKILL.md and wonder why Claude gets confused or forgets instructions halfway through.

Anthropic's docs are clear on this: keep references one level deep. That means:

my-skill/
├── SKILL.md              # Instructions (under 500 lines)
└── references/
    ├── templates.md      # Output templates
    ├── rules.md          # Scoring rubrics, checklists
    └── examples.md       # Sample inputs/outputs

Then in SKILL.md, you write: "Read references/rules.md before scoring." Claude follows the path and loads the file when it needs it. Not at startup. Not all at once. When the instruction says to.

I tested this with a scoring skill that had 150 lines of rubric. Inline, Claude would forget rules by the end of the post. Split into a reference file, it nailed every criterion. The context window is real.

Step 4: Add Entry Points

A good skill handles more than one scenario. Use a table:

## Entry Points

| User Says | What Happens |
|-----------|-------------|
| "run my weekly review" | Full review flow |
| "just show this week's wins" | Wins summary only |
| "what's blocking me" | Jump to blockers list |

This does two things. It tells Claude how to route different requests. And it gives you a natural way to make the skill flexible without making it bloated. Each entry point can skip or include steps as needed.

Step 5: Write Anti-Hallucination Rules

Skills that generate output (templates, schema, configurations) need explicit guardrails. Without them, Claude fills gaps with plausible-sounding garbage.

The pattern that works:

## Rules

- NEVER invent business information. Use [PLACEHOLDER] if unknown.
- NEVER generate schema types from memory. Read references/schema-templates.md first.
- NEVER fabricate statistics or claim specific percentages.
- ALWAYS verify file paths exist before referencing them.

Capitalize NEVER and ALWAYS. It sounds dramatic but it measurably reduces hallucination. I ran the same skill with and without capitalized constraints. The lowercase version hallucinated a phone number. The uppercase version used the placeholder.

Step 6: Test on Every Model You'll Use

Anthropic's docs recommend this explicitly. A skill that works perfectly on Opus might fall apart on Haiku. The body might be too long for smaller context windows. The instructions might be too nuanced for faster models.

Test checklist:

  • Does it trigger from the description? (Say something that should match, see if it loads)
  • Does it follow the full process? (Don't just test the happy path)
  • Does it read reference files when told to?
  • Does it respect the Rules section?
  • Does it handle the "I don't have enough info" case gracefully?

If a skill doesn't trigger, the problem is almost always the description. Not the body. Not the instructions. The description.

From Simple to Production

Here's the progression I use:

→ Level 1 (20 lines): Single SKILL.md, one process, no references. Good for personal utilities.

→ Level 2 (100-200 lines): SKILL.md with a references folder. Templates, rules, or examples split out. Good for team skills.

→ Level 3 (multi-skill system): An orchestrator skill dispatching specialist skills, each with their own references. Shared brain files for context. Good for production pipelines.

You don't start at Level 3. You get there when a Level 2 skill outgrows its single file. The jump from 1 to 2 is "I need a reference file." The jump from 2 to 3 is "I need a second skill that talks to this one."

Troubleshooting

My skill never triggers?

Check the description. Is it specific enough to match your prompt but not so broad it matches everything? Add explicit trigger phrases: "Triggers on 'weekly review', 'week in review', or /weekly-review."

Claude forgets instructions halfway through?

Your SKILL.md is probably too long. Move content to reference files. Aim for under 300 lines in the main body.

Claude ignores my Rules section?

Put Rules near the top or immediately after the Process section. If it's buried at the bottom of a long file, it gets less attention. Capitalize NEVER/ALWAYS.

The skill works on Opus but not Haiku?

Simplify the instructions. Shorter sentences. Fewer conditional branches. Haiku needs clearer, more direct instructions than Opus does.

Next Steps

Build one. Start with something you explain to Claude at least once a week. That repeated explanation is a skill waiting to happen. Write the description first, keep the body tight, split heavy content into references, and test it on the model you actually use.

If you want to see production-grade skills in action, check out the Digital Plan Vault skills collection for examples ranging from single-file utilities to full multi-skill pipelines.

Frequently Asked Questions

Where do Claude Code skills live on my machine?

Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md. Project skills go in .claude/skills/<skill-name>/SKILL.md inside any git repo. Personal skills are always available. Project skills are only available when you're working in that repo.

How long should a SKILL.md file be?

Anthropic recommends under 500 lines. In practice, under 300 lines in the main body works better. Move templates, rubrics, examples, and anything over 50 lines into a references/ folder and have Claude read them when needed.

Why does my skill trigger on the wrong prompts?

Your description is too broad. Claude Code uses semantic matching on the description to decide when to load a skill. Add specific trigger phrases and narrow the scope. "Helps with writing" matches everything. "Weekly review generator for any project, triggers on /weekly-review or 'run my weekly review'" matches only what you want.

Can skills call other skills?

Yes. An orchestrator skill can reference other skill files and dispatch work to them. This is the production pattern for multi-step pipelines: one skill coordinates, specialist skills do the work.