Writing Skills

编写技能

概述

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

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

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

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

必需背景： 在使用此技能前，你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。

官方指南： Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。

什么是技能？

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

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

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

TDD 映射到技能

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

何时创建技能

创建条件：

• 技术对你来说不是直觉上显而易见的
• 你会在不同项目中反复引用
• 模式具有广泛适用性（非项目特定）
• 其他人也会受益

不要创建：

• 一次性解决方案
• 其他地方有充分文档的标准实践
• 项目特定的约定（放在 CLAUDE.md 中）
• 机械性约束（如果可以用正则/验证强制执行，就自动化——文档留给需要判断的场景）

技能类型

技术类

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

模式类

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

参考类

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

目录结构

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

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

分离文件的情况：

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

保持内联：

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

SKILL.md 结构

Frontmatter（YAML）：

• 两个必需字段：name 和 description（完整支持字段参见 agentskills.io/specification）
• 总计最多 1024 字符
• name：只使用字母、数字和连字符（不要用括号、特殊字符）
• description：第三人称，仅描述何时使用（不是做什么）
  • 以"Use when..."开头，聚焦于触发条件
  • 包含具体的症状、场景和上下文
  • 绝不总结技能的流程或工作流（参见 SDO 章节了解原因）
  • 尽量控制在 500 字符以内

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

# 技能名称

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

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

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

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

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

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

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

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

技能发现优化（SDO）

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

1. 丰富的描述字段

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

格式： 以"Use when..."开头，聚焦于触发条件

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

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

为什么这很重要： 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着"任务间进行代码审查"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。

当描述改为仅"在当前会话中执行包含独立任务的实现计划时使用"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。

陷阱： 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。

# 错误：总结了工作流 - 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

内容：

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

# 错误：太抽象、模糊，未包含何时使用
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. 关键词覆盖

使用 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 词（仍要简洁）

技巧：

将细节移到工具帮助中：

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

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

使用交叉引用：

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

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

压缩示例：

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

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

消除冗余：

• 不要重复交叉引用的技能中已有的内容
• 不要解释从命令中就能看出的东西
• 不要为同一模式提供多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started 工作流：目标 <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
• 主动的，描述你正在进行的操作

5. 交叉引用其他技能

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

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

• ✅ 好的：**必需子技能：** 使用 test-driven-development
• ✅ 好的：**必需背景：** 你必须理解 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 vs B"的决策

绝不使用流程图用于：

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

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

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

./render-graphs.js ../some-skill           # 每个图表分别渲染
./render-graphs.js ../some-skill --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 相同）

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

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

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

无例外：

• 不适用于"简单的添加"
• 不适用于"只是加一个章节"
• 不适用于"文档更新"
• 不要保留未测试的更改作为"参考"
• 不要在运行测试时"调整"
• 删除就是删除

必需背景： test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。

测试所有技能类型

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

纪律执行类技能（规则/要求）

例如： TDD、完成前验证、编码前设计

测试方式：

• 学术性问题：它们理解规则吗？
• 压力场景：它们在压力下遵守吗？
• 多重压力组合：时间 + 沉没成本 + 疲惫
• 识别合理化借口并添加明确的反驳

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

技术类技能（操作指南）

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

测试方式：

• 应用场景：它们能正确应用技术吗？
• 变体场景：它们能处理边界情况吗？
• 缺失信息测试：说明是否有遗漏？

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

模式类技能（心智模型）

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

测试方式：

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

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

参考类技能（文档/API）

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

测试方式：

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

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

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

以上所有都意味着：部署前测试。无例外。

让形式匹配失败类型

在写指导内容之前，先给基线失败归类。能让某一类失败变得无懈可击的形式，用在另一类上会可测量地反噬。

为什么禁令在"塑形"类问题上会反噬： 在存在竞争性激励时（比如"让提示词自包含"），智能体会跟"不要 X"讨价还价。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显多于配方组（两组分布完全分离），甚至比"完全不给指导"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但永远不要把禁令当默认选择。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。

无论你选哪种形式，都适用的规则：

• 不要加"视情况"从句。 "不要 X，除非它很重要"会重新打开谈判 —— 在同一批措辞测试里，给一个胜出的配方追加一条"视情况"从句，就把它从稳定退化成了飘忽。真正的例外要表达成它自己的条件句，挂在可观察的谓词上。
• 豁免条款不会限定作用域。 "这条长度限制不适用于代码块"，照样会压制代码块。如果产出里有一部分必须豁免，就重构结构让规则碰不到它，而不是写豁免。

让技能经受住合理化的考验

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

心理学说明： 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。

明确堵住每个漏洞

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

无例外：

• 不要保留作为"参考"
• 不要在写测试时"调整"它
• 不要看它
• 删除就是删除

</Good>

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

在前面加入基础原则：

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

这切断了整类"我遵循的是精神"的合理化借口。

构建合理化借口表

从基线测试中捕获合理化借口（参见下方测试章节）。智能体使用的每个借口都进入表中：

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

创建红线列表

让智能体容易自查是否在合理化：

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

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

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

更新 SDO 以包含违规症状

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

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

技能的红-绿-重构

遵循 TDD 循环：

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

在没有技能的情况下运行压力场景。逐字记录行为：

• 它们做了什么选择？
• 它们使用了什么合理化借口（原文）？
• 哪些压力触发了违规？

这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。

绿：编写最小技能

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

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

重构：堵住漏洞

智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。

先做措辞微型测试，再跑完整场景

完整的压力场景是最后一道关卡，但它每轮迭代都又慢又贵。先用微型测试验证措辞本身：

1. 每次调用一个全新上下文的样本 —— 一次裸 API 调用，或者没有 API 权限时用一个单发子智能体。system prompt 放这条指导实际会存在的真实上下文（完整的 skill 或提示词模板，不是把指导单独拎出来）；user message 放一个会诱发该失败的任务。
2. 永远带一个"不给指导"的对照组。 如果对照组根本没表现出那个失败，那就没什么可修的 —— 停下，别写这条指导。
3. 每个变体至少 5 次重复。 单个样本会骗人。
4. 每一条被标记的命中都要人工读一遍。 想用程序打分可以，但模板回声和被引用的反例会伪装成命中；只看自动计数会同时高估失败和成功。
5. 方差本身就是一个指标。 指导真正生效时，多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读，说明这个措辞没有约束力 —— 先收紧形式，别急着加字。

微型测试验证的是措辞；对纪律执行类技能，它不能替代压力场景。

测试方法论： 参见 @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 为什么不好： 标签应有语义意义

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

编写任何技能后，你必须停下来完成部署流程。

不要：

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

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

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

技能创建清单（TDD 适配版）

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

红色阶段 - 编写失败的测试：

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

绿色阶段 - 编写最小技能：

• 名称只使用字母、数字、连字符（无括号/特殊字符）
• YAML frontmatter 包含必需的 name 和 description 字段（最多 1024 字符；参见 spec）
• 描述以"Use when..."开头并包含具体的触发条件/症状
• 描述用第三人称
• 全文包含搜索关键词（错误、症状、工具）
• 带有核心原则的清晰概述
• 解决红色阶段识别出的具体基线失败
• 代码内联或链接到独立文件
• 一个优秀的示例（非多语言）
• 用技能运行场景 - 验证智能体现在遵守

重构阶段 - 堵住漏洞：

• 从测试中识别新的合理化借口
• 添加明确的反驳（纪律类技能）
• 从所有测试迭代中构建合理化借口表
• 创建红线列表
• 重新测试直到无懈可击

质量检查：

• 仅在决策不明显时使用小流程图
• 快速参考表
• 常见错误章节
• 无叙事性故事
• 支持文件仅用于工具或大量参考

部署：

• 将技能提交到 git 并推送到你的 fork（如果已配置）
• 考虑通过 PR 贡献回去（如果具有广泛用途）

发现工作流

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

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

为此流程优化 - 把可搜索的术语放在前面和各处。