사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/normanderwan/claude-casebook --skill write-skill시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Write Skill
Overview
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 agent-skills:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
Skills with executable code: see executable-code-skills.md, a summary of Anthropic's skill authoring best practices with a link to the full page.
What is a Skill?
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 Mapping for Skills
| 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.
When to Create a Skill
Create when:
- Technique wasn't intuitively obvious to you
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit
Don't create for:
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md)
- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
Skill Types
Technique
Concrete method with steps to follow (find-cause, verify-sources)
Pattern
Way of thinking about problems (flatten-with-flags, test-invariants)
Reference
API docs, syntax guides, tool documentation (office docs)
Directory Structure
skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if neededFlat namespace - all skills in one searchable namespace
Separate files for:
- Heavy reference (100+ lines) - API docs, comprehensive syntax
- Reusable tools - Scripts, utilities, templates
Keep inline:
- Principles and concepts
- Code patterns (< 50 lines)
- Everything else
SKILL.md Structure
Frontmatter (YAML):
- Two required fields:
nameanddescription(see agentskills.io/specification for all supported fields) version: required,Major.Minor.patch, top-level field (not nested undermetadata). New skill starts at1.0.0. Bump Patch for clarifications/typos, Minor for added sections/rules that don't break existing usage, Major for structural/behavioral changes that invalidate prior usage.- Max 1024 characters total
name: Use letters, numbers, and hyphens only (no parentheses, special chars)description: Third-person, describes ONLY when to use (NOT what it does)- Start with "Use when..." to focus on triggering conditions
- Include specific symptoms, situations, and contexts
- NEVER summarize the skill's process or workflow (see
cso-guide.mdfor why) - Keep under 500 characters if possible
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# Skill Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
[Small inline flowchart IF decision non-obvious]
Bullet list with SYMPTOMS and use cases
When NOT to use
## Core Pattern (for techniques/patterns)
Before/after code comparison
## Quick Reference
Table or bullets for scanning common operations
## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools
## Common Mistakes
What goes wrong + fixes
## Real-World Impact (optional)
Concrete resultsClaude Search Optimization (CSO)
Critical for discovery: Future Claude needs to FIND your skill before it can use it.
Description rules (summary):
- Start with "Use when..." — describes the TRIGGER, not what the skill does
- Never summarize the workflow or process in the description
- Use concrete symptoms and situations, not abstract categories
- Technology-agnostic unless the skill itself is tech-specific
Cross-references: Use backticks only — never @-syntax (force-loads, burns context).
Naming: Verb-noun, e.g. write-skill, guide-decision, find-cause. Not a vague category (skill-utils, helpers).
Keyword coverage: Include error messages, symptoms, tool names so Claude can find the skill.
Token efficiency: getting-started: <150 words. Frequently-loaded: <200 words total.
→ See `cso-guide.md` for the full description-field guide with examples, anti-patterns, token efficiency techniques, and the "workflow summary trap" explanation.
Flowchart Usage
digraph when_flowchart {
"Need to show information?" [shape=diamond];
"Decision where I might go wrong?" [shape=diamond];
"Use markdown" [shape=box];
"Small inline flowchart" [shape=box];
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
}Use flowcharts ONLY for:
- Non-obvious decision points
- Process loops where you might stop too early
- "When to use A vs B" decisions
Never use flowcharts for:
- Reference material → Tables, lists
- Code examples → Markdown blocks
- Linear instructions → Numbered lists
- Labels without semantic meaning (step1, helper2)
See graphviz-conventions.dot for graphviz style rules.
Visualizing for your human partner: Use render-graphs.js in this directory to render a skill's flowcharts to SVG:
./render-graphs.js ../some-skill # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVGCode Examples
One excellent example beats many mediocre ones
Choose most relevant language:
- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python
Good example:
- Complete and runnable
- Well-commented explaining WHY
- From real scenario
- Shows pattern clearly
- Ready to adapt (not generic template)
Don't:
- Implement in 5+ languages
- Create fill-in-the-blank templates
- Write contrived examples
You're good at porting - one great example is enough.
For skills that include executable scripts, see executable-code-skills.md.
File Organization
Self-Contained Skill
defense-in-depth/
SKILL.md # Everything inlineWhen: All content fits, no heavy reference needed
Skill with Reusable Tool
retry-with-backoff/
SKILL.md # Overview + patterns
example.ts # Working helpers to adaptWhen: Tool is reusable code, not just narrative
Skill with Heavy Reference
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable toolsWhen: Reference material too large for inline
The Iron Law (Same as TDD)
NO SKILL WITHOUT A FAILING TEST FIRSTThis applies to NEW skills AND EDITS to existing skills.
Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation.
No exceptions:
- Not for "simple additions"
- Not for "just adding a section"
- Not for "documentation updates"
- Don't keep untested changes as "reference"
- Don't "adapt" while running tests
- Delete means delete
REQUIRED BACKGROUND: The agent-skills:test-driven-development skill explains why this matters. Same principles apply to documentation.
Testing All Skill Types
Different skill types need different test approaches:
Discipline-Enforcing Skills (rules/requirements)
Examples: TDD, verification-before-completion, designing-before-coding
Test with:
- Academic questions: Do they understand the rules?
- Pressure scenarios: Do they comply under stress?
- Multiple pressures combined: time + sunk cost + exhaustion
- Identify rationalizations and add explicit counters
Success criteria: Agent follows rule under maximum pressure
→ See `testing-skills-with-subagents.md` for the full pressure-testing methodology (RED-GREEN-REFACTOR, pressure types, rationalization tables, meta-testing).
Technique / Pattern / Reference Skills
For skills that improve output quality rather than enforce compliance, use empirical A/B testing instead of pressure scenarios:
→ See `evaluating-skills-with-subagents.md` for the full evaluation methodology (quality A/B benchmark, blind comparison, trigger-description optimization).
The sub-sections below describe what each skill type needs; the measurement approach is in that document.
Technique Skills (how-to guides)
Examples: find-cause, verify-sources, prevent-drift
Test with:
- Application scenarios: Can they apply the technique correctly?
- Variation scenarios: Do they handle edge cases?
- Missing information tests: Do instructions have gaps?
Success criteria: Agent successfully applies technique to new scenario
Pattern Skills (mental models)
Examples: reducing-complexity, information-hiding concepts
Test with:
- Recognition scenarios: Do they recognize when pattern applies?
- Application scenarios: Can they use the mental model?
- Counter-examples: Do they know when NOT to apply?
Success criteria: Agent correctly identifies when/how to apply pattern
Reference Skills (documentation/APIs)
Examples: API documentation, command references, library guides
Test with:
- Retrieval scenarios: Can they find the right information?
- Application scenarios: Can they use what they found correctly?
- Gap testing: Are common use cases covered?
Success criteria: Agent finds and correctly applies reference information
Common Rationalizations for Skipping Testing
| Excuse | Reality |
|---|---|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
| "No time to test" | Deploying untested skill wastes more time fixing it later. |
All of these mean: Test before deploying. No exceptions.
Bulletproofing & RED-GREEN-REFACTOR
Skills that enforce discipline need to resist rationalization. Agents are smart and will find loopholes when under pressure.
Key techniques (summary):
- Close every loophole explicitly — forbid the specific workaround, not just the general rule
- Add a rationalization table: capture every excuse agents make → counter each one
- Add a "Red Flags — STOP" list for self-checking
- Address "spirit vs letter" arguments: add "Violating the letter IS violating the spirit"
RED: Run pressure scenario WITHOUT skill → document exact rationalizations verbatim. GREEN: Write skill addressing those specific rationalizations → verify compliance. REFACTOR: New rationalization found → add counter → re-test until bulletproof.
→ See `testing-skills-with-subagents.md` for the complete methodology: pressure scenario templates, all pressure types (time/sunk-cost/authority/exhaustion), plugging holes systematically, meta-testing techniques, and worked examples.
Anti-Patterns
❌ Narrative Example
"In session 2025-10-03, we found empty projectDir caused..." Why bad: Too specific, not reusable
❌ Multi-Language Dilution
example-js.js, example-py.py, example-go.go Why bad: Mediocre quality, maintenance burden
❌ Code in Flowcharts
step1 [label="import fs"];
step2 [label="read file"];Why bad: Can't copy-paste, hard to read
❌ Generic Labels
helper1, helper2, step3, pattern4 Why bad: Labels should have semantic meaning
❌ Non-descriptive skill name
skill-utils, helpers, misc-patterns Why bad: Claude searches by name - vague names don't trigger. Use verb-noun (see Naming above).
❌ Windows-style paths
scripts\helper.py, reference\guide.md Why bad: Fails on Unix. Use forward slashes everywhere.
❌ Too many options
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image…" Why bad: Decision fatigue. Provide one default; add escape hatch for the rare exception.
❌ Domain-by-domain catalog instead of a general rule
Separate bullets/sections for "finance decisions", "health decisions", "legal decisions" that each restate the same underlying rule with different nouns. Why bad: Doesn't generalize to the next domain that shows up. When correcting a skill, state the rule once at the level it actually applies, not as a growing list of examples.
STOP: Before Moving to Next Skill
After writing ANY skill, you MUST STOP and complete the deployment process.
Do NOT:
- Create multiple skills in batch without testing each
- Move to next skill before current one is verified
- Skip testing because "batching is more efficient"
The deployment checklist below is MANDATORY for EACH skill.
Skill Creation Checklist (TDD Adapted)
IMPORTANT: Use the task-tracking tool (TaskCreate in Claude Code) to create a task for EACH checklist item below.
RED Phase - Write Failing Test:
- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
- [ ] Identify patterns in rationalizations/failures
GREEN Phase - Write Minimal Skill:
- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
- [ ] Name is verb-noun (e.g.
write-skill), not a vague category or noun - [ ] YAML frontmatter with required
nameanddescriptionfields (max 1024 chars; see spec) - [ ]
versionset (1.0.0new, bumped per semver on edits) - [ ] Description starts with "Use when..." and includes specific triggers/symptoms
- [ ] Description written in third person
- [ ] Keywords throughout for search (errors, symptoms, tools)
- [ ] Clear overview with core principle
- [ ] Address specific baseline failures identified in RED
- [ ] Code inline OR link to separate file
- [ ] One excellent example (not multi-language)
- [ ] Run scenarios WITH skill - verify agents now comply
REFACTOR Phase - Close Loopholes:
- [ ] Identify NEW rationalizations from testing
- [ ] Add explicit counters (if discipline skill)
- [ ] Build rationalization table from all test iterations
- [ ] Create red flags list
- [ ] Re-test until bulletproof
Quality Checks:
- [ ] Small flowchart only if decision non-obvious
- [ ] Quick reference table
- [ ] Common mistakes section
- [ ] No narrative storytelling
- [ ] Supporting files only for tools or heavy reference
- [ ] SKILL.md body under 500 lines (use progressive disclosure if over)
- [ ] No Windows-style paths (forward slashes only)
- [ ] Tested on Haiku, Sonnet, and Opus (not one model only)
- [ ] Prompt-structure pass (exact triggers, one item per condition) before drafting, e.g. with the
write-promptplugin - [ ] Body and reference files write clean on the first draft: cut superfluous words, never fuse or drop meaning to shorten - no post-hoc tightening pass
Deployment:
- [ ] Every checklist item above re-verified against the finished file - drafting-time self-checks alone can miss gaps (e.g. a planned example that never made it in)
- [ ] Commit skill to git and push to your fork (if configured)
- [ ] Consider contributing back via PR (if broadly useful)
Discovery Workflow
How future Claude finds your skill:
- Encounters problem ("tests are flaky")
- Finds SKILL (description matches)
- Scans overview (is this relevant?)
- Reads patterns (quick reference table)
- Loads example (only when implementing)
Optimize for this flow - put searchable terms early and often.
The Bottom Line
Creating skills IS TDD for process documentation.
Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes). Same benefits: Better quality, fewer surprises, bulletproof results.
If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.
Base: [`obra/superpowers` — `writing-skills`](https://github.com/obra/superpowers) (MIT). Evaluation machinery absorbed from Anthropic `skill-creator` example (Apache-2.0). See `SOURCES.md`.