name: 写作技能 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.*     # 仅当需要时

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

单独文件用于：

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

保持内联：

原则和概念
代码模式 (< 50 行)
其他所有内容

设置适当的自由度

将特异性级别与任务的脆弱性和可变性匹配：

高自由度（基于文本的指令）：当多种方法有效或决策取决于上下文时使用。
中等自由度（伪代码或带参数的脚本）：当存在首选模式但一些变化可接受时使用。
低自由度（特定脚本、无上下文指令）：当操作脆弱、易错或一致性关键时使用。

渐进披露

通过将详细信息拆分为单独文件来高效管理上下文：

元数据（名称 + 描述）：始终加载以供发现。
SKILL.md 正文：核心工作流和高级指导。保持低于 500 行。
捆绑资源：
- scripts/：确定性代码/逻辑。
- references/：详细模式、API 文档或领域知识。
- assets/：模板、图像或静态文件。

模式： 从主 SKILL.md 链接到高级内容或变体特定细节（例如，aws.md vs gcp.md）。

SKILL.md 结构

前置内容（YAML）：

仅支持两个字段：name 和 description
最多 1024 字符总数
name：仅使用字母、数字和连字符（无括号、特殊字符）
description：第三人称，仅描述何时使用（非做什么）
- 以“Use when…”开头以聚焦触发条件
- 包括具体症状、情境和上下文
- 永远不要总结技能的过程或工作流（参见 CSO 部分了解原因）
- 如果可能，保持低于 500 字符

---
name: 技能名称-带连字符
description: 使用当 [具体触发条件和症状]
---

# 技能名称

## 概述

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

## 何时使用

[如果决策非明显，小内联流程图]

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

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

前后代码比较

## 快速参考

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

## 实现

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

## 常见错误

出错内容 + 修复

## 实际影响（可选）

具体结果

Claude 搜索优化 (CSO)

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

1. 丰富描述字段

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

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

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

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

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

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

陷阱： 总结工作流的描述创建了 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. 令牌效率（关键）

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

目标词数：

入门工作流：每个 <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
主动，描述您正在采取的行动

4. 交叉引用其他技能

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

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

✅ 好：**必需子技能：** 使用 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 vs B”决策

永远不要将流程图用于：

参考材料 → 表格、列表
代码示例 → Markdown 块
线性指令 → 编号列表
无语义意义的标签（step1、helper2）

有关 graphviz 样式规则，请参阅 @graphviz-conventions.dot。

为人类伙伴可视化： 使用此目录中的 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、完成前验证、编码前设计

测试用：

学术问题：他们理解规则吗？
压力场景：他们在压力下遵守吗？
多个压力组合：时间 + 沉没成本 + 疲劳
识别合理化并添加明确计数器

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

技术技能（操作指南）

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

测试用：

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

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

模式技能（心智模型）

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

测试用：

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

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

参考技能（文档/APIs）

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

测试用：

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

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

跳过测试的常见合理化

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

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

防御技能免受合理化

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

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

明确关闭每个漏洞

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

<坏>

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

</坏>

<好>

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

**无例外：**

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

</好>

处理“精神 vs 文字”论点

早期添加基本原则：

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

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

构建合理化表

从基线测试中捕获合理化（参见下面的测试部分）。代理制造的每个借口都放入表中：

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

创建红旗列表

让代理在合理化时轻松自我检查：

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

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

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

更新 CSO 用于违规症状

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

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

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

REFACTOR 阶段—关闭漏洞：

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

质量检查：

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

部署：

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

发现工作流

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

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

优化此流程—将可搜索术语放在早期并频繁。

底线

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

相同铁律：没有技能没有先失败的测试。

相同循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（关闭漏洞）。

相同好处：更好质量、更少意外、防弹结果。

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