writing-skills

<execution_workflow> Execute these steps strictly in order when creating or editing any skill document.

THE IRON LAW

NO SKILL WITHOUT A FAILING TEST FIRST

Applies to new skills AND edits. No exceptions — not for "simple additions", not for "documentation updates".

---

Skill Types

Type	Description	Example
Technique	Concrete steps to follow	condition-based-waiting, root-cause-tracing
Pattern	Mental model for thinking about problems	defense-in-depth
Reference	API docs, syntax guides, tool docs	heavily-referenced configs

---

1. RED PHASE — Write Failing Test (Baseline)

• DO NOT write the skill first.
• Run a pressure scenario with a subagent WITHOUT the skill.
• Document exact failures, rationalizations, and choices the agent made verbatim.

---

2. GREEN PHASE — Write Minimal Skill

SKILL.md Structure

• Frontmatter: exactly two fields (name, description), max 1024 chars total.
  • name: letters/numbers/hyphens only, verb-first active voice (e.g., creating-skills).
  • description: "Use when..." — ONLY triggering conditions and symptoms. NEVER summarize the workflow.
  • Why this matters (CSO rule): If the description summarizes the workflow, agents follow the description instead of reading the full skill. The skill body gets skipped.
• Word limits: <200 words for frequently-loaded skills, <500 words for others.
• Keywords: Embed error messages, symptoms, tool names for discoverability.
• Cross-references: Use skill name only — REQUIRED SUB-SKILL: skill-name. Never use @ syntax (force-loads files, burns context).
• Code examples: ONE excellent, complete, runnable example. Never multi-language.
• Flowcharts: ONLY for non-obvious decision points. Never for linear steps.
• Persuasion: Apply linguistic patterns from persuasion-principles.md when writing directives and discipline-enforcing rules.

Description Field — Critical Rules

# BAD: summarizes workflow — agent follows this instead of reading skill
description: Use when creating skills — run baseline, write SKILL.md, test with subagent

# GOOD: triggering conditions only
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment