writing-skills

编写技能

概述

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

个人技能位于运行时的技能目录中（Claude Code 中为 ~/.claude/skills/）——有关这些运行时的路径，请参阅 codex-tools.md 或 gemini-tools.md。Codex、Copilot CLI 和 Gemini CLI 也都将 ~/.agents/skills/ 识别为跨运行时别名。

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

**核心原则：**如果你没亲眼看到 Agent 在没有技能时失败，就不知道这项技能教得对不对。

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

**官方指南：**有关 Anthropic 官方的技能编写最佳实践，请参阅 references/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

技能的 description 只说明何时使用：触发条件和症状，并以“Use when...”开头。它绝不概述技能的工作流，因为 Agent 读到工作流概要后会直接照着执行，而不是阅读技能。

编写或更改技能的 frontmatter、名称或描述，或需要精简技能内容时，请阅读 references/discovery.md：其中包含 SKILL.md 模板、描述和关键词指南、命名规范、Token 预算，以及交叉引用其他技能的说明。

流程图

在技能中添加或更改流程图时，请先阅读 references/flowcharts.md：了解流程图何时值得添加、Graphviz 约定，以及如何渲染流程图。

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 → 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

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

在正文中通过解释器调用随附脚本（bash scripts/tool.sh、node scripts/tool.js），不要直接使用裸路径：有些 harness 插件打包器会移除可执行权限，裸路径 scripts/tool.sh 在那里会因 Permission denied 而失败。

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

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

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

没有例外：

• “简单补充”也不例外
• “只添加一个章节”也不例外
• “文档更新”也不例外
• 不要把未经测试的改动留作“参考”
• 不要在运行测试时“顺便调整”
• 删除就是删除

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

测试所有技能类型

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

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

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

测试方式：

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

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

技术型技能（操作指南）

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

测试方式：

• 应用场景：他们能否正确运用该技术？
• 变化场景：他们能否处理边缘情况？
• 信息缺失测试：说明是否存在遗漏？

成功标准： Agent 能在新场景中成功运用该技术

模式型技能（思维模型）

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

测试方式：

• 识别场景：他们能否识别适用该模式的情况？
• 应用场景：他们能否使用该思维模型？
• 反例：他们是否知道何时不该使用？

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

参考型技能（文档/API）

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

测试方式：

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

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

跳过测试的常见借口

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

这些借口都说明一件事：部署前先测试。没有例外。

根据失败类型选择合适的形式

编写指导内容之前，先对基线失败进行分类。能有效防止某一种失败的形式，用在另一种失败上时，可能会明显适得其反。

基线失败	合适的形式	不合适的形式
在压力下跳过或违反规则（知道应该怎么做，却还是照做）	禁止事项 + 借口表 + 警示信号（参见 references/bulletproofing.md）	委婉建议（“最好……”“可以考虑……”）
遵守了要求，但输出形式不正确（提示词臃肿、结论埋得太深、重复陈述规范）	正向范例或约定：说明输出应当是什么——包含哪些部分、顺序如何	禁止事项列表（“不要重复陈述”“不要叙述过程”）
在已有输出中遗漏必需元素	结构化要求：在待填写的模板中设置必填字段或占位项	在模板附近用文字提醒
行为应取决于某个条件	以可观察谓词为依据的条件规则（“如果存在 brief，就引用它”）	无条件规则 + 豁免条款

**为什么禁止事项会适得其反：**当存在相互竞争的动机（“让提示词自成一体”）时，Agent 会对“不要做 X”讨价还价。在针对调度提示词指导内容进行的措辞对照测试中，禁止事项组生成的不需要内容明显多于范例组（两组结果分布完全分离），甚至比无指导对照组的表现还差。请针对自己的案例进行微型测试，不要想当然；但也绝不要默认采用禁止事项。范例不给讨价还价留下余地：输出要么符合规定的形式，要么不符合。

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

• 不要添加细微差别条款。“除非 X 很重要，否则不要做 X”会重新开启讨价还价——在相同的措辞测试中，给效果出色的范例追加一个细微差别条款，就会使结果从稳定变得不稳定。确实存在例外时，应将其单独表述为以可观察谓词为依据的条件。
• 豁免条款无法限定规则范围。“此限制不适用于代码块”仍会抑制代码块。如果输出的某一部分必须豁免，就应重新组织结构，使规则无法作用于该部分。

防范借口

如果基线失败属于纪律问题，请在编写指导内容之前阅读 references/bulletproofing.md：了解如何堵住漏洞、把握精神与字面规定的界限、编写借口表和警示信号清单。

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 循环：

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

在不使用该技能的情况下，运行压力场景并使用子 Agent。记录具体行为：

• 它们做出了哪些选择？
• 它们使用了哪些借口（原话）？
• 哪些压力触发了违规行为？

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

GREEN：编写最小化技能

编写技能，解决这些具体借口。不要为假设情形添加额外内容。

使用该技能运行相同的场景。Agent 此时应当遵守要求。

REFACTOR：堵住漏洞

Agent 找到了新的借口？添加明确的反驳。重新测试，直到无懈可击。

完整场景测试前的微型测试措辞

完整压力场景测试是最后一道关卡，但每轮测试都耗时且成本高。先通过微型测试验证措辞本身：

1. 每次调用都使用一个全新上下文样本——原始 API 调用，或者在无法访问 API 时使用单次运行的子 Agent。系统提示词 = 指南将要应用的真实上下文（完整技能或提示词模板，而非孤立的指南）；用户消息 = 一个容易诱发该失败的任务。
2. 始终加入无指南对照组。 如果对照组没有出现该失败，就没有需要修复的问题——停止，不要编写指南。
3. 每个变体至少测试 5 次。 单个样本会误导。
4. 手动阅读每条标记匹配项。 可以用程序评分，但模板复述和引用的反例可能被误判为命中；仅靠自动计数会夸大失败率和成功率。
5. 差异性也是衡量指标。 指南生效时，多次测试会收敛到相同的表现形式。5 次测试出现 5 种不同解读，说明措辞约束力不足——先收紧表述形式，再添加更多文字。

微型测试用于验证措辞；它们不能替代对纪律类技能进行的压力场景测试。

测试方法： 完整测试方法见 references/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. 加载示例（仅在实施时）

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