skills/
  skill-name/
    SKILL.md              # Primary reference document (required)
    supporting-file.*     # Only if needed

---
name: Skill-Name-With-Hyphens
description: Use when [specific trigger conditions and symptoms]
---

undefined

undefined

**Content:**
- Use specific trigger conditions, symptoms, and scenarios to indicate when this skill applies
- Describe problems (race conditions, inconsistent behavior) not language-specific symptoms (setTimeout, sleep)
- Keep trigger conditions technology-agnostic unless the skill itself is technology-specific
- If the skill is technology-specific, clearly state that in the trigger conditions
- Write in third person (injected into system prompts)
- **Never summarize the skill's process or workflow**

```yaml

undefined

undefined

**Use cross-references:**
```markdown

**Compress examples:**
```markdown

**Eliminate redundancy:**
- Don't repeat content already in cross-referenced skills
- Don't explain things obvious from commands
- Don't provide multiple examples for the same pattern

**Validation:**
```bash
wc -w skills/path/SKILL.md

**Name by what you do or core insight:**
- ✅ `condition-based-waiting` > `async-test-helpers`
- ✅ `using-skills` instead of `skill-usage`
- ✅ `flatten-with-flags` > `data-structure-refactoring`
- ✅ `root-cause-tracing` > `debugging-techniques`

**Gerunds (-ing) are good for processes:**
- `creating-skills`, `testing-skills`, `debugging-with-logs`
- Active, describes what you're doing

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Might I make a mistake in decision?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Might I make a mistake in decision?" [label="Yes"];
    "Might I make a mistake in decision?" -> "Small inline flowchart" [label="Yes"];
    "Might I make a mistake in decision?" -> "Use markdown" [label="No"];
}

./render-graphs.js ../some-skill           # Render each chart separately
./render-graphs.js ../some-skill --combine # Combine all charts into one SVG

defense-in-depth/
  SKILL.md    # All content inline

condition-based-waiting/
  SKILL.md    # Overview + pattern
  example.ts  # Adaptable working code

pptx/
  SKILL.md       # Overview + workflow
  pptxgenjs.md   # 600-line API reference
  ooxml.md       # 500-line XML structure
  scripts/       # Executable tools

Don't write a skill without a failing test

</Good>

**Violating the letter of the rule is violating the spirit of the rule.**

| Rationalization | Reality |
|------|------|
| "Too simple to test" | Simple code still breaks. Testing takes 30 seconds. |
| "I'll test later" | Tests passing immediately proves nothing. |
| "Testing after works just as well" | Testing after = "What does this do?" Testing before = "What should this do?" |

undefined

undefined

description: use when implementing any feature or bugfix, before writing implementation code

step1 [label="import fs"];
step2 [label="read file"];