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

写作技能

概述

写作技能是测试驱动开发应用于过程文档。

个人技能位于代理特定目录中（Claude Code 的 ~/.claude/skills，Codex 的 ~/.agents/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：第三人称，仅描述何时使用（而非做什么）
- 以“Use when…”开头以关注触发条件
- 包括具体症状、情况和上下文
- 绝不要总结技能的过程或工作流程（参见 CSO 部分了解原因）
- 尽可能保持在 500 字符以内

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# 技能名称

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

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

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

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

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

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

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

## 实际影响（可选）
具体结果

Claude 搜索优化（CSO）

发现关键： 未来的 Claude 需要找到您的技能

1. 丰富描述字段

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

格式： 以“Use when…”开头以关注触发条件

关键：描述 = 何时使用，而非技能做什么

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

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

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

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

# ❌ 坏：总结工作流程 - Claude 可能遵循此而非阅读技能
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ 坏：太多过程细节
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

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

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

内容：

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

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

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

# ❌ 坏：提及技术但技能不特定于它
description: Use when tests use setTimeout/sleep and are flaky

# ✅ 好：以“Use when”开头，描述问题，无工作流程
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ 好：技术特定技能，带明确触发器
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 词（仍要简洁）

技术：

移动细节到工具帮助：

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

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

使用交叉引用：

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

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

压缩示例：

# ❌ 坏：详细示例（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"]

# ✅ 好：最小示例（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 与 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）

NO SKILL WITHOUT A FAILING TEST FIRST

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

先写技能再测试？删除它。重新开始。编辑技能不测试？同样违规。

无例外：

非“简单添加”
非“仅添加部分”
非“文档更新”
不将未测试更改保留为“参考”
不“在运行测试时适应”
删除意味着删除

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

测试所有技能类型

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

纪律强制技能（规则/要求）

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

测试用：

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

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

技术技能（如何做指南）

示例： 条件等待、根源追踪、防御性编程

测试用：

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

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

模式技能（心智模型）

示例： 减少复杂性、信息隐藏概念

测试用：

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

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

参考技能（文档/API）

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

测试用：

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

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

跳过测试的常见合理化

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

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

针对合理化的技能防弹

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

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

明确关闭每个漏洞

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

<坏>

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

</坏>

<好>

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

**无例外：**
- 不保留为“参考”
- 不在编写测试时“适应”它
- 不看它
- 删除意味着删除

</好>

处理“精神与文字”论点

早期添加基础原则：

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

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

构建合理化表

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

| 借口 | 现实 |
|--------|---------|
| “太简单不测试” | 简单代码会坏。测试需要 30 秒。 |
| “我之后测试” | 测试通过立即证明无。 |
| “之后测试达到相同目标” | 之后测试 = “这做什么？” 先测试 = “这应该做什么？” |

创建红旗列表

使代理在合理化时易于自我检查：

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

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

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

更新 CSO 为违规症状

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

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

技能的 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 前言仅 name 和 description（最多 1024 字符）
[ ] 描述以“Use when…”开头并包括具体触发器/症状
[ ] 描述以第三人称编写
[ ] 关键词遍及搜索（错误、症状、工具）
[ ] 清晰概述带核心原则
[ ] 解决红色中识别的特定基线失败
[ ] 代码内联或链接到单独文件
[ ] 一个优秀示例（非多语言）
[ ] 运行场景，带技能—验证代理现在遵守

重构阶段—关闭漏洞：

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

质量检查：

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

部署：

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

发现工作流程

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

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

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

底线

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

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

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