writing-skills

编写技能

概述

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

个人技能存放在运行时已安装的技能目录中。Codex、Copilot CLI 和 Gemini CLI 都将 ~/.agents/skills/ 识别为跨运行时别名。

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

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

必备背景知识： 使用本技能前，必须理解 test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。本技能将 TDD 应用于文档编写。

官方指南： Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了其他模式和指南，与本技能侧重 TDD 的方法相辅相成。

什么是技能？

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

技能包括： 可复用的技巧、模式、工具和参考指南

技能不包括： 讲述你曾经如何解决某个问题的故事

技能的 TDD 映射

TDD 概念	技能创建
测试用例	使用子 Agent 构造的压力场景
生产代码	技能文档（SKILL.md）
测试失败（RED）	Agent 在没有技能时违反规则（基线）
测试通过（GREEN）	Agent 在提供技能时遵循要求
重构	在保持遵循要求的同时堵住漏洞
先写测试	编写技能之前运行基线场景
观察失败	记录 Agent 使用的确切辩解
最少代码	编写针对这些具体违规行为的技能
观察通过	验证 Agent 现在是否遵循要求
重构循环	找出新的辩解 → 堵住漏洞 → 重新验证

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

何时创建技能

适合创建的情况：

• 你觉得某项技巧并非直观易懂
• 你会在不同项目中再次参考它
• 该模式适用范围广（并非特定于某个项目）
• 其他人也能从中受益

不适合创建的情况：

• 一次性解决方案
• 其他地方已有完善文档的标准做法
• 特定于项目的约定（放入项目说明文件）
• 机械性约束（如果可以通过正则表达式或验证来强制执行，就自动化处理；将文档留给需要判断的事项）

技能类型

技巧

包含具体步骤的方法（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 结构

Frontmatter（YAML）：

• 两个必填字段：name 和 description（所有受支持字段请参阅 agentskills.io/specification）
• 总字符数最多为 1024
• name：仅使用字母、数字和连字符（不得使用括号或特殊字符）
• description：使用第三人称，仅说明何时使用（而非说明它的作用）
  • 以 “Use when...” 开头，聚焦于触发条件
  • 包含具体症状、情境和上下文
  • 绝不要概述技能的流程或工作流（原因见 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

技能发现优化（SDO）

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

1. 丰富的描述字段

目的： Agent 会阅读描述，以决定针对给定任务加载哪些技能。描述应回答：“我现在应该阅读这项技能吗？”

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

关键：描述 = 何时使用，而非技能的作用

描述应仅说明触发条件。不要在描述中概述技能的流程或工作流。

为何重要： 测试发现，如果描述概述了技能的工作流，Agent 可能会遵循描述，而不是阅读完整的技能内容。描述中写着“在任务之间进行代码审查”，会导致 Agent 只进行一次审查，尽管技能的流程图明确展示了两次审查（先检查规范符合性，再检查代码质量）。

当描述改为仅写“在执行包含独立任务的实施计划时使用”（不概述工作流）后，Agent 正确阅读了流程图，并遵循了两阶段审查流程。

陷阱： 概述工作流的描述会造成 Agent 会走的捷径。技能正文就成了 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

内容：

• 使用具体的触发条件、症状和情境，表明适用此技能
• 描述问题（竞态条件、行为不一致），而非特定语言的症状（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. 关键词覆盖

使用 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（关键）

问题： 入门指南和频繁引用的技能会加载到每次对话中。每个 Token 都很重要。

目标字数：

• 入门工作流：每项少于 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
• 主动表达你正在采取的行动

5. 交叉引用其他技能

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

仅使用技能名称，并明确标注要求：

• ✅ 好：**REQUIRED SUB-SKILL:** 使用 test-driven-development`
• ✅ 好：**REQUIRED BACKGROUND:** 你必须了解 systematic-debugging`
• ❌ 不好：参见 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

好的示例应当：

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

不要：

• 用 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

这适用于新技能，也适用于对现有技能的修改。

先编写技能再测试？删除它，重新开始。 修改技能却不测试？同样违反规定。

没有例外：

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

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

测试所有技能类型

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

强制执行规范的技能（规则/要求）

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

测试方法：

• 理论问题：他们理解这些规则吗？
• 压力场景：他们在压力下会遵守吗？
• 多重压力叠加：时间 + 沉没成本 + 精疲力尽
• 找出合理化借口，并添加明确的反制措施

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

技术技能（操作指南）

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

测试方法：

• 应用场景：他们能正确应用这项技术吗？
• 变化场景：他们能处理边缘情况吗？
• 信息缺失测试：说明中存在缺漏吗？

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

模式技能（思维模型）

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

测试方法：

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

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

参考技能（文档/API）

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

测试方法：

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

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

常见的跳过测试的借口

借口	现实
“Skill 显然很清楚”	对你来说清楚 ≠ 对其他 Agent 来说清楚。测试一下。
“这只是参考资料”	参考资料可能存在缺漏或含糊不清的部分。测试检索效果。
“测试太小题大做了”	未经测试的 Skill 总会有问题。每次都如此。花 15 分钟测试，可以省下数小时。
“如果出现问题，我再测试”	出现问题意味着 Agent 无法使用 Skill。部署前就要测试。
“测试太麻烦了”	测试比在生产环境中调试糟糕的 Skill 省事。
“我确信它没问题”	过度自信必然导致问题。无论如何都要测试。
“学术审查就够了”	阅读 ≠ 使用。测试实际应用场景。
“没时间测试”	部署未经测试的 Skill，之后修复会浪费更多时间。

这些借口的意思都一样：部署前先测试。没有例外。

根据失败类型选择形式

编写指导前，先对基线失败进行分类。能有效防范某类失败的形式，用在另一类失败上却可能适得其反。

基线失败	合适的形式	不合适的形式
压力之下跳过或违反规则（明明知道不该这么做，却还是做了）	禁止事项 + 借口对照表 + 危险信号（见下文“让 Skill 无懈可击”）	柔性指导（“最好……”“考虑……”）
遵守了要求，但输出形式不对（提示词臃肿、结论埋得太深、重复陈述规范）	正向范例或契约：说明输出应当是什么——包含哪些部分、顺序如何	禁止事项列表（“不要重复陈述”“绝不要叙述”）
漏掉已在产出内容中要求的要素	结构化要求：在要填写的模板中设定必填字段或占位项	在模板附近用散文式文字提醒
行为应根据条件而变化	以可观察的谓词为条件（“如果简报存在，就引用它”）	无条件规则 + 豁免条款

**为什么禁止事项会适得其反，导致输出形式问题：**面对相互竞争的激励（“让提示词自成一体”）时，Agent 会与“不要做 X”讨价还价。在针对调度提示词指导的措辞对照测试中，禁止事项组产生的不良内容明显多于范例组（两组分布完全分离），而且趋势上甚至不如没有指导的对照组——请针对自己的情况进行小规模测试，不要想当然；但也不要默认采用禁止事项。范例不给讨价还价留余地：输出要么符合规定的形式，要么不符合。

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

• 不要添加细微差别条款。“除非 X 很重要，否则不要做 X”会重新开启讨价还价；在相同的措辞测试中，给效果最佳的范例附加一条细微差别条款，会让效果从稳定一致变得参差不齐。应将真正的例外单独表述为基于可观察谓词的条件。
• 豁免条款无法限定适用范围。“此限制不适用于代码块”仍会抑制代码块。如果输出中的某部分必须豁免，就调整结构，避免规则覆盖到它。

让 Skill 能抵御借口

强制执行纪律的 Skill（例如 TDD）需要能够抵御找借口。Agent 很聪明，遇到压力时会寻找漏洞。

**适用范围：**此工具包适用于纪律问题——Agent 知道规则，却在压力下跳过规则。对于输出形式错误或遗漏要素的情况，基于禁止事项的防范方法会适得其反；请改用“根据失败类型选择形式”中的方法。

**心理学提示：**了解说服技巧为何有效，有助于系统地运用这些技巧。有关权威、承诺、稀缺、社会认同和统一性原则的研究基础，请参阅 persuasion-principles.md（Cialdini，2021；Meincke 等人，2025）。

明确封堵每个漏洞

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

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

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 周期：

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

在不使用该技能的情况下，让子 Agent 执行压力场景。记录其确切行为：

• 它做出了哪些选择？
• 它用了哪些合理化理由（原话）？
• 哪些压力引发了违规？

这就是“观察测试失败”——编写技能之前，必须先了解 Agent 自然会怎么做。

GREEN：编写最精简的技能

编写技能，针对这些具体的合理化理由进行处理。不要添加针对假设情况的额外内容。

使用该技能运行相同场景。Agent 此时应该遵守规则。

REFACTOR：堵住漏洞

Agent 找到了新的合理化理由？添加明确的反制措施。重新测试，直到无懈可击。

在完整场景测试前，对措辞进行微测试

完整的压力场景测试是最终关卡，但每次迭代都运行这类测试既耗时又昂贵。先通过微测试验证措辞本身：

1. 每次调用使用一个全新上下文样本——使用原始 API 调用；如果没有 API 访问权限，则使用单次子 Agent。系统提示词 = 指南所处的真实上下文（完整技能或提示词模板，而不是单独的指南）；用户消息 = 一个容易诱发失败的任务。
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 改编版）

重要：为以下每一项检查清单内容创建一个待办事项。

RED 阶段 - 编写失败测试：

• 创建压力场景（针对纪律类技能，组合 3 种或更多压力）
• 不使用技能运行场景 - 原样记录基线行为
• 找出合理化说辞／失败模式

GREEN 阶段 - 编写最小技能：

• 名称仅使用字母、数字和连字符（不含括号／特殊字符）
• YAML frontmatter 包含必需的 name 和 description 字段（最多 1024 个字符；参见 规范）
• 描述以 "Use when..." 开头，并包含具体触发条件／症状
• 描述使用第三人称
• 全文包含便于搜索的关键词（错误、症状、工具）
• 提供包含核心原则的清晰概述
• 针对 RED 阶段发现的具体基线失败提供解决方法
• 指导形式与失败类型匹配（参见“让形式与失败相匹配”）
• 对于塑造行为的指导：针对无指导对照组进行措辞微测试（至少 5 次；人工阅读每条标记的匹配项）——纯参考类技能不适用
• 内联代码，或链接到单独的文件
• 提供一个出色的示例（不要使用多种语言）
• 使用技能运行场景 - 确认 Agent 现在会遵循要求

REFACTOR 阶段 - 弥补漏洞：

• 找出测试中出现的新的合理化说辞
• 添加明确的反制措施（如果是纪律类技能）
• 根据所有测试迭代结果构建合理化说辞表
• 创建危险信号清单
• 反复测试，直到无懈可击

质量检查：

• 仅在决策不明显时使用简短流程图
• 提供快速参考表
• 提供常见错误章节
• 不讲述故事
• 仅在需要工具或大量参考资料时添加辅助文件

部署：

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

发现工作流

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

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

针对这一流程进行优化 - 尽早且频繁地使用便于搜索的术语。