writing-skills

Run pressure scenarios with subagents without the skill first to capture baseline failures verbatim, then write the skill addressing those specific rationalizations and re-test until agents comply. Combine three or more pressures such as time, sunk cost, and authority for realistic results.

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

Close every loophole explicitly with negations, add a foundational principle like "violating the letter is violating the spirit," and maintain a rationalization table mapping each observed excuse to its counter. Re-test after each addition until no new rationalizations appear.

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

Yes, the included render-graphs.js script extracts dot blocks from a skill's SKILL.md and renders them to SVG files using graphviz. Run it with the skill directory path, optionally adding --combine to merge all diagrams into one SVG.