writing-skills

Start with YAML frontmatter containing a name and a description that begins with 'Use when' plus specific triggering conditions. Follow with an overview, when-to-use guidance, core patterns, and a quick reference, keeping the body concise and keyword-rich.

Run pressure scenarios with subagents before writing the skill to capture baseline failures verbatim, then re-run the same scenarios with the skill present. Combine three or more pressures like time, sunk cost, and authority to verify compliance under stress.

The description should only describe triggering conditions and symptoms, written in third person starting with 'Use when'. Never summarize the skill's workflow, because agents may follow the description shortcut instead of reading the full skill body.

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

Agents rationalize violations using excuses like sunk cost, pragmatism, or spirit-versus-letter arguments. Counter this by documenting exact rationalizations, adding explicit negations for each loophole, and building red-flag lists into the skill.