writing-skills

Create a directory containing a SKILL.md file with YAML frontmatter defining name and description, followed by markdown instructions. Follow the TDD cycle: run baseline scenarios without the skill, write minimal content addressing observed failures, then refactor to close loopholes.

Run pressure scenarios with subagents that combine time pressure, sunk cost, and authority. First run without the skill to document baseline failures verbatim, then run with the skill to verify agents comply under maximum pressure.

Write a third-person description starting with 'Use when...' that lists specific triggering conditions and symptoms. Never summarize the skill's workflow in the description, because agents may follow the summary instead of reading the full skill body.

Skip skill creation for one-off solutions, project-specific conventions better placed in CLAUDE.md, standard practices documented elsewhere, and mechanical constraints that can be enforced with automated validation instead of documentation.

Agents rationalize around rules under pressure using excuses like 'spirit not letter' or 'this case is different.' Counter this by adding explicit negations, rationalization tables, red-flag lists, and foundational principles, then re-test until bulletproof.