capability-documentation

编写技能

概述

编写技能就是将测试驱动开发应用于流程文档。

个人技能存放在 Agent 专属目录中（Claude Code 为 ~/.claude/skills，Codex 为 ~/.codex/skills）

你编写测试用例（使用子 Agent 的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（Agent 遵守），然后重构（封堵漏洞）。

核心原则： 如果你没有观察过 Agent 在没有该技能时失败，你就不知道这个技能教的东西是否正确。

必备背景： 使用本技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。本技能将 TDD 适配到文档编写。

官方指南： 关于 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。该文档提供了额外的模式和指南，与本技能以 TDD 为核心的方法相辅相成。

什么是技能？

技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。

技能是： 可复用的技术、模式、工具、参考指南

技能不是： 关于你曾经如何解决某个问题的叙事

技能的 TDD 映射

TDD 概念	技能创建
测试用例	使用子 Agent 的压力场景
生产代码	技能文档（SKILL.md）
测试失败（RED）	Agent 在没有技能时违反规则（基线）
测试通过（GREEN）	Agent 在技能存在时遵守规则
重构	在保持遵守的同时封堵漏洞
先写测试	在编写技能之前运行基线场景
观察它失败	记录 Agent 使用的确切合理化说辞
最小代码	编写针对这些具体违规行为的技能
观察它通过	验证 Agent 现在遵守规则
重构循环	发现新的合理化说辞 → 封堵 → 重新验证

整个技能创建过程遵循 RED-GREEN-REFACTOR。

何时创建技能

在以下情况创建：

• 技术对你来说并非显而易见
• 你会在跨项目中再次参考它
• 模式广泛适用（不是项目特定的）
• 其他人会从中受益

不要为以下情况创建：

• 一次性解决方案
• 在其他地方已有充分文档的标准实践
• 项目特定的约定（放入 CLAUDE.md）

技能类型

技术

带有可遵循步骤的具体方法（condition-based-waiting、root-cause-tracing）

模式

思考问题的方式（flatten-with-flags、test-invariants）

参考

API 文档、语法指南、工具文档（office docs）

目录结构

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

扁平命名空间 - 所有技能都在一个可搜索的命名空间中

以下情况使用单独文件：

1. 大量参考内容（100+ 行） - API 文档、全面的语法
2. 可复用工具 - 脚本、实用程序、模板

保持内联：

• 原则和概念
• 代码模式（< 50 行）
• 其他所有内容

SKILL.md 结构

前置元数据（YAML）：

• 仅支持两个字段：name 和 description
• 总计最多 1024 个字符
• name：仅使用字母、数字和连字符（不使用括号、特殊字符）
• description：第三人称，仅描述何时使用（而不是它做什么）
  • 以“Use when...”开头，聚焦于触发条件
  • 包含具体的症状、情况和上下文
  • 绝不要总结技能的过程或工作流（原因见 CSO 部分）
  • 尽可能保持在 500 个字符以下

---
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 results

Claude 搜索优化（CSO）

对发现至关重要： 未来的 Claude 需要找到你的技能

1. 丰富的描述字段

目的： Claude 会读取 description 来决定为给定任务加载哪些技能。让它回答："我现在应该读取这个技能吗？"

格式： 以"当……时使用"开头，聚焦触发条件

关键：Description = 何时使用，而非技能做什么

description 应只描述触发条件。不要在 description 中总结技能的流程或工作流。

为什么这很重要： 测试表明，当 description 总结了技能的工作流时，Claude 可能会遵循 description，而不是读取完整的技能内容。一个写着"任务之间的代码审查"的 description 导致 Claude 只做了一次审查，尽管技能的流程图清楚地显示需要两次审查（规范符合性审查，然后是代码质量审查）。

当 description 改为仅"在执行具有独立任务的实现计划时使用"（不包含工作流总结）后，Claude 正确地读取了流程图并遵循了两阶段审查流程。

陷阱： 总结工作流的 description 制造了 Claude 会走捷径的通道。技能正文变成了 Claude 跳过的文档。

# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• 使用具体的触发器、症状和表明此技能适用的情境
• 描述问题（竞态条件、行为不一致），而非特定语言的症状（setTimeout、sleep）
• 保持触发器与技术无关，除非技能本身是特定于技术的
• 如果技能是特定于技术的，请在触发器中明确说明
• 使用第三人称书写（注入到系统提示词中）
• 绝不要总结技能的流程或工作流

# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# ❌ BAD: First person
description: I can help you with async tests when they're flaky

# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects

2. 关键词覆盖

使用 Claude 会搜索的词语：

• 错误消息："Hook timed out"、"ENOTEMPTY"、"race condition"
• 症状："flaky"、"hanging"、"zombie"、"pollution"
• 同义词："timeout/hang/freeze"、"cleanup/teardown/afterEach"
• 工具：实际命令、库名、文件类型

3. 描述性命名

使用主动语态，动词优先：

• ✅ creating-skills 而非 skill-creation
• ✅ condition-based-waiting 而非 async-test-helpers

4. Token 效率（关键）

问题： getting-started 和频繁引用的技能会加载到每次对话中。每个 token 都很重要。

目标词数：

• getting-started 工作流：每个 <150 词
• 频繁加载的技能：总计 <200 词
• 其他技能：<500 词（仍需简洁）

技巧：

将细节移到工具帮助中：

# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

压缩示例：

# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

消除冗余：

• 不要重复交叉引用技能中的内容
• 不要解释从命令中显而易见的内容
• 不要包含同一模式的多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

按你做什么或核心洞察来命名：

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills 而非 skill-usage
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

动名词（-ing）适合表示流程：

• creating-skills、testing-skills、debugging-with-logs
• 主动式，描述你正在执行的操作

4. 交叉引用其他技能

在编写引用其他技能的文档时：

仅使用技能名称，并带有明确的要求标记：

• ✅ 正确：**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
• ✅ 正确：**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
• ❌ 错误：See skills/testing/test-driven-development（不清楚是否为必需）
• ❌ 错误：@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）

为什么不用 @ 链接： @ 语法会立即强制加载文件，在你需要它们之前就消耗 200k+ 的上下文。

流程图使用

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"];
}

仅将流程图用于：

• 不明显的决策点
• 可能过早停止的过程循环
• “何时用 A 还是 B”的决策

绝不要将流程图用于：

• 参考资料 → 表格、列表
• 代码示例 → Markdown 块
• 线性指令 → 编号列表
• 无语义含义的标签（step1、helper2）

关于 graphviz 风格规则，参见 @graphviz-conventions.dot。

为你的真人搭档可视化： 使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

代码示例

一个优秀的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 → TypeScript/JavaScript
• 系统调试 → Shell/Python
• 数据处理 → Python

好的示例：

• 完整且可运行
• 注释良好，解释 WHY
• 来自真实场景
• 清晰地展示模式
• 可直接改编（不是通用模板）

不要：

• 用 5 种以上语言实现
• 创建填空式模板
• 编写生造的示例

你擅长移植——一个出色的示例就足够。

文件组织

自包含技能

defense-in-depth/
  SKILL.md    # Everything inline

何时：所有内容都放得下，无需大量参考

带可复用工具的技能

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

何时：工具是可复用的代码，而不仅是叙述

带大量参考资料的技能

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

何时：参考资料太大，无法内联

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

这适用于新技能以及对现有技能的编辑。

先写技能再测试？删除它。重新开始。 编辑技能而不测试？同样违规。

没有例外：

• 不适用于“简单添加”
• 不适用于“只是添加一节”
• 不适用于“文档更新”
• 不要将未测试的改动保留为“参考”
• 不要在运行测试时“改编”
• 删除就是删除

必需背景： superpowers:test-driven-development 技能解释了这为何重要。同样的原则适用于文档。

测试所有技能类型

不同的技能类型需要不同的测试方法：

纪律约束型技能（规则/要求）

示例： TDD、verification-before-completion、designing-before-coding

测试方式：

• 学术性问题：他们理解规则吗？
• 压力场景：他们在压力下会遵守吗？
• 多种压力叠加：时间 + 沉没成本 + 疲惫
• 找出合理化借口并添加明确的应对措施

成功标准： Agent 在最大压力下遵守规则

技术型技能（操作指南）

示例： condition-based-waiting、root-cause-tracing、defensive-programming

测试方式：

• 应用场景：他们能正确应用该技术吗？
• 变体场景：他们能处理边缘情况吗？
• 缺失信息测试：指令有遗漏吗？

成功标准： Agent 成功将技术应用于新场景

模式型技能（心智模型）

示例： reducing-complexity、information-hiding 概念

测试方式：

• 识别场景：他们能识别模式何时适用吗？
• 应用场景：他们能使用该心智模型吗？
• 反例：他们知道何时不该应用吗？

成功标准： Agent 正确识别何时/如何应用模式

参考型技能（文档/API）

示例： API 文档、命令参考、库指南

测试方式：

• 检索场景：他们能找到正确的信息吗？
• 应用场景：他们能正确使用找到的内容吗？
• 缺口测试：常见用例都覆盖了吗？

成功标准： Agent 找到并正确应用参考信息

跳过测试的常见合理化借口

借口	现实
“技能显然很清晰”	对你清晰 ≠ 对其他 Agent 清晰。测试它。
“这只是个参考”	参考可能有遗漏、章节不清晰。测试检索。
“测试是过度设计”	未经测试的技能必定有问题。总是如此。15 分钟测试能省下数小时。
“有问题我再测试”	问题 = Agent 无法使用技能。部署前就要测试。
“测试太繁琐”	测试比在生产环境调试糟糕技能要不繁琐得多。
“我有信心它很好”	过度自信必然带来问题。无论如何都要测试。
“学术评审就够了”	阅读 ≠ 使用。测试应用场景。
“没时间测试”	部署未经测试的技能，之后修复会浪费更多时间。

所有这些都意味着：部署前先测试。没有例外。

为技能加固以抵御合理化

强制纪律的技能（如 TDD）需要抵御合理化。Agent 很聪明，在压力下会寻找漏洞。

心理学提示： 理解说服技巧为何有效，有助于你系统地应用它们。关于权威、承诺、稀缺、社会认同和统一原则的研究基础（Cialdini, 2021; Meincke et al., 2025），参见 persuasion-principles.md。

明确堵住每一个漏洞

不要只是陈述规则——要禁止具体的变通做法：

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

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

</Good>

### 应对“精神 vs 字面”的争论

尽早加入基础原则：

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

这会切断一整类“我遵循的是精神”的合理化。

构建合理化表

从基线测试中捕获合理化（见下文测试部分）。Agent 提出的每一个借口都放进表里：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

创建红旗清单

让 Agent 在合理化时能轻松自查：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

针对违规症状更新 CSO

在 description 中加入：你即将违反规则时的症状：

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

技能的 RED-GREEN-REFACTOR

遵循 TDD 循环：

RED：编写失败的测试（基线）

在 WITHOUT 该技能的情况下，用 subagent 运行压力场景。记录确切行为：

• 他们做了哪些选择？
• 他们使用了哪些合理化（逐字记录）？
• 哪些压力触发了违规？

这就是“看着测试失败”——在编写技能之前，你必须看到 Agent 自然会怎么做。

GREEN：编写最小技能

编写针对那些具体合理化的技能。不要为假设情况添加额外内容。

WITH 该技能运行相同场景。Agent 现在应该遵守。

REFACTOR：堵住漏洞

Agent 发现了新的合理化？添加明确的应对。重新测试直到无懈可击。

测试方法论： 完整测试方法论见 @testing-skills-with-subagents.md：

• 如何编写压力场景
• 压力类型（时间、沉没成本、权威、疲惫）
• 系统性地填补漏洞
• 元测试技巧

反模式

❌ 叙事式示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致……” 为什么不好： 太具体，不可复用

❌ 多语言稀释

example-js.js, example-py.py, example-go.go 为什么不好： 质量平庸，维护负担

❌ 流程图中的代码

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

为什么不好： 无法复制粘贴，难以阅读

❌ 通用标签

helper1, helper2, step3, pattern4 为什么不好： 标签应具有语义含义

停止：在进入下一个技能之前

编写 ANY 技能之后，你必须停止并完成部署流程。

不要：

• 批量创建多个技能而不逐个测试
• 在当前技能验证之前就进入下一个技能
• 因为“批处理更高效”而跳过测试

下面的部署清单对 EACH 技能都是强制性的。

部署未经测试的技能 = 部署未经测试的代码。这违反了质量标准。

技能创建检查清单（TDD 改编版）

重要：使用 TodoWrite 为以下每个检查清单项创建待办事项。

RED 阶段 - 编写失败测试：

• 创建压力场景（纪律类技能需组合 3 个以上压力）
• 在没有技能的情况下运行场景 - 逐字记录基线行为
• 识别合理化/失败中的模式

GREEN 阶段 - 编写最小技能：

• 名称仅使用字母、数字、连字符（不使用括号/特殊字符）
• YAML frontmatter 仅包含 name 和 description（最多 1024 个字符）
• description 以「Use when...」开头，并包含具体的触发条件/症状
• description 使用第三人称书写
• 全程使用关键词以便搜索（错误、症状、工具）
• 清晰的概述，包含核心原则
• 解决 RED 阶段识别出的具体基线失败
• 代码内联或提供链接
• 一个优秀的示例（而非多语言）
• 在有技能的情况下运行场景 - 验证 Agent 现在会遵守

REFACTOR 阶段 - 堵住漏洞：

• 识别测试中出现的新的合理化
• 添加明确的应对措施（如果是纪律类技能）
• 根据所有测试迭代构建合理化对照表
• 创建危险信号列表
• 反复测试直到无懈可击

质量检查：

• 仅在决策不明显时提供小型流程图
• 快速参考表
• 常见错误
• 不要叙述性讲故事
• 支持文件仅用于工具或大量内容

部署：

• 将技能提交到仓库并推送（如果已配置）
• 考虑通过 PR 回馈（如果广泛有用）

发现工作流

未来的 Claude 如何找到你的技能：

1. 遇到问题（「测试不稳定」）
2. 找到 SKILL（description 匹配）
3. 浏览概述（这相关吗？）
4. 阅读模式（快速参考表）
5. 加载示例（仅在实施时）

针对此流程优化 - 将可搜索的术语尽早、频繁地放置。

核心要点

创建技能就是流程文档的 TDD。

铁律：没有失败测试就不创建技能。 同样的循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。 同样的收益：更高质量、更少意外、无懈可击的结果。

如果你对代码遵循 TDD，那么对技能也应如此。这是同样的纪律应用于文档。