writing-skills

编写 Skills

概述

编写 Skills 就是把测试驱动开发（TDD）应用到流程文档上。

个人 Skills 存放在运行时的 skills 目录中（Claude Code 上为 ~/.claude/skills/）。这些运行时的路径请参见 codex-tools.md 或 gemini-tools.md。Codex、Copilot CLI 和 Gemini CLI 也都将 ~/.agents/skills/ 识别为跨运行时的别名。

你需要编写测试用例（使用子 Agent 的压力场景），观察其失败（基线行为），编写 Skill（文档），观察测试通过（Agent 遵守规则），然后重构（堵住漏洞）。

核心原则： 如果你没有观察到 Agent 在没有该 Skill 时失败，你就无法确定该 Skill 教授的内容是否正确。

必备背景： 在使用本 Skill 之前，你必须先理解 superpowers:test-driven-development。该 Skill 定义了 RED-GREEN-REFACTOR 这一基本循环。本 Skill 则把 TDD 改造为适用于文档编写。

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

什么是 Skill？

Skill 是针对成熟技术、模式或工具的参考指南。Skills 帮助未来的 Agent 找到并应用有效的方法。

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

Skills 不是： 关于你曾经如何解决某个问题的叙述

Skills 的 TDD 对应关系

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

整个 Skill 创建过程都遵循 RED-GREEN-REFACTOR。

何时创建 Skill

以下情况应创建：

• 该技术对你而言并非直观明显
• 你会在多个项目中反复参考
• 该模式具有广泛适用性（而非针对特定项目）
• 其他人也会从中受益

以下情况不应创建：

• 一次性的解决方案
• 已在别处有充分记载的标准实践
• 项目特定的约定（应写入你的指令文件）
• 机械性约束（如果可以用正则或校验强制执行，就应自动化，文档只用于需要判断的场景）

Skill 类型

技术

包含可遵循步骤的具体方法（如 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

扁平命名空间：所有 Skills 处于同一个可搜索的命名空间中

以下内容应放入单独文件：

1. 大型参考资料（100 行以上）：API 文档、完整语法说明
2. 可复用工具：脚本、实用程序、模板

以下内容应保留在正文中：

• 原则与概念
• 代码模式（少于 50 行）
• 其他所有内容

SKILL.md 结构

Frontmatter（YAML）：

• 两个必填字段：name 和 description（所有受支持字段请参见 agentskills.io/specification）
• 总长度不超过 1024 个字符
• name：仅使用字母、数字和连字符（不要使用括号或特殊字符）
• description：使用第三人称，仅描述何时使用（而不是它做什么）
  • 以 "Use when..." 开头，聚焦触发条件
  • 包含具体的症状、situation 和 context
  • 绝不要概括 skill 的流程或工作流（原因见 SDO 章节）
  • 尽量控制在 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

Skill 发现优化（SDO）

对发现至关重要： 未来的 Agent 需要找到你的 skill

1. 丰富的 description 字段

目的： Agent 通过阅读 description 来决定为某项任务加载哪些 skill。它应当回答："我现在应该阅读这个 skill 吗？"

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

关键：description 描述的是何时使用，而不是 skill 做什么

description 应当仅描述触发条件。不要在 description 中概括 skill 的流程或工作流。

为什么重要： 测试表明，当 description 概括了 skill 的工作流时，Agent 可能会按照 description 行事，而不去阅读完整的 skill 内容。例如，description 写着 "code review between tasks" 时，Agent 只做了一次审查，而 skill 的流程图清楚地显示应进行两次审查（先做规格合规性审查，再做代码质量审查）。

当 description 改为仅 "Use when executing implementation plans with independent tasks"（不含工作流概括）后，Agent 正确阅读了流程图，并遵循了两阶段审查流程。

陷阱： 概括工作流的 description 会形成一条 Agent 会走的捷径。skill 正文就会沦为 Agent 会跳过的文档。

# ❌ BAD: Summarizes workflow - agents 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

内容：

• 使用具体的触发条件、症状和情境，表明该 skill 适用
• 描述问题（竞态条件、行为不一致），而不是特定语言的症状（setTimeout、sleep）
• 除非 skill 本身与技术强相关，否则保持触发条件与技术无关
• 如果 skill 与特定技术相关，请在触发条件中明确说明
• 使用第三人称书写（会被注入 system prompt）
• 绝不概括 skill 的流程或工作流

# ❌ 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. 关键词覆盖

使用 Agent 会搜索的词语：

• 错误信息："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 类和经常被引用的 skill 会加载到每一次对话中。每个 token 都很重要。

目标字数：

• getting-started 工作流：每个少于 150 字
• 频繁加载的 skill：总计少于 200 字
• 其他 skill：少于 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]

消除冗余：

• 不要重复交叉引用的 skill 中已有的内容
• 不要解释命令本身已经说明清楚的内容
• 同一模式不要包含多个示例

验证：

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
• 主动，描述你正在执行的动作

5. 交叉引用其他 Skill

编写引用其他 Skill 的文档时：

只使用 Skill 名称，并明确标注要求级别：

• ✅ 正确：**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 将 Skill 的流程图渲染为 SVG：

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

代码示例

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

选择最相关的语言：

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

好的示例：

• 完整且可运行
• 注释充分，解释为什么（WHY）
• 来自真实场景
• 清晰展示模式
• 便于改造（而非通用模板）

避免：

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

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

文件组织

自包含的 Skill

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

适用场景：所有内容都能放下，无需大量参考资料

带可复用工具的 Skill

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

适用场景：工具是可复用的代码，而不只是叙述性内容

带大量参考资料的 Skill

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

适用场景：参考资料太大，无法内联

在正文中应通过解释器调用随附脚本（bash scripts/tool.sh、node scripts/tool.js），切勿直接使用裸路径：某些 harness 插件打包工具会去除可执行权限，此时裸路径形式的 scripts/tool.sh 会因 Permission denied 而失败。

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

这条规则同时适用于新建 Skill 和修改已有 Skill。

先写 Skill 后测试？删掉重来。 修改 Skill 却不测试？同样违规。

没有例外：

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

必读背景： superpowers:test-driven-development Skill 解释了其重要性。同样的原则也适用于文档。

测试所有 Skill 类型

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

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

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

测试方式：

• 理论问题：他们理解这些规则吗？
• 压力场景：他们在压力下是否仍然遵守？
• 多重压力叠加：时间 + 沉没成本 + 疲劳
• 识别自我合理化的借口，并添加明确的反驳条款

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

技术型 Skill（操作指南）

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

测试方式：

• 应用场景：他们能否正确应用该技术？
• 变体场景：他们能否处理边界情况？
• 信息缺失测试：说明中是否存在空白？

成功标准： Agent 能将该技术成功应用到新场景中

模式类技能（心智模型）

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

测试方式：

• 识别场景：它们能否识别何时适用该模式？
• 应用场景：它们能否运用该心智模型？
• 反例场景：它们是否知道何时不应套用？

成功标准： Agent 能正确识别何时以及如何应用该模式

参考类技能（文档/API）

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

测试方式：

• 检索场景：它们能否找到正确的信息？
• 应用场景：它们能否正确使用所找到的信息？
• 缺口测试：常见用例是否被覆盖？

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

跳过测试的常见借口

借口	现实
“技能显然很清楚”	对你清楚，不等于对其他 Agent 清楚。去测试。
“它只是参考资料”	参考资料也可能有缺口、表述不清的部分。测试检索能力。
“测试太小题大做”	未经测试的技能必然有问题。永远如此。15 分钟测试能省下数小时。
“等出问题再测”	出问题意味着 Agent 无法使用该技能。部署前就要测试。
“测试太繁琐”	测试比在生产环境中调试有问题的技能省心得多。
“我很有把握它没问题”	过度自信必然导致问题。仍然要测试。
“学术审阅就够了”	阅读不等于使用。要测试应用场景。
“没有时间测试”	部署未经测试的技能，之后修复只会耗费更多时间。

以上所有借口的含义都是：部署前必须测试。没有例外。

让形式匹配失败类型

在编写指导内容之前，先对基线失败进行分类。能够加固某一类失败的形式，在另一类失败上可能会明显适得其反。

基线失败	正确形式	错误形式
在压力下跳过或违反规则（明知故犯）	禁令 + 借口对照表 + 危险信号（见下文“加固”）	软性建议（“最好……”“可以考虑……”）
能够遵从，但输出结构有误（提示词臃肿、结论被埋没、重复复述规范）	正面的配方或契约：说明输出应当包含什么，包括各部分及其顺序	禁止清单（“不要复述”“从不叙述过程”）
在已经产出的内容中遗漏了必需要素	结构化：在待填写的模板中设置必填字段或槽位	模板附近的文字提醒
行为应取决于某个条件	以可观察的谓词为条件（“如果存在 brief，则引用它”）	无条件规则 + 例外条款

为什么禁令在塑造类问题上会适得其反： 当存在相互竞争的激励（例如“让提示词自成一体”）时，Agent 会与“不要做 X”这类表述进行博弈。在有关派发提示词指导的正面对比测试中，禁令组产生的不良内容明显多于配方组（两者分布完全分离），甚至略差于无指导的对照组。请针对自己的场景进行小规模测试，不要想当然，但也绝不要默认使用禁令。配方不留博弈空间：输出要么符合规定的形式，要么不符合。

无论选择哪种形式，都需遵守以下规则：

• 不加细节限定条款。 “除非确有必要，否则不要做 X”会重新引发博弈。在经过验证的有效配方上仅追加一条细节限定条款，就会在同样的对比测试中使其从稳定变为嘈杂。若要表达真正的例外，应将其写成以可观察谓词为条件的独立规则。
• 豁免条款无法限定范围。 “此限制不适用于代码块”仍会抑制代码块。若输出中某部分必须豁免，应调整结构，使规则无法触及该部分。

让 Skills 抵御合理化借口

用于强制执行纪律的 Skills（例如 TDD）必须能够抵御合理化借口。Agent 足够聪明，在压力下会找到规则的漏洞。

适用范围： 本工具箱针对的是纪律性失败，即 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>

### 应对"精神与字面"之争

在前面尽早加入基础原则：

```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.**

为违规征兆更新 SDO

在描述中加入"即将违规时"的征兆：

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

Skills 的 RED-GREEN-REFACTOR

遵循 TDD 循环：

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

在不使用该 Skill 的情况下，用子 Agent 运行压力场景，并记录确切行为：

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

这就是"看着测试失败"：在编写 Skill 之前，你必须先看到 Agent 自然会怎么做。

GREEN：编写最小化的 Skill

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

在使用该 Skill 的情况下运行相同场景。此时 Agent 应当遵守规则。

REFACTOR：堵住漏洞

Agent 找到了新的合理化借口？添加明确的反制内容。重新测试，直到足够稳固。

在完整场景前先对措辞做微测试

完整的压力场景运行是最终的检验关卡，但每次迭代都既慢又昂贵。应先用微测试验证措辞本身：

1. 每次调用使用一个全新上下文的样本：可以是原始 API 调用，若无 API 访问权限，则使用单次子 Agent。系统提示词 = 指导将来所处的真实上下文（完整的 Skill 或提示词模板，而不是孤立的指导内容）；用户消息 = 一个会诱发该失败的任务。
2. 始终包含无指导的对照组。 如果对照组没有出现该失败，就无需修复，停止即可，不要编写指导内容。
3. 每个变体至少 5 次重复。 单个样本不可靠。
4. 人工阅读每一个被标记的匹配项。 可以用程序打分，但模板回显和引用的反例会伪装成命中；仅靠自动计数会高估失败和成功的程度。
5. 将方差作为指标。 当指导生效时，各次重复会收敛到相同的形态。五次重复出现五种不同的解读，说明措辞还不具约束力，应先收紧形式，再考虑增加文字。

微测试用于验证措辞；对于纪律性 Skill，它们不能取代压力场景测试。

测试方法： 完整的测试方法请参阅 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）

重要：为下方检查清单中的每一项创建一个待办事项。

RED 阶段：编写失败的测试

• 创建压力场景（对纪律类技能，组合至少 3 种压力）
• 在没有技能的情况下运行场景，逐字记录基线行为
• 找出合理化借口和失败情况中的模式

GREEN 阶段：编写最小化技能

• 名称仅使用字母、数字和连字符（不含括号或其他特殊字符）
• YAML frontmatter 包含必填的 name 和 description 字段（最多 1024 个字符；参见 规范）
• 描述以 "Use when..." 开头，并包含具体的触发条件或症状
• 描述使用第三人称撰写
• 全文使用便于搜索的关键词（错误、症状、工具）
• 提供清晰的概述和核心原则
• 针对 RED 阶段发现的具体基线失败进行处理
• 指导形式与失败类型相匹配（参见“根据失败类型匹配形式”）
• 对于行为塑造类指导：已针对无指导的对照组对措辞进行小规模测试（至少 5 次重复，逐一人工阅读每个被标记的匹配项）；纯参考类技能不适用
• 代码内联，或链接到单独的文件
• 提供一个优秀的示例（不要多语言版本）
• 在有技能的情况下运行场景，验证 Agent 现在能够遵守规范

REFACTOR 阶段：堵住漏洞

• 从测试中找出新的合理化借口
• 为纪律类技能添加明确的反制措施
• 根据所有测试迭代建立合理化借口对照表
• 创建危险信号列表
• 重新测试，直至足够稳固

质量检查：

• 仅当决策不明显时才使用小型流程图
• 快速参考表
• 常见错误章节
• 不使用叙事性的故事写法
• 仅为工具或大量参考资料提供辅助文件

部署：

• 将技能提交到 git 并推送到你的 fork（如已配置）
• 如果内容具有广泛价值，考虑通过 PR 回馈贡献

发现流程

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

1. 遇到问题（“测试不稳定”）
2. 搜索技能（检索描述、浏览分类）
3. 找到技能（描述匹配）
4. 浏览概述（是否相关？）
5. 阅读模式（快速参考表）
6. 加载示例（仅在实施时）

围绕此流程进行优化：尽早且多次放置可搜索的术语。