编写技能

概述

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

个人技能存放在特定于智能体的目录中（Claude Code 为 ~/.claude/skills，Codex 为 ~/.agents/skills/）

你编写测试用例（涉及子智能体的压力场景），看着它们失败（基线行为），编写技能（文档），看着测试通过（智能体遵循规则），然后重构（堵住漏洞）。

核心原则：如果你没有看到智能体在没有该技能的情况下失败，你就不知道这个技能是否教会了正确的东西。

必需背景知识：在使用此技能之前，你必须理解 superpowers:test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 应用于文档编写。

官方指南：关于 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了额外的模式和指南，补充了本技能中专注于 TDD 的方法。

什么是技能？

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

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

技能不是：关于你如何解决一个问题的叙述性故事

技能编写的 TDD 映射

TDD 概念	技能创建
测试用例	包含子智能体的压力场景
生产代码	技能文档 (SKILL.md)
测试失败（红）	没有技能时，智能体违反规则（基线）
测试通过（绿）	有技能时，智能体遵守规则
重构	在保持遵守规则的前提下堵住漏洞
先写测试	在编写技能前运行基线场景
看着它失败	记录智能体使用的确切理由
最少代码	编写专门针对这些特定违规行为的技能
看着它通过	验证智能体现在遵守规则
重构循环	发现新的理由 → 堵住 → 重新验证

整个技能创建过程遵循红-绿-重构。

何时创建技能

当以下情况时创建：

• 某项技术对你来说并非直观显而易见
• 你会在不同项目中再次引用此内容
• 模式具有广泛适用性（非项目特定）
• 其他人会从中受益

不要为以下情况创建：

• 一次性解决方案
• 在其他地方已有完善文档的标准实践
• 项目特定的约定（放在 CLAUDE.md 中）
• 机械性约束（如果可以通过正则表达式/验证来强制执行，就自动化它——文档留给需要判断的决策）

技能类型

技术

包含可遵循步骤的具体方法（基于条件的等待、根本原因追踪）

模式

思考问题的方式（使用标志扁平化、测试不变量）

参考

API 文档、语法指南、工具文档（办公文档）

目录结构

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

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

以下情况使用单独文件：

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

保持内联：

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

SKILL.md 结构

前置元数据 (YAML)：

• 仅支持两个字段：name 和 description
• 总字符数最多 1024
• name：仅使用字母、数字和连字符（无括号、特殊字符）
• description：使用第三人称，仅描述何时使用（非技能内容）
  • 以“当…时使用”开头，聚焦于触发条件
  • 包含具体的症状、情况和上下文
  • 切勿总结技能的流程或工作流程（参见 CSO 部分了解原因）
  • 如可能，保持在 500 字符以内

---
name: Skill-Name-With-Hyphens
description: 当 [具体的触发条件和症状] 时使用
---

# 技能名称

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

## 何时使用
[如果决策不直观，可添加小型内联流程图]

包含症状和使用场景的列表
何时不应使用

## 核心模式（针对技术/模式）
修改前/修改后的代码对比

## 快速参考
用于扫描常见操作的表格或列表

## 实施
简单模式的内联代码
对于庞大参考或可复用工具，链接到文件

## 常见错误
哪里会出错 + 修复方法

## 实际影响（可选）
具体成果

Claude 搜索优化 (CSO)

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

1. 丰富的描述字段

目的：Claude 通过阅读描述来决定为给定任务加载哪些技能。让它能回答：“我现在应该阅读这个技能吗？”

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

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

描述应该仅描述触发条件。切勿在描述中总结技能的工作流程。

为何如此重要：测试表明，当描述总结了技能的工作流程时，Claude 可能会遵循描述而不是阅读完整的技能内容。一个说“在任务之间进行代码审查”的描述导致 Claude 只进行了一次审查，即使技能的流程图清楚地显示了两次审查（规范符合性然后代码质量）。

当描述改为“当执行包含独立任务的实施计划时使用”（无工作流程总结）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。

陷阱：总结工作流程的描述为 Claude 创建了一条捷径。技能正文变成了被跳过的文档。

# ❌ 错误：总结了工作流程 - Claude 可能遵循此描述而非阅读技能
description: 当执行计划时使用 - 为每个任务分派子智能体，并在任务之间进行代码审查

# ❌ 错误：流程细节过多
description: 用于 TDD - 先写测试, 看着它失败, 编写最少代码, 重构

# ✅ 正确：仅触发条件，无工作流程总结
description: 当在当前会话中执行包含独立任务的实施计划时使用

# ✅ 正确：仅触发条件
description: 当实现任何功能或错误修复时，在编写实施代码之前使用

内容：

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

# ❌ 错误：过于抽象、模糊，不包含何时使用
description: 用于异步测试

# ❌ 错误：第一人称
description: 我可以在测试不稳定时帮助你处理异步测试

# ❌ 错误：提到了技术，但技能并非针对该技术
description: 当测试使用 setTimeout/sleep 且不稳定时使用

# ✅ 正确：以“当...时使用”开头，描述问题，无工作流程
description: 当测试存在竞态条件、时间依赖性或通过/失败不一致时使用

# ✅ 正确：特定于技术的技能，有明确的触发器
description: 当使用 React Router 并处理身份验证重定向时使用

2. 关键词覆盖

使用 Claude 可能会搜索的词：

• 错误消息：”钩子超时”、”ENOTEMPTY”、”竞态条件”
• 症状：”不稳定”、”挂起”、”僵尸”、”污染”
• 同义词：”超时/挂起/冻结”、”清理/拆卸/afterEach”
• 工具：实际命令、库名、文件类型

3. 描述性命名

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

• ✅ creating-skills 优于 skill-creation
• ✅ condition-based-waiting 优于 async-test-helpers

4. 令牌效率（关键）

问题：入门指南和经常被引用的技能会加载到每一次对话中。每个令牌都很重要。

目标字数：

• 入门工作流程：每个 <150 词
• 常加载技能：总计 <200 词
• 其他技能：<500 词（仍需简洁）

技巧：

将细节移至工具帮助：

# ❌ 错误：在 SKILL.md 中记录所有标志
search-conversations 支持 --text, --both, --after 日期, --before 日期, --limit 数量

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

使用交叉引用：

# ❌ 错误：重复工作流程细节
搜索时，使用模板分派子智能体...
[20 行重复指令]

# ✅ 正确：引用其他技能
始终使用子智能体（节省 50-100 倍上下文）。必需：对于工作流程，使用 [其他技能名称]。

压缩示例：

# ❌ 错误：冗长示例（42 词）
你的伙伴：“我们之前在 React Router 中是如何处理身份验证错误的？”
你：我将搜索过去的对话以查找 React Router 身份验证模式。
[分派子智能体，搜索查询："React Router authentication error handling 401"]

# ✅ 正确：最小示例（20 词）
伙伴：“我们之前是如何在 React Router 中处理身份验证错误的？”
你：正在搜索...
[分派子智能体 → 综合]

消除冗余：

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

验证：

wc -w skills/path/SKILL.md
# 入门工作流程：目标 <150 词每个
# 其他常加载技能：目标总计 <200 词

根据你做什么或核心见解来命名：

• ✅ 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. 交叉引用其他技能

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

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

• ✅ 正确：**必需的子技能：** 使用 superpowers:test-driven-development
• ✅ 正确：**必需的背景知识：** 你必须理解 superpowers:systematic-debugging
• ❌ 错误：请参阅 skills/testing/test-driven-development（不清楚是否必需）
• ❌ 错误：@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）

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

流程图的使用

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

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

仅在以下情况使用流程图：

• 不直观的决策点
• 可能过早停止的流程循环
• “何时使用 A 对比 B”的决策

切勿在以下情况使用流程图：

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

请参阅 @graphviz-conventions.dot 了解 graphviz 样式规则。

为你的伙伴进行可视化：使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：

./render-graphs.js ../某个技能           # 每个图表单独生成
./render-graphs.js ../某个技能 --combine # 所有图表合并为一个 SVG

代码示例

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

选择最相关的语言：

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

好的示例：

• 完整且可运行
• 有良好注释解释原因
• 来自真实场景
• 清晰地展示模式
• 准备好供人改编（非通用模板）

不要：

• 用 5 种以上语言实现
• 创建填空式模板
• 编写人为的例子

你很擅长移植——一个优秀的示例就足够了。

文件组织

自包含技能

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

适用情况：所有内容都能容纳，不需要庞大的参考

带有可复用工具的技能

condition-based-waiting/
  SKILL.md    # 概述 + 模式
  example.ts  # 可供改编的工作示例

适用情况：工具是可复用的代码，而不仅仅是叙述

带有庞大参考的技能

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

适用情况：参考资料太大，无法内联

铁律（与 TDD 相同）

没有先经过失败的测试，就不能创建技能

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

在测试之前编写了技能？删掉它。重新开始。
未经测试就编辑技能？同样是违规。

没有例外：

• 不适用于“简单添加”
• 不适用于“只是增加一个章节”
• 不适用于“文档更新”
• 不要将未经验证的更改留作“参考”
• 不要在运行测试时“改编”代码
• 删掉就是删掉

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

测试所有技能类型

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

纪律性技能（规则/要求）

示例： TDD、完成前验证、先设计后编码

测试方法：

• 学术性问题：他们理解规则吗？
• 压力场景：他们在压力下遵守规则吗？
• 多种压力组合：时间 + 沉没成本 + 疲惫
• 识别出的理由并添加明确的反对理由

成功标准：智能体在最大压力下仍遵守规则

技术性技能（操作指南）

示例： 基于条件的等待、根本原因追踪、防御性编程

测试方法：

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

成功标准：智能体成功地将技术应用于新场景

模式性技能（思维模型）

示例： 降低复杂性、信息隐藏概念

测试方法：

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

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

参考性技能（文档/API）

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

测试方法：

• 检索场景：他们能找到正确的信息吗？
• 应用场景：他们能正确使用找到的信息吗？
• 漏洞测试：常见用例是否被覆盖？

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

跳过测试的常见借口

借口	现实
“技能显然很清楚”	你清楚 ≠ 其他智能体清楚。测试它。
“这只是个参考”	参考资料也可能有漏洞、不清楚的部分。测试检索。
“测试太过了”	未经测试的技能总是有问题。15 分钟测试能省下几小时。
“如果有问题我再测试”	问题 = 智能体无法使用技能。部署前测试。
“测试太繁琐”	测试比在生产环境中调试有问题的技能要省事得多。
“我有信心它很好”	过度自信保证会有问题。无论如何都要测试。
“学术审查就够了”	阅读 ≠ 使用。测试应用场景。
“没时间测试”	部署未经测试的技能，之后花更多时间修复它，更浪费时间。

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

使技能免受理由的侵蚀

执行纪律的技能（如 TDD）需要抵制理由的侵蚀。智能体很聪明，在压力下会找到漏洞。

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

明确地堵住每一个漏洞

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

没有例外：

• 不要把它留作“参考”
• 不要在编写测试时去“改编”它
• 不要看它
• 删掉就是删掉

</好>

### 处理“精神与文字”的争论

尽早添加基本原则：

```markdown
**违背规则的文字表述就是违背规则的精神。**

这堵住了整个一类“我在遵循精神”的借口。

建立理由表

从基线测试中捕获理由（参见下面的测试部分）。智能体提出的每一个借口都放进表中：

| 借口 | 现实 |
|--------|---------|
| “太简单了，不值得测试” | 简单的代码也会出错。写个测试只需 30 秒。 |
| “我之后会测试” | 立即通过的测试什么都证明不了。 |
| “后写测试能达到同样的目的” | 后写测试 = “这段代码是做什么的？”先写测试 = “这段代码应该做什么？” |

创建危险信号列表

让智能体在找借口时能轻松自我检查：

## 危险信号 - 停止并重新开始

- 先写代码后写测试
- “我已经手动测试过了”
- “后写测试能达到同样的目的”
- “重要的是精神，不是形式”
- “这次情况不同，因为……”

**所有这些都意味着：删掉代码。用 TDD 重新开始。**

更新 CSO 以包含违规症状

在描述中添加：你即将违反规则时的症状：

description: 当实现任何功能或错误修复时，在编写实施代码之前使用

技能编写的红-绿-重构

遵循 TDD 循环：

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

在没有该技能的情况下，使用子智能体运行压力场景。记录确切的行为：

• 他们做了什么选择？
• 他们用了什么理由（逐字记录）？
• 哪些压力触发了违规行为？

这是“看着测试失败”——你必须在编写技能之前看到智能体自然地做什么。

绿：编写最少技能

编写专门针对这些特定理由的技能。不要为假设情况添加额外内容。

使用技能运行相同的场景。智能体现在应该遵守规则。

重构：堵住漏洞

智能体发现了新的理由？添加明确的反对理由。重新测试直到无懈可击。

测试方法：请参阅 @testing-skills-with-subagents.md 了解完整的测试方法：

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

反模式

❌ 叙述性示例

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

❌ 多语言稀释

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

❌ 流程图中的代码

步骤1 [label="导入 fs"];
步骤2 [label="读取文件"];

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

❌ 通用标签

helper1, helper2, 步骤3, 模式4
为什么不好：标签应有语义含义

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

在编写完任何技能后，你必须停止并完成部署流程。

不要：

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

下面的部署清单对每个技能都是必需的。

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

技能创建清单（改编自 TDD）

重要：使用 TodoWrite 为下面清单中的每个项目创建待办事项。

红阶段 – 编写失败的测试：

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

绿阶段 – 编写最少技能：

• 名称仅使用字母、数字、连字符（无括号/特殊字符）
• YAML 前置元数据仅包含名称和描述（最多 1024 字符）
• 描述以“当…时使用”开头，并包含具体的触发器/症状
• 描述使用第三人称
• 通篇包含关键词以便搜索（错误、症状、工具）
• 清晰的概述，包含核心原则
• 解决在红阶段识别出的特定基线失败问题
• 代码内联或链接到单独文件
• 一个优秀的示例（非多语言）
• 在有技能的情况下运行场景 – 验证智能体现在遵守规则

重构阶段 – 堵住漏洞：

• 识别测试中出现的新理由
• 添加明确的反对理由（如果是纪律性技能）
• 从所有测试迭代中构建理由表
• 创建危险信号列表
• 重新测试直到无懈可击

质量检查：

• 仅在决策不直观时使用小型流程图
• 快速参考表格
• 常见错误部分
• 无叙述性故事
• 仅在有工具或庞大参考时才使用辅助文件

部署：

• 将技能提交到 git 并推送到你的分支（如果已配置）
• 考虑通过拉取请求回馈（如果技能具有广泛用途）

发现流程

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

1. 遇到问题（“测试不稳定”）
2. 找到技能（描述匹配）
3. 扫描概述（这相关吗？）
4. 阅读模式（快速参考表格）
5. 加载示例（仅在实施时）

为此流程优化 – 尽早且频繁地放置可搜索的术语。

底线

编写技能 就是将 TDD 应用于流程文档。

同样的铁律：没有先失败的测试，就没有技能。
同样的循环：红（基线）→ 绿（编写技能）→ 重构（堵住漏洞）。
同样的好处：质量更高、意外更少、效果无懈可击。

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