Most Skill Files Never Trigger. The Description Field Is Why.

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]

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

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.

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.

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.

Across hundreds of skill files in open-source repos and production codebases, the same failure patterns recur.^[6] These are not hypothetical. They are the reasons skills break the moment they leave the author's machine.

A non-obvious one: the most elaborate skill files are often the least reliable. Teams that pour effort into exhaustive instructions, templates, and deep reference documentation 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.

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. Engineer the description. Everything else is downstream of that one decision.