writing-skills

A SKILL.md requires YAML frontmatter with only name and description fields, followed by a markdown body with overview, when-to-use triggers, core patterns, and quick reference sections. The description should start with "Use when..." and describe triggering conditions only, never the workflow.

Run pressure scenarios with subagents without the skill first to capture baseline failures verbatim, then write the skill addressing those specific failures, and re-test with the skill present. Combine three or more pressures like time, sunk cost, and exhaustion for realistic testing.

A good description starts with "Use when...", describes only triggering conditions and symptoms in third person, and never summarizes the skill's workflow. Descriptions that summarize process cause agents to follow the description instead of reading the full skill body.

Do not create skills for one-off solutions, standard practices documented elsewhere, project-specific conventions, or mechanical constraints that can be enforced with validation or regex. Skills are for reusable techniques, patterns, and references that apply broadly.

Agents rationalize skipping rules using excuses like sunk cost, authority override, or "spirit versus letter" arguments. Bulletproof skills counter this with explicit negations of each loophole, rationalization tables, red flag lists, and foundational principles stated early.