writing-skills

A SKILL.md requires YAML frontmatter with name and description fields, followed by a markdown body with an overview, when-to-use triggers, core patterns, and examples. Keep the description focused on triggering conditions starting with "Use when" rather than summarizing the workflow.

Test skills by running pressure scenarios with subagents: first without the skill to document baseline failures, then with the skill to verify compliance. Combine multiple pressures like time constraints, sunk cost, and authority to surface rationalizations the skill must counter.

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 processes cause agents to follow the description instead of reading the full skill.

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

Agents rationalize around rules under pressure using excuses like "spirit versus letter" or "being pragmatic." Counter this with explicit loophole closures, rationalization tables, red flags lists, and foundational principles stated early in the skill.