writing-skills

编写技能

概述

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

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

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

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

必备背景知识： 使用本技能前，你必须理解 superpowers-ruby:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 周期。本技能将 TDD 应用于文档。

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

什么是技能？

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

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

技能不包括： 叙述你曾经如何解决某个问题

技能的 TDD 映射

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

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

何时创建技能

适合创建的情况：

• 你未能直观地掌握某项技术
• 你会在多个项目中再次参考它
• 这种模式适用范围广（而非仅针对某个项目）
• 其他人也能从中受益

不适合创建的情况：

• 一次性解决方案
• 其他地方已有完善文档的标准实践
• 项目专属约定（放入 CLAUDE.md）
• 机械性约束（如果能用正则表达式或验证机制强制执行，就将其自动化——文档留给需要判断的事项）

技能类型

技术

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

前置元数据（YAML）：

字段	必填	限制
name	是	最多 64 个字符。只能包含小写字母、数字和连字符。不能以连字符开头或结尾，也不能包含连续连字符。必须与父目录名称一致。
description	是	最多 1024 个字符。有关如何编写有效描述，请参见 CSO 部分。
license	否	许可证名称或对随附许可证文件的引用。
compatibility	否	最多 500 个字符。环境要求（目标产品、系统软件包、网络访问权限）。
metadata	否	任意键值映射（字符串键对应字符串值）。
allowed-tools	否	以空格分隔的预先批准工具列表。实验性功能——支持情况可能有所不同。

description 编写指南：

• 使用第三人称，只描述何时使用（而非它的功能）
• 以 “Use when...” 开头，聚焦触发条件
• 包含具体症状、情形和上下文
• 绝不要概述技能的流程或工作流（原因见 CSO 部分）
• 尽可能控制在 500 个字符以内

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
# Optional:
# license: MIT
# compatibility: Requires network access
# metadata:
#   author: your-name
# allowed-tools: Bash(git:*) Read
---

# 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

Claude 搜索优化（CSO）

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

1. 丰富的描述字段

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

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

关键：描述说明何时使用，而非技能的功能

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

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

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

陷阱： 概述工作流的描述会形成一条 Claude 可能采用的捷径。技能正文就会沦为 Claude 跳过不读的文档。

# ❌ BAD: Summarizes workflow - Claude 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. 关键词覆盖

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

**问题：**入门和频繁引用的技能会加载到每次对话中。每个 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
• 表达主动行为，描述你正在执行的操作

4. 交叉引用其他技能

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

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

• ✅ 好：**REQUIRED SUB-SKILL:** 使用 superpowers-ruby:test-driven-development
• ✅ 好：**REQUIRED BACKGROUND:** 你必须了解 superpowers-ruby: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 将技能的流程图渲染为 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

这适用于新建技能，也适用于编辑现有技能。

先编写技能再测试？删除它，从头开始。 编辑技能却不测试？同样违规。

没有例外：

• 不是“简单添加”也不行
• 不是“只是添加一个章节”也不行
• 不是“文档更新”也不行
• 不要把未经测试的更改作为“参考”保留
• 运行测试时不要“顺便改编”
• 删除就是删除

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

测试所有技能类型

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

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

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

测试方式：

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

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

技术型技能（操作指南）

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

测试方式：

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

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

模式型技能（思维模型）

示例： reducing-complexity、information-hiding concepts

测试方式：

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

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

参考型技能（文档/API）

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

测试方式：

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

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

不测试的常见合理化说辞

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

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

让技能坚决抵御合理化说辞

强制遵守纪律的技能（如 TDD）需要能够抵御合理化说辞。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.**

更新 CSO，纳入违规征兆

在描述中添加规则即将被违反时的征兆：

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

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 周期：

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

在不提供该技能的情况下，让子 Agent 执行压力场景。记录其确切表现：

• 他们做出了哪些选择？
• 他们用了哪些合理化说辞（逐字记录）？
• 哪些压力导致了违规？

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

GREEN：编写最精简的技能

编写能够解决这些特定合理化说辞的技能。不要添加针对假设情形的额外内容。

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

REFACTOR：堵住漏洞

Agent 是否找到了新的合理化说辞？添加明确的反驳。反复测试，直到无懈可击。

**测试方法：**完整测试方法请参阅 @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 为以下每项清单事项创建待办任务。

RED 阶段——编写失败测试：

• 创建压力场景（纪律类技能需包含 3 种以上组合压力）
• 在不使用技能的情况下运行场景——逐字记录基线行为
• 找出合理化说辞／失败中的模式

GREEN 阶段——编写最精简的技能：

• 名称仅使用字母、数字和连字符（不含括号／特殊字符）
• YAML 前置内容：必需的 name（最多 64 个字符，小写并使用连字符）和 description（最多 1024 个字符）
• 视情况添加可选前置字段：license、compatibility、metadata、allowed-tools
• 描述以“Use when...”开头，并包含具体触发条件／症状
• 描述使用第三人称
• 全文包含便于搜索的关键词（错误、症状、工具）
• 提供包含核心原则的清晰概览
• 解决 RED 阶段发现的具体基线失败
• 将代码内联，或链接到单独的文件
• 提供一个优秀示例（不要使用多种语言）
• 使用该技能运行场景——确认 Agent 现在会遵守要求

REFACTOR 阶段——堵住漏洞：

• 找出测试中出现的新合理化说辞
• 添加明确的反驳（如果是纪律类技能）
• 根据所有测试迭代创建合理化说辞表
• 创建警示信号列表
• 反复测试，直到无懈可击

质量检查：

• 仅在决策不明显时使用小型流程图
• 提供速查表
• 提供常见错误部分
• 不讲述故事
• 仅在涉及工具或内容庞大时使用辅助文件

部署：

• 将技能提交到 git，并推送到你的 fork（如果已配置）
• 考虑通过 PR 贡献回项目（如果对更多人有用）

发现工作流

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

1. 遇到问题（“测试不稳定”）
2. 找到 SKILL（描述与问题匹配）
3. 浏览概览（这是否相关？）
4. 阅读模式（速查表）
5. 查看示例（仅在实施时）

针对这一流程进行优化——尽早并频繁地放置便于搜索的词语。

核心要点

创建技能就是对流程文档进行 TDD。

同一条铁律：没有先失败的测试，就不创建技能。 同一循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。 同样的益处：质量更高、意外更少、结果无懈可击。

如果你对代码采用 TDD，也应对技能采用 TDD。这是将同一套纪律应用于文档。