Production-Ready Skill Files: Why 9 in 10 Never Trigger, and How to Fix the Description

Your skill works on your machine. With your phrasing. On the one task you tested. A teammate tries it with different wording and the skill never fires. Or it fires when it shouldn't. Or it runs and emits output that looks fine and quietly breaks the next step in the pipeline.

That's the default state. Around 90% of skill files in shared repos and team configs miss one of five basic checks: a vague description, a body past 500 lines, reference files nested more than a level deep, no documented ambiguity strategy, no pre-ship test protocol. The official docs cover the file format. They spend almost no time on the engineering decisions that decide whether the skill ever runs in production.^[1]

One field controls all the others. The description. Get it wrong and the body never loads — the agent didn't pick your skill, and nothing inside it ever ran. The rest of this guide covers what flows from that fact: metadata engineering for reliable triggering, three-tier progressive disclosure for token discipline, an ambiguity policy that survives real users, output formats that serve humans and the next tool in the chain, and a test protocol that gives you a number to ship against instead of a feeling.

The docs say it. They don't dwell on it. The description is the only thing the agent reads when deciding whether to load your skill.^[1] The body, the instructions, the templates, the validation scripts — none of it exists in the agent's context until after the description has already won or lost.

At startup, every installed skill contributes roughly 100 tokens of metadata to the system prompt. Hundreds of skills compete in that budget. The agent scans the descriptions and picks the best match for the current task. A vague description loses to a precise competitor. Missing trigger vocabulary loses to a description that mirrors the user's actual phrasing. A first-person blurb loses to a third-person one because the system prompt's voice gets confused.^[2]

There's no algorithmic routing. No embeddings, no intent classifier, no pattern matching at the code level.^[7] The system formats all available skill descriptions into the Skill tool's context and lets the model make the call. The model is reading descriptions the same way it reads everything else — as text. Write the description for a reader, not a regex.

Library card catalog. Nobody reads the book to decide whether to pull it off the shelf. The catalog card decides. Write the card.

Add 20 skills to a team's Claude Code setup and something counterintuitive happens: selection gets worse, not just slower. Recent research studying agent skill libraries at scale found performance degrading by up to 21% when scaling from a small set of focused skills to a 202-skill library.^[12] The model starts having trouble determining which skill is worth loading, and potentially helpful skills go unused.

The mechanism is called skill shadowing: when two or more skills have overlapping description vocabulary, they compete for the same trigger queries and split the selection signal. The agent picks one, ignores the other, or picks neither. All three outcomes are wrong.

The fix isn't fewer skills. It's cleaner description boundaries.

The context window is a shared resource. Your skill competes with the system prompt, conversation history, every other installed skill's metadata, and the actual user request. Every token spent on skill content is a token taken from reasoning.^[6]

Production skills load in three tiers, on demand. Tier collapse — pulling everything in upfront — is the failure mode.

Tier 1 — Metadata. Always loaded. ~100 tokens per skill. The name and description from the YAML frontmatter. This is the only fragment the agent sees at selection time.^[1]

Tier 2 — Entry point. Loaded when the skill wins selection. The markdown body of SKILL.md. Target under 500 lines. Holds the workflow, decisions, pointers to references. Past 500 lines and the agent starts reading partial chunks and missing context.

Tier 3 — References. Loaded on demand. Templates, examples, API docs, scripts. A skill with 2,000 lines of API reference in a Tier 3 file costs zero tokens on every task that does not touch the API. That's the leverage point.

Note: when using skills through the Claude Agent SDK rather than the CLI, allowed-tools frontmatter is ignored — tool access is controlled via the allowedTools option on query(). The SDK loads skills via settingSources (user and project), not via the frontmatter fields the CLI reads.^[13]

Real users don't write specifications. They say "fix the tests" when they mean the three failing integration tests in the auth module. They say "make a report" when they mean a quarterly revenue breakdown by region, in markdown.

The skill needs a written ambiguity policy. Two failure modes pull in opposite directions. Always-ask kills the experience — the skill feels slow and pedantic, users stop reaching for it. Always-assume produces wrong output that takes longer to repair than to redo from scratch. The fix is not a single rule. It is a per-class-of-action decision documented in the skill itself, so the agent doesn't re-derive it under pressure.

Skill output is rarely the final destination. It flows into two consumers: a human deciding the next move, and a downstream tool that needs to parse what came out. Pick one and the other pays a tax.

Human-formatted output the next tool can't parse forces manual copy-paste — every chained workflow grinds. Machine-formatted output the human can't scan forces a formatter pass before any decision. The right shape serves both. The pattern below is plan-validate-execute: the skill writes a structured plan a human can read at a glance, then validates it, then applies it. The intermediate artifact is the contract.

Common failure: every instruction written as an absolute rule. Different parts of a skill need different constraint levels. Database migrations need exact commands. Code reviews need direction, not a script. Over-constrain the flexible work and the agent ignores context that matters. Under-constrain the fragile work and the agent reasons toward something that breaks production.^[6]

A useful mental model. Some tasks are a narrow bridge with cliffs on both sides — one safe path, deviation means failure, write the exact command. Other tasks are an open field — many paths reach the goal, the agent's judgment about which route to take is usually better than the author's hardcoded choice. Match the constraint to the terrain. Mismatch is where rigidity meets recklessness.

A corollary: the most elaborate skill files are often the least reliable. Teams that pour effort into exhaustive instructions discover the skill is too rigid for the variety of inputs it actually meets. The skills that survive in production are narrowly scoped with sparse instructions — one thing, done clearly, no attempt to cover every adjacent case. Scope discipline beats coverage ambition.

Claude hooks communicate via exit code. The semantics are not what Unix tradition suggests.

Exit code 0 means proceed normally. Any JSON output on stdout is parsed for structured control fields. Exit code 2 is the only code that blocks — it tells Claude Code to halt the current action, and the content on stderr gets fed back to Claude as an error message to reason about. Any other exit code, including 1, logs an error and lets the tool through anyway.^[14]

Every first-time plugin author writes a PreToolUse hook, tests it, sees "BLOCKED" in the log, then watches Claude execute the call regardless. Because 1 is not block. Only 2 is. The hook ran. The enforcement did not.

A second sharp edge: PostToolUse cannot block anything. The tool already ran. Exit code 2 on a PostToolUse hook shows stderr to Claude — it does not undo what executed. Use Pre for guards. Use Post for cleanup and context injection.

Writing evals before writing extensive documentation is the highest-leverage move in skill engineering.^[4] It forces the question every author wants to skip — does the skill solve a real problem or an imagined one. If the agent already handles the task without the skill, you don't need the skill. The eval surfaces that fact in minutes instead of months.

The protocol below is two halves. Automated checks catch structural problems — descriptions that fail selection, files past the line cap, references nested too deep. Observational testing catches behavioral problems the harness can't see — the skill firing on adjacent tasks, ignoring a reference file, re-reading the same section four times because the body is structured wrong. Run both. One without the other ships blind.

After shipping 54 plugins in skillstack, one metric predicts adoption better than any other: activation rate — the percentage of relevant user queries that actually trigger the skill. A careful first author lands around 8/10. Not a failure. A starting point. The gap from 8/10 to 10/10 closes through iteration on the description field, never the body.

The loop: 10-15 positive trigger queries, 5-10 negatives, run them against the model, count the misses, rewrite the description to close each specific gap, run again. plugin-dev's run_eval.py collapses that into one command. Without the harness, every description edit is a coin flip — you cannot tell whether the change helped, hurt, or did nothing.

A single SKILL.md is a function. A plugin — skills, hooks, MCP extensions, scripts — is a system. The threshold is real. A new failure class lives on the other side. The most common one costs hours the first time it hits.

Claude hooks communicate via exit code. Exit code 0 means proceed. Exit code 2 means block the tool call. Exit code 1 logs an error and lets the tool through anyway. Every first-time plugin author writes a PreToolUse hook, tests it, sees "BLOCKED" in the log, watches Claude execute the call regardless. Because 1 is not block. Only 2 is. The hook ran. The enforcement did not.^[14]

The patterns above are not abstract. They are the patterns I extracted while building skillstack. Three artifacts implement them directly. One install adds the whole stack.

Every principle from this guide is in that file. The description carries both what (generates a changelog) and when (user asks for changelog, release notes, what changed, what shipped). The workflow takes the narrowest reasonable interpretation when input is ambiguous. The output format reads cleanly for the human and parses cleanly for the next tool. And the template loads only when the workflow reaches the render step — Tier 3 reference, zero token cost on every other path.^[3]

The test that matters is not whether the skill works when you type /generate-changelog v2.0.0 v2.1.0. It is whether it fires when a teammate types "what shipped this week" into the chat without knowing the skill exists. Design for that phrasing. Test for it. The activation rate is the only number that says yes.

The skills that get used in production are not the ones with the most thorough instructions. They are the ones whose descriptions win selection against everything else competing for that 100-token slot — including the 20 other skills in your team's config. Engineer the description. Keep the library small and the boundaries sharp. Everything else is downstream of those two decisions.