Why Your Claude Skill Sits Unused (And How to Make It Fire)

The big picture

A Claude skill is a folder of instructions that teaches Claude how your team does a recurring task. Inside that folder sits one required file called SKILL.md (a plain text file written in Markdown, the simple formatting most note apps use). The file opens with a few lines of metadata: a name and a description. Below that, you write the actual instructions.

Anthropic, the company behind Claude, offers the clearest way to think about this: a skill is an onboarding guide for a new hire. Claude can already reason. What it cannot guess is your procedural knowledge: how your team writes a product spec, which metrics you quietly drop from every report. The skill hands Claude that house knowledge.

Building one is genuinely easy. The internet is full of honest "build one in five minutes" tutorials. The hard part is everything those tutorials skip.

Why it matters

You are trying to use AI for real work, and you keep re-explaining yourself. Every new session, Claude forgets how you want your spec structured or who your competitors are. A skill is the fix: write the playbook once, and Claude pulls it in when the task comes up.

But here is the trap. A skill that works perfectly yet never fires is worthless. According to the field guide this piece draws on, almost all tutorials cover the basics and almost none cover the real work: getting a skill to trigger on the right task and behave once it does. So people stop at "a bit of text in a file" and wonder why their skill sits unused.

How it works

Claude reads skills in layers

Claude does not load your whole skill up front. At startup it reads only the name and description of every installed skill, about a hundred tokens each (a token is roughly a word-piece, the unit AI bills and reasons in). That is enough to know the skill exists.

When your request matches, Claude reads the full SKILL.md body. Anthropic recommends keeping that body under about five hundred lines. Only if the body points to a reference file does Claude open that third layer. So a skill can hold a dozen reference documents and cost almost nothing for the parts a task never touches.

The description does the deciding

The description is the only thing Claude sees when it picks whether to reach for your skill. Anthropic's best-practices doc is blunt: write it in third person, name what the skill does, and name the triggers. "Processes Excel files and generates reports" beats "Helps with documents." A vague description is the single most common reason a good skill never fires.

Match guardrails to the task

For an open task where many paths work, like a code review, give Claude loose direction. For a fragile task where one wrong step breaks everything, like a database change, give the exact command and tell it not to deviate. Anthropic's image: a robot in an open field needs a nudge; a robot on a narrow bridge with cliffs needs rails.

Yes, but

Triggering is only half the battle. Your skill can fire and still get the output wrong in a way you only notice in real use. The classic case: a spec-reviewer skill that looks great on the one example you built it against, then misses the issues that matter on real work.

You do not catch that by reading the skill. You catch it by testing. Anthropic's own docs state the rule almost no tutorial follows: build your test cases before you write the skill. Run Claude on a few real tasks without the skill, note where it falls short, and turn those gaps into scenarios with a clear "what good looks like."

Here is the part the field guide is most excited about. You used to run that loop by hand. The author reports that in March, Anthropic shipped a version of its skill-creator that runs it for you, with separate agents doing the grading: an Executor runs the skill against your test prompts, a Grader scores the output against your "what good looks like," and a Comparator does a blind A/B between two versions (or between the skill and no skill at all). It also has a benchmark mode that tracks pass rate, time, and token cost so you can re-check a skill when a new model lands. And it runs inside Cowork, Anthropic's desktop agent for non-developers, so you describe what good looks like in plain language and the agents do the rest.

One more caution: security. A SKILL.md is plain text that Claude treats as instructions, so it is a place to hide an attack. A malicious skill can quietly tell Claude to leak your API key, and ordinary code scanners miss it because the payload is prose, not code. The piece points to scanners built for this surface (it names claudelint and skill-lint). Install skills the way you install software: only from sources you trust, and read the whole file first.

The bottom line

Building a skill is the easy part. Making it fire on the right task, behave once it does, and survive a stranger's tampering is the work. A sharp description, a short body, and one test loop separate skills that hold up from skills that just read well.