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

写作技能

概述

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

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

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

核心原则： 如果您没有观察代理在没有技能时失败，您就不知道技能是否教授正确的内容。

必备背景： 使用此技能前，您必须理解超能力：测试驱动开发。该技能定义了基本的RED-GREEN-REFACTOR循环。此技能将TDD应用于文档。

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

什么是技能？

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

技能是： 可重用技术、模式、工具、参考指南

技能不是： 关于您如何一次解决问题的叙述

技能的TDD映射

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

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

何时创建技能

创建时机：

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

不要为以下情况创建：

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

技能类型

技术

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

模式

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

参考

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

目录结构

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: 当[具体触发条件和症状]时使用
---

# 技能名称

## 概述
这是什么？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会搜索的词语：

错误消息：“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-100倍上下文节省）。必需：使用[其他技能名]进行工作流。

压缩示例：

# ❌ 错误：冗长示例（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. 交叉引用其他技能

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

仅使用技能名，具有明确需求标记：

✅ 良好：**必需子技能：** 使用超能力：测试驱动开发
✅ 良好：**必备背景：** 您必须理解超能力：系统调试
❌ 错误：见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-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相同）

没有失败测试先，没有技能

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

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

无例外：

非为“简单添加”
非为“仅添加章节”
非为“文档更新”
不保留未测试更改作为“参考”
不“适配”同时运行测试
删除意味着删除

必备背景： 超能力：测试驱动开发技能解释为何重要。相同原则适用于文档。

测试所有技能类型

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

纪律强制执行技能（规则/需求）

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

测试使用：

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

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

技术技能（操作指南）

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

测试使用：

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

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

模式技能（心智模型）

示例： 减少复杂度，信息隐藏概念

测试使用：

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

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

参考技能（文档/API）

示例： 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，对技能也遵循它。它是相同纪律应用于文档。