How to Build a Claude Skill That Actually Loads When You Need It

A Claude Skill is a folder Claude Code auto-loads when your prompt matches it. The anatomy is four parts: a folder named after the skill, a SKILL.md file with YAML frontmatter at the top, an optional scripts/ folder for deterministic code, and an optional references/ folder for docs the skill should pull in. Get the description field right and Claude invokes the skill on its own. Get it wrong and the skill sits on disk forever. I have built 40+ Claude Skills for my own operations and for client work at Formaum. Here is how I build one that actually fires.

What a Claude Skill is

A Skill is a folder of instructions Claude Code loads into context when it decides the skill is relevant to your prompt. It is the difference between pasting the same 200-line procedure into chat every time and just saying "run the audit." If you want the conceptual version, I wrote a separate post on what Claude Skills are and why they exist. This post is the build tutorial.

Skills live in one of two places. Personal skills go in ~/.claude/skills/ and follow you across every project. Project skills go in .claude/skills/ inside the repo and travel with the codebase. Claude scans both at startup. Use project skills for anything tied to a specific client or stack. Use personal skills for procedures you run across every project.

The anatomy of a working skill

Every skill is a folder. The folder name is the skill name. Inside the folder, four things matter:

• SKILL.md . the only required file. YAML frontmatter at the top with name and description. The body is the procedure Claude follows when the skill fires.
• scripts/ . optional. Python or Node files for anything that needs to be deterministic. Math, file generation, API calls where you do not want the model improvising.
• references/ . optional. Long docs the skill body tells Claude to read on demand. Voice guides, API specs, client style rules. These do not load until the skill body points to them.
• templates/ . optional. HTML, markdown, or config templates the skill fills in. Useful for any skill that produces a deliverable with a fixed shape.

The thing most tutorials skip: the body of SKILL.md does not load until the skill is invoked. The frontmatter loads on every prompt. That is the whole game. The description has to be tight because it is paying context rent every single turn. The body can be as long as it needs to be because it costs nothing until you use it.

Step 1: Name it like a verb-noun

The folder name becomes the slash command. /audit, /callsheet, /proposal. Verb-noun or short single-verb. Lowercase, hyphens for multi-word, no spaces.

Bad names: helper, my-skill, assistant. Good names: review-pr, generate-invoice, debug-build. The name is the first signal Claude uses to decide if the skill is relevant. "helper" matches nothing because it could mean anything.

Step 2: Write the description (this is the whole job)

The description field is the single most important thing in your skill. Claude reads the description of every available skill on every turn. If your description matches the user's intent, the skill loads. If it does not, the skill never runs. People spend hours on the body and 30 seconds on the description and then wonder why the skill never fires.

Three rules:

1. Write it the way the user would ask for the task. If you would normally say "review this code," the description should contain the phrase "review code," not "perform a quality assessment of source files." Match the user's vocabulary, not your formal one.
2. Include trigger phrases explicitly. List the actual phrases that should fire the skill. "Triggers on /audit, 'audit this client,' 'run an audit on [name]'." Claude pattern-matches on these.
3. Stay under 200 characters when you can. The description is read every turn. Long descriptions cost context for no benefit. Tight and specific beats long and abstract.

Here is the frontmatter pattern I use:

---
name: audit
description: Generate problem-first workflow audits for client engagements. Creates styled HTML deliverables with SVG flow diagrams, gap analysis, and prioritised recommendations. Triggers on /audit, "audit [client]", "run an audit on [name]".
---

That is it. Two fields. The body comes after.

Step 3: Structure the body (when to use, how to use, examples)

The body is markdown. Claude reads it top to bottom when the skill fires. The structure that has worked across every skill I have shipped:

1. When to use this skill . one paragraph. Restate the trigger conditions. This is for Claude, not for you.
2. Inputs . what the skill needs from the user before it can run. Client name, file path, target metric. List them.
3. Procedure . numbered steps. Treat Claude like a new hire who has done this exact task once. Be specific. "Read the file at X. Extract the sections matching pattern Y. Write the output to Z."
4. Output format . what the deliverable looks like and where it goes. Include the file path, the markdown structure, and any naming convention.
5. Examples . one or two real (anonymized) runs. Examples beat instructions for steering output quality.
6. References . links to references/ files the skill should load only when needed. Voice rules, API docs, client-specific patterns.

Step 4: Test in actual conversation

Save the file, restart Claude Code, and trigger it three ways:

1. Explicit invocation. Type /your-skill-name and confirm it loads. If it fails here, the file is malformed.
2. Trigger phrase. Use one of the phrases from your description in a normal message. The skill should auto-invoke. If it does not, the description is too vague.
3. Negative test. Say something the skill should NOT match. If it fires anyway, your description is too broad and it will steal context from other skills.

Iterate on the description. Not the body. 90% of "my skill is not loading" problems are description problems.

A real skill walkthrough

Here is the skeleton of a comms-check skill I run before sending any client-facing message. It catches voice drift, banned phrases, and tone mismatches in under 10 seconds. I am showing the structure, not the full file.

~/.claude/skills/comms-check/
├── SKILL.md
├── references/
│   ├── voice-rules.md
│   ├── banned-phrases.md
│   └── approved-examples.md
└── scripts/
    └── score.py

And the top of SKILL.md:

---
name: comms-check
description: Review any client-facing message for voice, banned phrases, and tone before sending. Triggers on /comms-check, "comms check this", "review before I send", "is this on-brand".
---

# Comms Check

## When to use
Fire whenever a draft message is about to go to a client, a prospect, or a public surface (LinkedIn, Upwork, email). Skip for internal-only notes.

## Inputs
- The draft message (pasted or referenced by file path)
- Recipient context (client name, channel, stage of relationship)

## Procedure
1. Read references/voice-rules.md
2. Read references/banned-phrases.md
3. Score the draft on 5 axes: factual accuracy, voice match, banned-phrase hits, tone, length
4. Run scripts/score.py to produce the numeric summary
5. Return the score, a one-line verdict, and a revised draft if any axis scores under 4

## Output format
- Score table (5 rows, 1–5 each)
- Verdict line ("send," "revise," or "rewrite")
- Revised draft (only if needed)

## Examples
[two anonymized before/after samples]

Why this works. The description names the exact phrases I actually use. The body tells Claude what to load and when. The references are heavy (the voice guide is 2,000 lines) but they do not cost context until the skill runs. The script handles the deterministic scoring so Claude is not improvising numbers. The whole thing fires reliably because every piece earns its place.

Common mistakes

• Vague descriptions. "Helps with writing" matches everything and gets invoked for nothing. Specific verbs, real trigger phrases, named outputs.
• Stuffing the body with content that should be a reference. If your SKILL.md is 800 lines, you are paying full context cost on every invocation. Move the heavy stuff to references/ and link from the procedure.
• No examples. Examples steer output quality more than instructions do. One real before/after beats a paragraph of "be concise."
• Asking Claude to do math or generate IDs in the body. Mechanical work goes in scripts/. The body coordinates. The script computes.
• Naming it after the tool, not the job. /pandadoc-skill tells Claude nothing about when to fire. /send-contract does.
• Never testing the negative case. A skill that fires when it should not is worse than a skill that never fires. It hijacks context from skills that should have run.
• Building one giant skill instead of three small ones. Skills compose. /audit + /proposal + /invoice beats one /client-flow that tries to do everything.

The skill that works is not the longest one. It is the one with the tightest description, the cleanest procedure, and the examples Claude can pattern-match against. Write the description like a job posting. Write the body like an SOP for a new hire. Move everything else to references and scripts. Then test it in a real conversation before you trust it.

Genevieve Claire

Founder, Formaum — Claude Code Expert & Full-Stack AI Engineer

Builds bespoke AI automation systems for multi-location operations. Previously EA Sports FIFA ($7B franchise) and Film/TV VFX on Skyfall, Avengers, Game of Thrones. Based in Vancouver, BC.