---

name: writing-skills description: 使用于创建新技能、编辑现有技能或在部署前验证技能工作

编写技能

概览

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

个人技能存放在特定代理的目录中（Claude Code 的 ~/.claude/skills，Codex 的 ~/.codex/skills）

你编写测试用例（带有子代理的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（代理遵从），并重构（修补漏洞）。

**核心原则：**如果你没有看到代理在没有技能的情况下失败，你就不知道技能是否教会了正确的东西。

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

**官方指导：**有关 Anthropic 的官方技能编写最佳实践，请参阅 anthropic-best-practices.md。此文档提供了补充 TDD 重点方法的额外模式和指南。

技能是什么？

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

**技能是：**可重用的技术、模式、工具、参考指南 **技能不是：**关于你如何一次性解决问题的叙述

技能的 TDD 映射

TDD 概念	技能创建
测试用例	带有子代理的压力场景
生产代码	技能文档（SKILL.md）
测试失败（RED）	代理在没有技能的情况下违反规则（基线）
测试通过（GREEN）	代理在技能存在时遵从
重构	在保持遵从的同时关闭漏洞
先写测试	在编写技能之前运行基线场景
观察它失败	文档记录代理使用的确切合理化
最小代码	编写技能解决这些特定的违规
观察它通过	验证代理现在遵从
重构循环	找到新的合理化 → 修补 → 重新验证

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

何时创建技能

创建时：

• 技术对你来说并不直观明显
• 你会在多个项目中参考此内容
• 模式广泛适用（不是项目特定的）
• 其他人会受益

不要为以下创建：

• 一次性解决方案
• 其他地方已有良好文档的标准实践
• 项目特定的约定（放在 CLAUDE.md 中）

技能类型

技术

具体的方法，带有遵循的步骤（基于条件的等待，根本原因追踪）

模式

思考问题的方式（用旗帜扁平化，测试不变量）

参考

API 文档，语法指南，工具文档（办公文档）

目录结构

skills/
  skill-name/
    SKILL.md              # 主要参考（必需）
    supporting-file.*     # 如有需要

扁平命名空间 - 所有技能都在一个可搜索的命名空间中 单独文件用于：

1. 重参考（100+ 行） - API 文档，全面的语法
2. 可重用工具 - 脚本，实用程序，模板

保持内联：

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

SKILL.md 结构

前言（YAML）：

• 仅支持两个字段：name 和 description
• 总共最多 1024 个字符
• name：仅使用字母、数字和连字符（无括号，特殊字符）
• description：第三人称，仅描述何时使用（而不是它做什么）
  • 以 “Use when…” 开始，专注于触发条件
  • 包括特定症状、情况和上下文
  • 永远不要总结技能的过程或工作流程（见 CSO 部分原因）
  • 如可能，保持在 500 个字符以内

---
name: Skill-Name-With-Hyphens
description: 使用于[特定触发条件和症状]
---

# 技能名称

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

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

带有症状和用例的子弹列表
何时不使用

## 核心模式（对于技术和模式）
前后代码比较

## 快速参考
用于扫描常见操作的表格或子弹

## 实施
内联代码用于简单模式
链接到文件用于重参考或可重用工具

## 常见错误
出了什么问题 + 修复

## 现实世界影响（可选）
具体结果

Claude 搜索优化（CSO）

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

1. 丰富的描述字段

目的： Claude 读取描述以决定为给定任务加载哪些技能。使其回答：“我现在应该阅读这个技能吗？”

**格式：**以 “Use when…” 开始，专注于触发条件

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

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

**为什么这很重要：**测试表明，当描述总结技能的工作流程时，Claude 可能会按照描述而不是阅读完整的技能内容。描述说 “code review between tasks” 导致 Claude 只进行了一次审查，尽管技能的流程图清楚地显示了两个审查（规范合规然后代码质量）。

当描述更改为仅 “Use when executing implementation plans with independent tasks”（无工作流程总结）时，Claude 正确地阅读了流程图并遵循了两阶段审查过程。

**陷阱：**总结工作流程的描述为 Claude 创建了捷径。技能主体成为 Claude 跳过的文档。

# ❌ BAD: 总结工作流程 - Claude 可能会按照这个而不是阅读技能
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: 过多的流程细节
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: 仅触发条件，无工作流程总结
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: 仅触发条件
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• 使用 Claude 会搜索的具体触发器、症状和情况：
• 描述 问题（竞态条件，不一致的行为）而不是 语言特定的症状（setTimeout，sleep）
• 保持触发器与技术无关，除非技能本身与技术特定
• 如果技能与技术特定，那么在触发器中明确这一点
• 以第三人称写（注入到系统提示中）
• 永远不要总结技能的过程或工作流程

# ❌ BAD: 太抽象，模糊，不包括何时使用
description: For async testing

# ❌ BAD: 第一人称
description: I can help you with async tests when they're flaky

# ❌ BAD: 提到了技术但技能不是特定于它的
description: Use when tests use setTimeout/sleep and are flaky

# ✅ GOOD: 以 "Use when" 开始，描述问题，无工作流程
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: 特定于技术的技能，明确的触发器
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. 令牌效率（关键）

**问题：**入门和经常引用的技能加载到每一次对话中。每个令牌都很重要。

目标字数：

• 入门工作流程：每个 <150 字
• 经常加载的技能：总共 <200 字
• 其他技能：<500 字（仍然要简洁）

技术： 将细节移动到工具帮助中：

# ❌ BAD: 在 SKILL.md 中记录所有标志
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: 参考 --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# ❌ BAD: 重复工作流程细节
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: 引用其他技能
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

压缩示例：

# ❌ BAD: 冗长的示例（42 字）
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: 最小示例（20 字）
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

消除冗余：

• 不要在交叉引用的技能中重复
• 不要解释从命令中显而易见的内容
• 不要包含同一模式的多个示例

验证：

wc -w skills/path/SKILL.md
# 入门工作流程：目标 <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
• 活跃的，描述你正在采取的行动

4. 交叉引用其他技能

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

使用技能名称，带有明确的要求标记：

• ✅ 好：**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 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

好的示例：

• 完整且可运行
• 有解释 WHY 的良好注释
• 来自真实场景
• 清晰显示模式
• 准备适应（不是通用模板）

不要：

• 在 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 相同）

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

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

在测试之前编写技能？删除它。重新开始。 在测试时编辑技能？同样的违规。

没有例外：

• 不是 “简单的添加”
• 不是 “只是添加一个部分”
• 不是 “文档更新”
• 不要将未经测试的更改保留为 “参考”
• 不要在运行测试时 “适应”
• 删除意味着删除

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

测试所有技能类型

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

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

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

测试与：

• 学术问题：他们是否理解规则？
• 压力场景：他们在压力下是否遵从？
• 组合多重压力：时间 + 沉没成本 + 疲劳
• 识别合理化并添加明确的对策

**成功标准：**代理在最大压力下遵循规则

技术技能（操作指南）

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

测试与：

• 应用场景：他们是否正确应用技术？
• 变体场景：他们是否处理边缘情况？
• 缺少信息测试：指示有空白吗？

**成功标准：**代理成功地将技术应用于新场景

模式技能（心智模型）

示例： reducing-complexity，information-hiding concepts

测试与：

• 识别场景：他们是否认出何时模式适用？
• 应用场景：他们可以使用心智模型吗？
• 反例：他们知道何时不适用吗？

**成功标准：**代理正确识别何时/如何应用模式

参考技能（文档/APIs）

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

测试与：

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

**成功标准：**代理找到并正确应用参考信息

跳过测试的常见合理化

借口	现实
“技能显然很清楚”	清楚给你 ≠ 清楚给其他代理。测试它。
“这只是参考”	参考可能有空白，不清楚的部分。测试检索。
“测试是过度的”	未经测试的技能总是有问题。总是。15 分钟的测试节省了几个小时。
“如果有问题我会测试”	问题 = 代理不能使用技能。测试在部署之前。
“太繁琐了，无法测试”	测试比在生产中调试坏技能要少繁琐。
“我有信心它很好”	过度自信保证问题。无论如何都要测试。
“学术审查就足够了”	阅读 ≠ 使用。测试应用场景。
“没有时间测试”	部署未经测试的技能会浪费更多时间在以后修复它。

所有这些意味着：在部署之前测试。没有例外。

防止合理化的防弹技能

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

**心理学注释：**了解为什么说服技巧有效可以帮助你系统地应用它们。有关研究基础的更多信息，请参见 persuasion-principles.md（Cialdini, 2021; Meincke et al., 2025）关于权威、承诺、稀缺、社会证明和统一原则。

明确关闭每个漏洞

不要只陈述规则 - 禁止特定的变通方法：

<Bad>

写测试前的代码？删除它。

</Bad>

<Good>

写测试前的代码？删除它。重新开始。

**没有例外：**
- 不要将其保留为 "参考"
- 不要在写测试时 "适应" 它
- 不要看它
- 删除意味着删除

</Good>

应对 “精神与文字” 争论

早期添加基本原则：

**违反规则的文字就是违反规则的精神。**

这切断了整个类别的 “我遵循精神” 合理化。

构建合理化表格

从基线测试中捕获合理化（见下面的测试部分）。代理提出的每一个借口都进入表格：

| 借口 | 现实 |
|--------|---------|
| "太简单，无法测试" | 简单的代码会中断。测试需要 30 秒。 |
| "我会之后测试" | 立即通过的测试证明不了什么。 |
| "之后测试达到同样的目的" | 之后测试 = "这是什么？" 首先测试 = "这应该是什么？" |

创建红旗列表

使代理能够轻松自我检查何时合理化：

## 红旗 - 停止并重新开始

- 测试前的代码
- "我已经手动测试过了"
- "之后测试达到同样的目的"
- "是关于精神不是仪式"
- "这是不同的，因为..."

**所有这些都意味着：删除代码。重新开始 TDD。**

更新 CSO 违规症状

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

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

RED-GREEN-REFACTOR 技能

遵循 TDD 循环：

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

在没有技能的情况下，用子代理运行压力场景。逐字记录确切行为：

• 他们做了什么选择？
• 他们使用了哪些合理化（逐字）？
• 哪些压力触发了违规？

这是 “观察测试失败” - 你必须在编写技能之前看到代理自然做什么。

GREEN: 编写最小技能

编写解决这些特定合理化的技能。不要为假设情况添加额外内容。

用技能运行相同的场景。代理现在应该遵从。

REFACTOR: 关闭漏洞

代理找到了新的合理化？添加明确的对策。重新测试直到防弹。

测试方法： 见 @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 前言只有名称和描述（最多 1024 个字符）
• [ ] 描述以 “Use when…” 开始，并包括特定触发器/症状
• [ ] 以第三人称写描述
• [ ] 整个关键词搜索（错误、症状、工具）
• [ ] 清晰的概述和核心原则
• [ ] 针对 RED 中识别的特定基线失败
• [ ] 代码内联或链接到单独文件
• [ ] 一个优秀的示例（不是多语言）
• [ ] 用技能运行场景 - 验证代理现在遵从

REFACTOR 阶段 - 关闭漏洞：

• [ ] 从测试中识别新的合理化
• [ ] 添加明确的对策（如果是纪律技能）
• [ ] 从所有测试迭代中构建合理化表格
• [ ] 创建红旗列表
• [ ] 重新测试直到防弹

质量检查：

• [ ] 仅在决策不明显时使用小型流程图
• [ ] 快速参考表
• [ ] 常见错误部分
• [ ] 无叙事故事
• [ ] 仅用于工具或重参考的支持文件

部署：

• [ ] 提交技能到 git 并推送到你的分支（如果配置）
• [ ] 考虑通过 PR 贡献回来（如果广泛有用）

发现工作流程

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

1. 遇到问题（“tests are flaky”）
2. 找到 SKILL（描述匹配）
3. 扫描概述（这是否相关？）
4. 阅读模式（快速参考表）
5. 加载示例（仅在实施时）

为此流程优化 - 尽早并经常放置可搜索的术语。

底线

创建技能是流程文档的 TDD。

相同的铁律：没有技能就没有失败的测试。 相同的循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（关闭漏洞）。 相同的好处：更好的质量，更少的惊喜，防弹结果。

如果你遵循 TDD 编写代码，就遵循它编写技能。这是相同的纪律应用于文档。