Pitfalls

Generic Descriptions

If several skills “help with development,” routing becomes arbitrary. Describe the unique trigger, excluded cases, and expected artifact.

Hiding Mandatory Rules in Optional Skills

If the agentAgentA worker you delegate to: brief it, and it takes steps on its own. A chatbot answers; an agent acts.An LLM that runs tools in a loop toward a goal — it acts, checks the result, decides the next step, and repeats until done.Full definitionClose may choose not to load a skill, the skill cannot be the only home for a non-negotiable repository rule.

Duplicated Vendor Forks

Three independent copies diverge quickly. Share the procedure and isolate only product-specific metadata and commands.

Unsafe Helper Scripts

Skill scripts run with the process's real access. Validate paths, quote arguments, constrain destinations, and never treat model-generated input as trusted shell syntax.

Oversized Entrypoints

Large bodies defeat progressive disclosure and become fragile under compaction. Route to references at the step where they are needed.

Claiming Completion from Procedure Text

The model saying it followed the skill is not evidence. Require test output, diffs, source links, or other independently inspectable artifacts.

Falsification Checklist

• Does the skill trigger on positive cases and stay silent on negative ones?
• Do all products load the same core procedure?
• Can a skipped step be detected from the output?
• Are scripts safe under malformed or hostile arguments?
• Does the workflow retain its critical instructions after compaction?