写作技能

概述

写作技能 = 将测试驱动开发（TDD）应用于流程文档的实践。

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

你编写测试用例（带子代理的压力场景），观察其失败（基线行为），撰写技能文档（即技能本身），再观察测试通过（代理遵从规则），最后重构（修补漏洞）。

核心原则： 如果你没有在未提供技能的情况下观察到代理的失败，你就无法确定该技能是否真正教会了正确的内容。

必要背景知识： 在使用本技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。本技能将 TDD 方法适配至文档编写。

官方指南： 关于 Anthropic 官方技能创作最佳实践，请参阅 anthropic-best-practices.md。本文档提供了补充性的模式与指导，与本技能聚焦 TDD 的方法相辅相成。

什么是技能？

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

技能是： 可复用的方法、模式、工具、参考手册

技能不是： 关于你一次性解决问题的叙述性记录

技能创建中的 TDD 映射

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

何时创建技能

应创建的情况：

• 该技术对你而言并非显而易见
• 你在多个项目中会再次参考
• 该模式具有广泛适用性（非项目专属）
• 其他人会从中受益

不应创建的情况：

• 一次性解决方案
• 已在其他地方充分记录的标准实践
• 项目特有约定（应放入 CLAUDE.md）
• 机械性约束（若可通过正则或校验实现，应自动化——文档仅用于判断性决策）

技能类型

技术（Technique）

具体的可操作方法，包含明确步骤（如条件等待、根因追踪）

模式（Pattern）

思考问题的方式（如标志展平、测试不变量）

参考（Reference）

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: Use when [具体触发条件与症状]
---

# 技能名称

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

## 何时使用
[若决策不明确，可附简短流程图]

- 列出症状与使用场景
- 不应使用的情况

## 核心模式（适用于技术/模式类）
前后代码对比示例

## 快速参考
表格或列表形式，便于快速扫描常见操作

## 实现方式
简单模式使用内联代码
复杂参考或可复用工具请链接至文件

## 常见错误
哪些情况容易出错 + 解决方案

## 实际影响（可选）
具体成果案例

Claude 搜索优化（CSO）

对发现至关重要： 未来的 Claude 需要能够“找到”你的技能

1. 丰富的描述字段

目的： Claude 会根据描述决定在当前任务中加载哪些技能。确保它能回答：“我现在应该读这个技能吗？”

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

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

描述应仅描述触发条件。不要在描述中总结技能的工作流程或执行步骤。

为何重要： 测试表明，当描述中总结了技能流程时，Claude 可能直接按照描述执行，而跳过阅读完整技能内容。例如，一个描述为“任务间进行代码审查”的技能，导致 Claude 只执行一次审查；而实际上技能中的流程图明确要求两次审查（规范符合性检查 + 代码质量检查）。

当描述改为“Use when executing implementation plans with independent tasks”（仅说明触发条件，不提流程），Claude 正确读取了流程图，并执行了双阶段审查。

陷阱： 描述中包含流程总结会诱导 Claude 走捷径。技能正文变成被忽略的文档。

# ❌ 错误：总结工作流程 - Claude 可能遵循此描述而非阅读技能本身
description: 用于执行实施计划时 - 每个任务分配子代理，并在任务间进行代码审查

# ❌ 错误：包含过多流程细节
description: 用于 TDD 场景 - 先写测试，观察其失败，再编写最小化代码，最后重构

# ✅ 正确：仅描述触发条件，不包含工作流程
description: 在当前会话中执行独立任务的实施计划时使用

# ✅ 正确：仅描述触发条件
description: 在编写实现代码前，用于实现任何功能或修复缺陷时

内容要求：

• 使用具体可识别的触发条件、症状和情境来表明该技能适用
• 描述问题本质（如竞态条件、行为不一致），而非语言特定的症状（如 setTimeout、sleep）
• 触发条件应保持技术无关性，除非该技能本身具有技术专属性
• 若技能具有技术专属性，应在触发条件中明确说明
• 使用第三人称书写（注入系统提示）
• 绝不总结技能的处理流程或工作步骤

# ❌ 错误：过于抽象模糊，未说明何时使用
description: 用于异步测试

# ❌ 错误：使用第一人称
description: 我可以在异步测试出现不稳定时提供帮助

# ❌ 错误：提及技术但技能并非专门针对该技术
description: 当测试使用 setTimeout/sleep 且结果不稳定时使用

# ✅ 正确：以“使用当”开头，描述问题，不包含流程
description: 当测试存在竞态条件、时间依赖性，或通过/失败结果不一致时使用

# ✅ 正确：技术专属性技能，触发条件明确
description: 使用 React Router 并处理认证重定向时使用

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

问题： getting-started 和高频调用的技能会加载到每一次对话中。每个 token 都至关重要。

目标字数：

• getting-started 流程：每项 <150 字
• 高频加载技能：总计 <200 字
• 其他技能：<500 字（仍需简洁）

优化技巧：

将细节移至工具帮助文档：

# ❌ 错误：在 SKILL.md 中罗列所有参数
search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N

# ✅ 正确：引用 --help
search-conversations 支持多种模式和过滤器。运行 --help 查看详细信息。

使用交叉引用：

# ❌ 错误：重复工作流程说明
搜索时，使用模板分派子代理...
[重复 20 行指令]

# ✅ 正确：引用其他技能
始终使用子代理（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 完成流程。

压缩示例：

# ❌ 错误：冗长示例（42 字）
你的合作伙伴：“我们之前如何处理 React Router 的认证错误？”
你：我将搜索过往对话中关于 React Router 认证模式的内容。
[分派子代理，查询： "React Router authentication error handling 401"]

# ✅ 正确：极简示例（20 字）
合作伙伴：“如何处理 React Router 的认证错误？”
你：正在搜索...
[分派子代理 → 综合]

消除冗余：

• 不重复交叉引用技能中的内容
• 不解释命令本身已明确的信息
• 不重复多个相同模式的示例

验证方法：

wc -w skills/path/SKILL.md
# getting-started 流程：目标 <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（强制加载，消耗上下文）

为何不使用 @ 链接： @ 语法会立即强制加载文件，提前消耗超过 20 万上下文，而你可能尚未需要。

流程图使用

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 一致）

没有失败测试的技能，就不算技能

此规则适用于新技能创建以及对已有技能的修改。

先写技能再写测试？删除它。从头开始。

修改技能却不写测试？同样违反规则。

无一例外：

• 不因“简单补充”而跳过
• 不因“仅添加章节”而跳过
• 不因“文档更新”而跳过
• 不将未测试的变更保留为“参考”
• 不在运行测试时“临时调整”
• 删除即彻底删除

必要背景： superpowers:test-driven-development 技能详细解释了为何如此重要。文档编写同样遵循相同原则。

各类技能的测试方法

不同类型的技能需要不同的测试策略：

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

示例： TDD、验证先行、设计优先于编码

测试方式：

• 学术问题：是否理解规则？
• 压力场景：在高压下能否遵守？
• 多重压力组合：时间紧迫 + 沉没成本 + 精神疲劳
• 识别合理化借口，并设置明确反制措施

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

技术型技能（操作指南类）

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

测试方式：

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

成功标准： 代理能在新场景中成功应用该技术

模式型技能（心智模型类）

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

测试方式：

• 识别场景：能否判断该模式适用？
• 应用场景：能否有效运用该心智模型？
• 反例测试：能否识别不适用的情况？

成功标准： 代理能准确判断何时/如何应用该模式

参考型技能（文档/API 类）

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

测试方式：

• 检索场景：能否找到正确信息？
• 应用场景：能否正确使用所查信息？
• 缺陷测试：常见用例是否覆盖？

成功标准： 代理能准确检索并正确应用参考信息

常见跳过测试的借口

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

抵抗合理化倾向的技能加固

强制规范类技能（如 TDD）必须能抵御合理化行为。代理在压力下会主动寻找漏洞。

心理学提示： 理解说服技巧的原理，有助于系统性地应用它们。详见 persuasion-principles.md（Cialdini, 2021；Meincke 等, 2025），涵盖权威、承诺、稀缺、社会认同和团结等原则。

明确关闭每一处漏洞

不要只陈述规则，而要禁止具体变通方式：

<坏>

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

</坏>

<好>

写代码前写测试？删除它。从头开始。

**无一例外：**
- 不得保留为“参考”
- 不得在写测试时“临时调整”
- 不得查看
- 删除即彻底删除

</好>

回应“精神 vs 字面”争议

早期引入基础原则：

**违背规则字面，即是违背规则精神。**

这能直接切断“我是在遵循精神”的各类借口。

构建合理化清单

在基线测试中记录代理提出的各种借口。每一条说辞都应列入表格：

| 说辞 | 现实 |
|------|------|
| “太简单不用测” | 简单代码也会出错。测试只需 30 秒。 |
| “我稍后再测” | 测试通过不能证明任何事。 |
| “事后测试能达到同样目标” | 事后测试 = “这是做什么的？” 事前测试 = “它应该做什么？” |

制作红色警报清单

让代理能快速自查是否陷入合理化思维：

红色警报 - 停止并重新开始

• 在测试之前编写代码
• “我已经手动测试过了”
• “测试和实现目标相同”
• “这是精神问题，不是形式问题”
• “这不一样，因为……”

以上所有情况都意味着：删除代码，从 TDD 开始重新构建。

更新 CSO 以包含违规征兆

在 description 中添加：即将违反规则时的征兆：

description: 在实现任何功能或修复 bug 之前使用，写实现代码前

技能开发的红-绿-重构流程

遵循 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 frontmatter 仅包含 name 和 description（最大 1024 字符）
• [ ] description 以“使用场景：…”开头，包含具体触发条件和症状
• [ ] 描述使用第三人称
• [ ] 全文包含关键词以提升搜索（如 errors、symptoms、tools）
• [ ] 清晰概述核心原则
• [ ] 针对红色阶段识别出的具体失败进行回应
• [ ] 代码内联或链接到独立文件
• [ ] 提供一个优秀示例（不支持多语言）
• [ ] 在有技能情况下运行场景——验证代理已合规

重构阶段 - 堵住漏洞：

• [ ] 识别测试中出现的新合理化理由
• [ ] 添加显式反制措施（若为纪律类技能）
• [ ] 从所有测试迭代中建立合理化对照表
• [ ] 创建红色警报列表
• [ ] 重复测试直至无懈可击

质量检查：

• [ ] 仅当决策不明显时才使用小流程图
• [ ] 提供快速参考表格
• [ ] 包含常见错误说明
• [ ] 不包含叙事性描述
• [ ] 支持文件仅用于工具或大量参考资料

部署：

• [ ] 将技能提交至 git 并推送到你的分支（如已配置）
• [ ] 考虑通过 PR 贡献回主项目（若具广泛适用性）

发现工作流

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

1. 遇到问题（“测试不稳定”）
2. 找到技能（描述匹配）
3. 浏览概览（是否相关？）
4. 查阅模式（快速参考表）
5. 加载示例（仅在实施时）

优化此流程——尽早且频繁地放置可搜索术语。

最终要点

创建技能 = 对流程文档执行 TDD。

同样的铁律：没有失败测试，就不写技能。

同样的循环：红色（基线）→ 绿色（编写技能）→ 重构（堵漏洞）。

同样的收益：更高质量、更少意外、坚不可摧的结果。

如果你对代码遵循 TDD，那么对技能也应如此。这只是将同一套纪律应用于文档而已。