writing-skills

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

Use pressure scenarios with subagents that combine 3+ pressures like time constraints, sunk cost, and authority. Run scenarios without the skill to capture baseline rationalizations, then verify agents comply once the skill is present.

The description should start with "Use when..." and describe only triggering conditions and symptoms, never summarizing the skill's workflow. Write in third person, keep it under 500 characters, and include searchable keywords like error messages and symptoms.

Agents rationalize violations when facing time pressure, sunk costs, or authority conflicts. Counter this by documenting exact rationalizations verbatim, adding explicit negations for each loophole, and building rationalization tables with red-flag lists.

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