writing-skills

Start with YAML frontmatter containing name and description fields, then write an overview, when-to-use triggers, core patterns, and common mistakes. Test the skill with pressure scenarios before deploying to verify agents actually follow it.

Run pressure scenarios with subagents without the skill first to document baseline failures verbatim. Then run the same scenarios with the skill present and verify compliance, iterating to close any rationalization loopholes agents find.

Write only triggering conditions starting with "Use when..." in third person, including specific symptoms and situations. Never summarize the skill's workflow, because agents may follow the description instead of reading the full skill body.

Agents rationalize violations when facing time pressure, sunk cost, or authority conflicts. Counter this with explicit negations of each observed excuse, rationalization tables, red flag lists, and foundational principles like "violating the letter is violating the spirit."

Skip skill creation for one-off solutions, project-specific conventions, well-documented standard practices, and mechanical constraints that can be enforced with validation or regex instead of documentation.