Use when creating new skills, editing existing skills, or writing SKILL.md content. Triggers on: "스킬 만들어줘", "새 skill 작성", "SKILL.md 써줘", "skill 개선해줘", create a skill", "skill documentation", "스킬 문서 작성", "workflow skill로 만들어줘".
Writing skills IS Test-Driven Development applied to process documentation.
Personal skills live in agent-specific directories (~/.claude/skills for Claude Code, ~/.agents/skills/ for Codex)
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
REQUIRED BACKGROUND: You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
Official guidance: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md.
A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once
| TDD Concept | Skill Creation |
|---|---|
| Test case | Pressure scenario with subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates rule without skill (baseline) |
| Test passes (GREEN) | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |
| Write test first | Run baseline scenario BEFORE writing skill |
| Watch it fail | Document exact rationalizations agent uses |
| Minimal code | Write skill addressing those specific violations |
| Watch it pass | Verify agent now complies |
| Refactor cycle | Find new rationalizations → plug → re-verify |
The entire skill creation process follows RED-GREEN-REFACTOR.
Create when:
Don't create for:
Technique — Concrete method with steps (condition-based-waiting, root-cause-tracing) Pattern — Way of thinking about problems (flatten-with-flags, test-invariants) Reference — API docs, syntax guides, tool documentation (office docs)
skills/skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed
Separate files for heavy reference (100+ lines) or reusable tools. Keep everything else inline.
For SKILL.md structure template, flowchart guidance, code example rules, file organization patterns, and anti-patterns, see references/authoring-reference.md.
Frontmatter (YAML): Only name and description fields. Max 1024 characters total.
name: letters, numbers, hyphens onlydescription: starts with "Use when...", triggering conditions only, never workflow summary, under 500 charsCritical for discovery: Future Claude needs to FIND your skill.
Description = When to Use, NOT What the Skill Does. Do NOT summarize the skill's process or workflow. Testing showed that workflow-summary descriptions cause Claude to follow the description instead of reading the skill body — creating a shortcut that makes the skill body irrelevant.
# ❌ BAD: Summarizes workflow