skill-engineering

A skill stabilizes a procedure the agent performs unreliably. It is not a place for knowledge the model already has, and it is not documentation. Value concentrates in procedural anchoring — setup order, tool sequence, the check that catches a specific failure — not in explanation.

Decide whether the behavior belongs in a skill

• Write a skill only where the model fails the procedure without it. Skills pay off where the model is weak and cost where it is already competent: a skill on a task the model already handles adds tokens, adds an applicability judgment it can get wrong, and narrows the recovery path it would otherwise have found.
• One skill per procedure a user would name in a single request. If one request needs two of these skills, they are one skill; if one skill answers two unrelated requests, it is two.
• Put a prohibition that must hold every time in a hook. Prose steers; the host's lifecycle mechanism enforces.
• Put work that needs a clean context and returns a summary in a subagent, and connection to an external system in a tool or server. Skills carry procedure; tools carry capability.

Archetype and scoping — the workflow, knowledge, and coding-discipline shapes with their structural templates, the scope-sizing tests, negative triggers, and skill composition: [${CLAUDE_SKILL_DIR}/references/archetypes.md]. Read it before writing the body, because the archetype decides the structure.

Write the description as routing code

The description is the only part of a skill that is always in context, and it is where most skills fail: over half of public skills carry routing metadata that cannot route.

• Use the form [Verb] [what]. Use when [trigger]. A description that says only what the skill does gives the model nothing to fire on.
• Discriminate against the neighbors. Name the boundary that separates this skill from the sibling that matches the same words. Selection precision collapses as the candidate pool grows — from roughly 30% at five candidates to a few percent at a hundred — so a description competes, it does not merely describe.
• Front-load the use case and keep it under 250 characters. Listings are budgeted and truncate.
• Write the triggers in the words a user would type, including the case where the user never names the domain.
• Keep routing information out of the body and write it in third person. The body is read after the routing decision is made, and a mixed point of view degrades discovery.