writing-skills

Writing Skills

Overview

Writing a skill is applying test-driven development to process documentation.

Personal skills are stored in agent-specific directories (for Claude Code use ~/.claude/skills, for Codex use ~/.agents/skills/）

You write test cases (stress scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch the tests pass (the agent follows the rules), then refactor (plug the holes).

Core principle: If you haven't observed the agent failing without the skill, you don't know whether the skill teaches the right thing.

Required background: Before using this skill, you must understand superpowers:test-driven-development. That skill defines the basic red-green-refactor loop. This skill adapts TDD to documentation writing.

Official guidance: For Anthropic's official skill-writing best practices, see anthropic-best-practices.md. That document provides additional patterns and guidance that complement this skill's TDD-oriented approach.

What Is a Skill?

A skillis a reference guide to a proven technique, pattern, or tool. Skills help future Claude instances find and apply effective approaches.

A skill is: a reusable technique, pattern, tool, reference guide

A skill is not: a narrative about how you solved a problem one time

TDD Mapped to Skills

TDD Concept	Skill Creation
Test case	Stress scenario with a subagent
Production code	Skill documentation (SKILL.md)
Test fails (red)	The agent violates the rules without the skill (baseline)
Test passes (green)	The agent follows the rules with the skill
Refactor	Plug the holes while maintaining compliance
Write the test first	Run the baseline scenario before writing the skill
Watch it fail	Record the exact rationalizations the agent uses
Minimal code	Write a skill targeting those specific violations
Watch it pass	Verify that the agent now follows the rules
Refactor loop	Discover new rationalizations → plug → re-verify

The entire skill creation process follows red-green-refactor.

When to Create a Skill

Create when:

The technique is not intuitively obvious to you
You would repeatedly reference it across different projects
The pattern has broad applicability (not project-specific)
Others would also benefit

Do not create:

One-off solutions
Standard practices that are well documented elsewhere
Project-specific conventions (put them in CLAUDE.md)
Mechanical constraints (if it can be enforced with regex/validation, automate it—leave documentation for scenarios that require judgment)

Skill Types

Technique-based

Methods with concrete steps (condition-based-waiting, root-cause-tracing)

Pattern types

Ways of thinking about problems (flatten-with-flags, test-invariants)

Reference types

API documentation, syntax guides, tool documentation (office docs)

Directory structure

skills/
  skill-name/
    SKILL.md              # 主参考文档（必需）
    supporting-file.*     # 仅在需要时

Flat namespace - All skills in one searchable namespace

Cases for separate files:

Large amount of reference content(100+ lines) - API documentation, comprehensive syntax descriptions
Reusable tools - Scripts, utilities, templates

Keep inline:

Principles and concepts
Code patterns (< 50 lines)
Everything else

SKILL.md structure

Frontmatter（YAML）：

Two required fields:name and description(for fully supported fields see agentskills.io/specification）
Maximum 1024 characters total
name: Use only letters, numbers, and hyphens (no parentheses, special characters)
description: Third person, describe only when to use (not what to do)
- Start with "Use when...", focus on trigger conditions
- Include concrete symptoms, scenarios, and context
- Never summarize the skill's process or workflow(see the CSO section for why)
- Keep it under 500 characters if possible

---
name: Skill-Name-With-Hyphens
description: Use when [具体的触发条件和症状]
---

# 技能名称

## 概述
这是什么？用 1-2 句话说明核心原则。

## 何时使用
[如果决策不明显，使用小型内联流程图]

症状和用例的要点列表
不适用的场景

## 核心模式（技术/模式类）
前后代码对比

## 快速参考
用于快速浏览常见操作的表格或要点

## 实现
简单模式内联代码
大量参考或可复用工具链接到文件

## 常见错误
常见问题 + 修复方法

## 实际效果（可选）
具体结果

Claude Search Optimization (CSO)

Discovery is critical: Future Claude needs to find your skill

1. Rich description field

Purpose: Claude reads the description to decide which skills to load for the current task. Let it answer: "Should I read this skill right now?"

Format: Start with "Use when...", focus on trigger conditions

Key: description = when to use, not what the skill does

The description should only describe trigger conditions. Do not summarize the skill's process or workflow in the description.

Why this matters: Testing shows that when the description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description that says "perform code review between tasks" caused Claude to do only one review, even though the skill's flowchart clearly showed two reviews (spec compliance first, then code quality).

When the description was changed to only "Use when executing an implementation plan containing independent tasks in the current session" (no workflow summary), Claude correctly read the flowchart and followed the two-phase review process.

Pitfall: Descriptions that summarize the workflow create shortcuts that Claude will take. The skill body becomes documentation that Claude skips.

# 错误：总结了工作流 - Claude 可能会跟随描述而非阅读技能
description: Use when executing plans - dispatches subagent per task with code review between tasks

# 错误：流程细节太多
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# 正确：只有触发条件，无工作流摘要
description: Use when executing implementation plans with independent tasks in the current session

# 正确：仅触发条件
description: Use when implementing any feature or bugfix, before writing implementation code

Content:

Use concrete trigger conditions, symptoms, and scenarios to indicate that this skill applies
Describe the problem (race conditions, inconsistent behavior) rather than language-specific symptoms (setTimeout, sleep)
Keep trigger conditions technology-agnostic unless the skill itself is technology-specific
If the skill is technology-specific, state it explicitly in the trigger conditions
Write in third person (injected into the system prompt)
Never summarize the skill's process or workflow

# 错误：太抽象、模糊，未包含何时使用
description: For async testing

# 错误：第一人称
description: I can help you with async tests when they're flaky

# 错误：提到了技术但技能并非该技术特定的
description: Use when tests use setTimeout/sleep and are flaky

# 正确：以"Use when"开头，描述问题，无工作流
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# 正确：技术特定的技能带有明确的触发条件
description: Use when using React Router and handling authentication redirects

2. Keyword coverage

Use words that Claude would search for:

Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
Symptoms: "flaky", "hanging", "zombie", "pollution"
Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
Tools: actual commands, library names, file types

3. Descriptive naming

Use active voice, verbs first:

✅ creating-skills instead of skill-creation
✅ condition-based-waiting instead of async-test-helpers

4. Token efficiency (critical)

Problem: getting-started and frequently referenced skills are loaded into every conversation. Every token matters.

Target word counts:

getting-started workflows: each <150 words
Frequently loaded skills: total <200 words
Other skills: <500 words (still be concise)

Techniques:

Move details into tool help:

# 错误：在 SKILL.md 中列出所有参数
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# 正确：引用 --help
search-conversations 支持多种模式和过滤器。运行 --help 查看详情。

Use cross-references:

# 错误：重复工作流细节
搜索时，用模板分派子智能体……
[20 行重复的说明]

# 正确：引用其他技能
始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。

Condense examples:

# 错误：冗长的示例（42 词）
你的搭档："我们之前是怎么处理 React Router 中的认证错误的？"
你：我来搜索过去对话中的 React Router 认证模式。
[用搜索查询分派子智能体："React Router authentication error handling 401"]

# 正确：精简的示例（20 词）
搭档："我们之前是怎么处理 React Router 中的认证错误的？"
你：正在搜索……
[分派子智能体 → 整合]

Eliminate redundancy:

Don't repeat content already in cross-referenced skills
Don't explain what is obvious from the command
Don't provide multiple examples for the same pattern

Validation:

wc -w skills/path/SKILL.md
# getting-started 工作流：目标 <150 每个
# 其他频繁加载的：目标总计 <200

Name it after what you do or the 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 describing processes:

creating-skills、testing-skills、debugging-with-logs
Active, describes the operation you are performing

4. Cross-reference other skills

When writing documentation that references other skills:

Use only the skill name, with a clear required marker:

✅ Good:**必需子技能：** 使用 superpowers:test-driven-development
✅ Good:**必需背景：** 你必须理解 superpowers:systematic-debugging
❌ Bad:参见 skills/testing/test-driven-development(unclear whether required)
❌ Bad:@skills/testing/test-driven-development/SKILL.md(forces loading, wastes context)

Why not use @ links: @ syntax immediately forces the file to load, consuming 200k+ of context before you need it.

Flowchart usage

digraph when_flowchart {
    "需要展示信息?" [shape=diamond];
    "我可能在决策中犯错?" [shape=diamond];
    "使用 markdown" [shape=box];
    "小型内联流程图" [shape=box];

    "需要展示信息?" -> "我可能在决策中犯错?" [label="是"];
    "我可能在决策中犯错?" -> "小型内联流程图" [label="是"];
    "我可能在决策中犯错?" -> "使用 markdown" [label="否"];
}

Use flowcharts only in the following cases:

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 code blocks
Linear instructions → numbered lists
Labels with no semantic meaning (step1, helper2)

See @graphviz-conventions.dot for graphviz style rules.

Visualize for your partner: Use the render-graphs.js in this directory to render a skill's flowchart as SVG:

./render-graphs.js ../some-skill           # 每个图表分别渲染
./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG

Code examples

One excellent example beats many mediocre ones

Choose the most relevant language:

Testing techniques → TypeScript/JavaScript
System debugging → Shell/Python
Data processing → Python

Good examples:

Complete and runnable
Well commented, explaining why
From real scenarios
Clearly demonstrate the pattern
Can be adapted directly (not a generic template)

Don't:

Implement in 5+ languages
Create fill-in-the-blank template
Write a human-constructed example

You are good at language transplantation—one excellent example is enough.

File Organization

Self-Contained Skill

defense-in-depth/
  SKILL.md    # 所有内容内联

Use case: everything fits, no need for extensive references

Skill with Reusable Tools

condition-based-waiting/
  SKILL.md    # 概述 + 模式
  example.ts  # 可适配的工作代码

Use case: the tools are reusable code, not just prose

Skill with Extensive References

pptx/
  SKILL.md       # 概述 + 工作流
  pptxgenjs.md   # 600 行 API 参考
  ooxml.md       # 500 行 XML 结构
  scripts/       # 可执行工具

Use case: too much reference material to inline

Iron Rules (Same as TDD)

没有失败的测试就不写技能

This applies to new skills and edits to existing skills.

Write the skill first, then test it? Delete it. Start over. Edit the skill without testing it? Same violation.

No Exceptions:

Does not apply to "simple additions"
Does not apply to "just adding one section"
Does not apply to "documentation updates"
Do not keep untested changes as "reference"
Do not "tweak" while running tests
Delete means delete

Required Background: The superpowers:test-driven-development skill explains why this matters. The same principles apply to documentation.

Test All Skill Types

Different types of skills require different testing methods:

Discipline-Enforcement Skills (Rules/Requirements)

For example: TDD, verification before completion, design before coding

How to test:

Academic questions: Do they understand the rules?
Pressure scenarios: Do they comply under pressure?
Multiple pressure combinations: time + sunk cost + exhaustion
Identify rationalizations and add explicit rebuttals

Success criteria: The agent follows the rules under maximum pressure

Technical Skills (How-To Guides)

For example: condition-based-waiting、root-cause-tracing、defensive-programming

How to test:

Application scenarios: Can they apply the technique correctly?
Variant scenarios: Can they handle edge cases?
Missing information test: Are there omissions in the instructions?

Success criteria: The agent successfully applies the technique to new scenarios

Pattern Skills (Mental Models)

For example: reducing-complexity, information-hiding concepts

How to test:

Recognition scenarios: Can they recognize when the pattern applies?
Application scenarios: Can they use the mental model?
Counterexamples: Do they know when not to apply it?

Success criteria: The agent correctly identifies when/how to apply the pattern

Reference Skills (Documentation/API)

For example: API documentation, command reference, library guides

How to test:

Retrieval scenarios: Can they find the correct information?
Application scenarios: Can they correctly use what they find?
Coverage test: Are common use cases all covered?

Success criteria: The agent finds and correctly applies the reference information

Common Rationalizations for Skipping Tests

Excuse	Reality
"The skill is obviously clear"	Clear to you ≠ clear to other agents. Test it.
"This is just reference material"	Reference material may have omissions or unclear points. Test retrieval.
"Testing is too much"	Untested skills always have problems. 15 minutes of testing saves hours.
"Test when there's a problem"	A problem = the agent can't use the skill. Test before deployment.
"Testing is too tedious"	Testing is far less tedious than debugging a bad skill in production.
"I'm confident it's good"	Overconfidence guarantees problems. Test anyway.
"Academic review is enough"	Reading ≠ using. Test the application scenarios.
"No time to test"	Deploying an untested skill wastes more time than fixing it later.

All of the above means: test before deployment. No exceptions.

Make skills withstand the test of rationalization

Skills that enforce discipline (such as TDD) need to resist rationalization. Agents are smart and will find loopholes under pressure.

Psychology note: Understanding why persuasion techniques work helps you apply them systematically. See persuasion-principles.md for the research basis (Cialdini, 2021; Meincke et al., 2025), covering authority, commitment, scarcity, social proof, and the principle of belonging.

Explicitly close every loophole

Don't just state the rule—prohibit specific workarounds:

No exceptions:

Don't keep it as "reference"
Don't "adjust" it while writing tests
Don't look at it
Delete means delete

</Good>

### 应对"精神 vs 字面"的辩论

在前面加入基础原则：

```markdown
**违反规则的字面意思就是违反规则的精神。**

This cuts off the entire class of "I'm following the spirit" rationalization excuses.

Build a rationalization excuse table

Capture rationalization excuses from baseline tests (see the testing section below). Every excuse the agent uses goes into the table:

| 借口 | 现实 |
|------|------|
| "太简单不值得测试" | 简单的代码也会出错。测试只需 30 秒。 |
| "我后面再测试" | 测试立即通过什么也证明不了。 |
| "后写测试效果一样" | 后写测试 = "这做了什么？" 先写测试 = "这应该做什么？" |

Create a red-line list

Make it easy for the agent to self-check whether it is rationalizing:

## 红线 - 停下来重新开始

- 先写代码再写测试
- "我已经手动测试过了"
- "后写测试效果一样"
- "重要的是精神不是仪式"
- "这个情况不同，因为……"

**以上所有都意味着：删除代码。用 TDD 重新开始。**

Update the CSO to include violation symptoms

Add to the description: symptoms of when you are about to violate the rule:

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

Red-green-refactor for skills

Follow the TDD cycle:

Red: write a failing test (baseline)

Run the stress scenarios without the skill. Record the behavior verbatim:

What choices did they make?
What rationalization excuses did they use (verbatim)?
Which pressures triggered violations?

This is "watch the test fail"—before writing the skill you must see what the agent naturally does.

Green: write the minimal skill

Write a skill targeting those specific rationalization excuses. Don't add extra content for hypothetical situations.

Run the same scenarios with the skill. The agent should now comply.

Refactor: close the loopholes

Did the agent find new rationalization excuses? Add explicit rebuttals. Retest until airtight.

Testing methodology: See @testing-skills-with-subagents.md for the full testing methodology:

How to write stress scenarios
Stress types (time, sunk cost, authority, exhaustion)
Systematically close loopholes
Meta-testing techniques

Anti-patterns

Narrative examples

"In the session on 2025-10-03, we discovered that an empty projectDir caused..." Why it's bad: Too specific, not reusable

Multilingual dilution

example-js.js、example-py.py、example-go.go Why it's bad: Mediocre quality, heavy maintenance burden

Code in flowcharts

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

Why it's bad: Cannot copy-paste, hard to read

Generic labels

helper1、helper2、step3、pattern4 Why it's bad: Labels should have semantic meaning

STOP: Before moving on to the next skill

After writing any skill, you must stop and complete the deployment process.

Do not:

Create multiple skills in bulk without testing them one by one
Move on to the next one before the current skill is verified
Skip testing because "batch processing is more efficient"

The deployment checklist below is mandatory for every skill.

Deploying an untested skill = deploying untested code. This is a violation of quality standards.

Skill creation checklist (TDD adapted version)

Important: Use TodoWrite to create a todo for each checklist item below.

Red phase - Write a failing test:

Create stress scenarios (discipline-type skills require 3 or more combined pressures)
Run the scenario without the skill - record baseline behavior verbatim
Identify patterns in rationalization excuses

Green phase - Write the minimal skill:

Name uses only letters, numbers, hyphens (no parentheses/special characters)
YAML frontmatter contains the required name and description fields (max 1024 characters; see spec）
Description starts with "Use when..." and includes specific trigger conditions/symptoms
Description uses third person
Include search keywords throughout (errors, symptoms, tools)
Clear overview with core principles
Address the specific baseline failures identified in the red phase
Code inline or linked to separate files
One excellent example (non-multilingual)
Run the scenario with the skill - verify the agent now complies

Refactor phase - Close loopholes:

Identify new rationalization excuses from testing
Add explicit rebuttals (discipline-type skills)
Build a rationalization excuse table from all test iterations
Create a red-line list
Retest until it is airtight

Quality check:

Use small flowcharts only when the decision is not obvious
Quick reference table
Common mistakes section
No narrative stories
Supporting files only for tools or extensive reference

Deployment:

Commit the skill to git and push to your fork (if configured)
Consider contributing back via PR (if it has broad use)

Discovery workflow

How future Claude finds your skill:

Encounters a problem("tests are flaky")
Finds the skill(Descriptive match)
Browsing overview(Is this relevant?)
Reading mode(Quick reference table)
Load example(only during implementation)

Optimized for this process - Put searchable terms at the front and throughout.

Summary

Creating skill is the TDD of process documentation.

The same iron law: don't write a skill without a failing test. The same loop: red (baseline) → green (write the skill) → refactor (plug the holes). The same benefits: higher quality, fewer surprises, bulletproof results.

If you follow TDD for code, you should do the same for skills. It's the same discipline applied to documentation.

About this skill

Overview

What Is a Skill?

TDD Mapped to Skills

When to Create a Skill

Skill Types

Technique-based

Pattern types

Reference types

Directory structure

SKILL.md structure

Claude Search Optimization (CSO)

1. Rich description field

2. Keyword coverage

3. Descriptive naming

4. Token efficiency (critical)

4. Cross-reference other skills

Flowchart usage

Code examples

File Organization

Self-Contained Skill

Skill with Reusable Tools

Skill with Extensive References

Iron Rules (Same as TDD)

Test All Skill Types

Discipline-Enforcement Skills (Rules/Requirements)

Technical Skills (How-To Guides)

Pattern Skills (Mental Models)

Reference Skills (Documentation/API)

Common Rationalizations for Skipping Tests

Make skills withstand the test of rationalization

Explicitly close every loophole

Build a rationalization excuse table

Create a red-line list

Update the CSO to include violation symptoms

Red-green-refactor for skills

Red: write a failing test (baseline)

Green: write the minimal skill

Refactor: close the loopholes

Anti-patterns

Narrative examples

Multilingual dilution

Code in flowcharts

Generic labels

STOP: Before moving on to the next skill

Skill creation checklist (TDD adapted version)

Discovery workflow

Summary