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-REFACTOR。

何时创建技能

创建时机：

技术对您来说不是直观明显的
您会在项目中再次参考此内容
模式广泛适用（非项目特定）
他人会受益

不要创建：

一次性解决方案
其他地方有良好文档的标准实践
项目特定约定（放在 CLAUDE.md 中）
机械约束（如果可以用正则表达式/验证强制执行，自动化它—为判断性决策保存文档）

技能类型

技术

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

模式

思考问题的方式（带标志扁平化、测试不变量）

参考

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

目录结构

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

扁平命名空间 - 所有技能在一个可搜索的命名空间中

单独文件用于：

重参考（100+ 行） - API 文档、综合语法
可重用工具 - 脚本、实用程序、模板

内联保留：

原则和概念
代码模式（< 50 行）
其他一切

SKILL.md 结构

前端元数据（YAML）：

仅支持两个字段：name 和 description
总共最多 1024 字符
name：仅使用字母、数字和连字符（无括号、特殊字符）
description：第三人称，仅描述何时使用（非功能）
- 以“在…时使用”开头，聚焦触发条件
- 包括具体症状、情况和上下文
- 绝不总结技能的过程或工作流（见 CSO 部分原因）
- 尽可能保持在 500 字符以内

---
name: Skill-Name-With-Hyphens
description: 在 [具体触发条件和症状] 时使用
---

# 技能名称

## 概述

这是什么？1-2 句核心原则。

## 何时使用

[如果决策非显而易见，添加小型内联流程图]

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

## 核心模式（用于技术/模式）

前后代码比较

## 快速参考

用于扫描常见操作的表格或子弹列表

## 实现

简单模式的内联代码
重参考或可重用工具的文件链接

## 常见错误

出问题的地方 + 修复

## 实际影响（可选）

具体结果

Claude 搜索优化（CSO）

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

1. 丰富描述字段

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

格式： 以“在…时使用”开头，聚焦触发条件

关键：描述 = 何时使用，非技能功能

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

为什么重要： 测试显示，当描述总结技能工作流时，Claude 可能遵循描述而非读取完整技能内容。描述说“任务间代码审查”导致 Claude 进行一次审查，即使技能的流程图清楚显示两次审查（规范符合性然后代码质量）。

当描述更改为“在当前会话中执行具有独立任务的实施计划时使用”（无工作流总结），Claude 正确读取流程图并遵循两阶段审查过程。

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

# ❌ 差：总结工作流 - Claude 可能遵循此而非读取技能
description: 在执行计划时使用 - 每个任务分派子代理并在任务间进行代码审查

# ❌ 差：太多过程细节
description: 用于 TDD - 先写测试，观察失败，写最小代码，重构

# ✅ 好：仅触发条件，无工作流总结
description: 在当前会话中执行具有独立任务的实施计划时使用

# ✅ 好：仅触发条件
description: 在实现任何功能或错误修复前，编写实施代码前使用

内容：

使用具体触发器、症状和表示此技能适用的情况
描述问题（竞争条件、不一致行为）而非语言特定症状（setTimeout、sleep）
保持触发器与技术无关，除非技能本身是技术特定的
如果技能是技术特定的，在触发器中明确说明
用第三人称编写（注入系统提示）
绝不总结技能的过程或工作流

# ❌ 差：太抽象、模糊，不包括何时使用
description: 用于异步测试

# ❌ 差：第一人称
description: 我可以在测试不稳定时帮助您进行异步测试

# ❌ 差：提到技术但技能不特定于它
description: 在测试使用 setTimeout/sleep 且不稳定时使用

# ✅ 好：以“在...时使用”开头，描述问题，无工作流
description: 在测试有竞争条件、时间依赖性或通过/失败不一致时使用

# ✅ 好：技术特定技能，明确触发器
description: 在使用 React Router 并处理身份验证重定向时使用

2. 关键词覆盖

使用 Claude 会搜索的词：

错误消息：“钩子超时”、“ENOTEMPTY”、“竞争条件”
症状：“不稳定”、“挂起”、“僵尸”、“污染”
同义词：“超时/挂起/冻结”、“清理/拆卸/afterEach”
工具：实际命令、库名、文件类型

3. 描述性命名

使用主动语态，动词优先：

✅ creating-skills 非 skill-creation
✅ condition-based-waiting 非 async-test-helpers

4. 令牌效率（关键）

问题： 入门和频繁引用的技能加载到每个对话中。每个令牌都重要。

目标字数：

入门工作流：每个 <150 字
频繁加载技能：总共 <200 字
其他技能：<500 字（仍要简洁）

技术：

将细节移到工具帮助：

# ❌ 差：在 SKILL.md 中记录所有标志
search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N

# ✅ 好：参考 --help
search-conversations 支持多种模式和过滤器。运行 --help 获取细节。

使用交叉引用：

# ❌ 差：重复工作流细节

搜索时，用模板分派子代理...
[20 行重复指令]

# ✅ 好：引用其他技能

始终使用子代理（50-100x 上下文节省）。必需：使用 [其他技能名称] 作为工作流。

压缩示例：

# ❌ 差：冗长示例（42 字）

您的人类伙伴：“我们之前在 React Router 中如何处理身份验证错误？”
您：我会搜索过去对话中的 React Router 身份验证模式。
[分派子代理，搜索查询：“React Router authentication error handling 401”]

# ✅ 好：最小示例（20 字）

伙伴：“在 React Router 中如何处理身份验证错误？”
您：搜索中...
[分派子代理 → 合成]

消除冗余：

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

验证：

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
主动，描述您采取的行动

5. 交叉引用其他技能

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

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

✅ 好：**必需子技能：** 使用 superpowers:test-driven-development
✅ 好：**必读背景：** 您必须理解 superpowers:systematic-debugging
❌ 差：参见 skills/testing/test-driven-development（不清楚是否必需）
❌ 差：@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）

为什么无 @ 链接： @ 语法立即强制加载文件，在您需要它们之前消耗 200k+ 上下文。

流程图使用

digraph when_flowchart {
    “需要显示信息？” [shape=diamond];
    “决策我可能出错的地方？” [shape=diamond];
    “使用 markdown” [shape=box];
    “小型内联流程图” [shape=box];

    “需要显示信息？” -> “决策我可能出错的地方？” [label=“是”];
    “决策我可能出错的地方？” -> “小型内联流程图” [label=“是”];
    “决策我可能出错的地方？” -> “使用 markdown” [label=“否”];
}

仅使用流程图用于：

非显而易见的决策点
您可能过早停止的过程循环
“何时使用 A 对 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

好示例：

完整且可运行
良好注释，解释为什么
来自真实场景
清晰显示模式
准备好适应（非通用模板）

不要：

用 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、完成前验证、编码前设计

测试用：

学术问题：他们理解规则吗？
压力场景：他们在压力下遵守吗？
多重压力组合：时间 + 沉没成本 + 疲惫
识别理由并添加明确反驳

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

技术技能（操作指南）

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

测试用：

应用场景：他们能正确应用技术吗？
变体场景：他们处理边缘情况吗？
缺失信息测试：指令有空白吗？

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

模式技能（心智模型）

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

测试用：

识别场景：他们识别何时模式适用吗？
应用场景：他们能使用心智模型吗？
反例：他们知道何时不应用吗？

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

参考技能（文档/API）

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

测试用：

检索场景：他们能找到正确信息吗？
应用场景：他们能正确使用找到的内容吗？
空白测试：常见使用案例覆盖了吗？

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

跳过测试的常见理由

借口	现实
“技能明显清晰”	对您清晰 ≠ 对其他代理清晰。测试它。
“它只是参考”	参考可能有空白、不清晰部分。测试检索。
“测试过度”	未测试技能有问题。总是。15 分钟测试节省小时。
“如果问题出现我会测试”	问题 = 代理无法使用技能。部署前测试。
“测试太乏味”	测试比调试生产中的坏技能更不乏味。
“我有信心它好”	过度自信保证问题。无论如何测试。
“学术审查足够”	阅读 ≠ 使用。测试应用场景。
“没时间测试”	部署未测试技能浪费更多时间稍后修复它。

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

防理由技能加固

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

心理学注： 理解为什么说服技术有效有助于您系统应用它们。参见 persuasion-principles.md 获取研究基础（Cialdini, 2021; Meincke et al., 2025）关于权威、承诺、稀缺性、社会证明和统一原则。

明确关闭每个漏洞

不要仅陈述规则—禁止特定变通：

<差>

先写代码后测试？删除它。

</差>

<好>

先写代码后测试？删除它。重新开始。

**无例外：**

- 不要将其保留为“参考”
- 不要写测试时“适应”它
- 不要看它
- 删除意味着删除

</好>

处理“精神对文字”争论

早期添加基本原则：

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

这切断整个“我遵循精神”理由类。

构建理由表

从基线测试捕获理由（见下面测试部分）。代理提出的每个借口放入表：

| 借口                           | 现实                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| “太简单无需测试”             | 简单代码中断。测试花费 30 秒。                              |
| “我会稍后测试”                | 立即通过测试证明无物。                                |
| “测试后达到相同目标” | 测试后 = “这做什么？” 测试前 = “这应该做什么？” |

创建红旗列表

使代理在理由时易于自检：

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

- 先代码后测试
- “我已经手动测试了它”
- “测试后达到相同目的”
- “这是关于精神非仪式”
- “这不同因为...”

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

为违规症状更新 CSO

添加到描述：您即将违反规则的症状：

description: 在实现任何功能或错误修复前，编写实施代码前使用

技能的 RED-GREEN-REFACTOR

遵循 TDD 循环：

红色：写失败测试（基线）

运行带子代理的压力场景，无技能。记录确切行为：

他们做了哪些选择？
他们使用了哪些理由（逐字）？
哪些压力触发违规？

这是“观察测试失败”—您必须看到代理自然做什么，然后编写技能。

绿色：写最小技能

编写解决这些特定理由的技能。不要为假设案例添加额外内容。

运行相同场景，带技能。代理现在应遵守。

重构：关闭漏洞

代理找到新理由？添加明确反驳。重新测试直到防弹。

测试方法： 参见 @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 为下面每个清单项创建待办事项。

红色阶段—写失败测试：

[ ] 创建压力场景（纪律技能 3+ 组合压力）
[ ] 运行场景无技能—逐字记录基线行为
[ ] 识别理由/失败模式

绿色阶段—写最小技能：

[ ] 名称仅使用字母、数字、连字符（无括号/特殊字符）
[ ] YAML 前端元数据，仅名称和描述（最多 1024 字符）
[ ] 描述以“在…时使用”开头，包括具体触发器/症状
[ ] 描述用第三人称编写
[ ] 整个中关键词搜索（错误、症状、工具）
[ ] 清晰概述，带核心原则
[ ] 解决红色中识别的特定基线失败
[ ] 代码内联或链接到单独文件
[ ] 一个优秀示例（非多语言）
[ ] 运行场景带技能—验证代理现在遵守

重构阶段—关闭漏洞：

[ ] 从测试识别新理由
[ ] 添加明确反驳（如果纪律技能）
[ ] 从所有测试迭代构建理由表
[ ] 创建红旗列表
[ ] 重新测试直到防弹

质量检查：

[ ] 仅如果决策非显而易见，小型流程图
[ ] 快速参考表
[ ] 常见错误部分
[ ] 无叙述性讲故事
[ ] 支持文件仅用于工具或重参考

部署：

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

发现工作流

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

遇到问题（“测试不稳定”）
找到技能（描述匹配）
扫描概述（这相关吗？）
读取模式（快速参考表）
加载示例（仅在实现时）

优化此流程—早期和经常放可搜索术语。

底线

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

相同铁律：无失败测试前无技能。相同循环：红色（基线）→ 绿色（写技能）→ 重构（关闭漏洞）。相同好处：更好质量、更少意外、防弹结果。

如果您对代码遵循 TDD，对技能也遵循。这是应用于文档的相同纪律。