name: 写作技能 description: 使用当用户要求创建、写、编辑或测试技能时。也用于记录可重用技术、模式或工作流，供未来Claude实例使用。

写作技能

概述

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

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

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

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

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

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

什么是技能？

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

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

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

技能与其他Claude功能对比

理解何时使用每个功能：

功能	目的	使用时机
自定义指令	您的个性	所有对话的全局设置：“始终使用主动语态”，沟通风格，一般偏好
项目	您的参考库	在该项目每次聊天开始时加载的静态上下文。始终在上下文中，永不释放。背景文档，公司背景，技术规范
技能	您的专家团队	需要时按需加载，然后释放。可包含可执行代码。任务特定工作流，专门程序
MCP	您的外部连接	标准化协议，连接Claude到工具和数据源（数据库访问，API连接，工具集成）

它们如何协同工作：

示例工作流：

自定义指令 设置您的写作风格
项目包含公司背景和品牌指南
MCP服务器 让Claude访问您的CRM数据
技能定义工作流：“生成季度报告时，通过MCP获取CRM数据，分析趋势，应用项目中的品牌指南，并按我偏好的风格格式化”

关键区别： MCP处理连接，技能处理工作流。

三层架构

技能分阶段加载信息。理解这点改变您如何结构化它们：

级别1：元数据（始终加载）

仅YAML前置的 name 和 description
每技能约100令牌成本
这就是为什么您能有数百个技能而无性能问题
在此放置触发逻辑

级别2：指令（触发时加载）

带逐步指导的完整SKILL.md主体
通常低于5,000令牌（保持在500行内）
这是Claude学习工作流的地方
在此放置推理和编排

级别3：资源（需要时加载）

Python脚本、模板、参考文档
实际上无限，因为脚本执行不加载到上下文
仅输出返回到Claude
在此放置确定性操作和代码

为什么重要： 不要编写包含代码片段的庞大级别2指令。编写紧凑的级别2指令，说“运行 analyze.py”，并将实际代码放在级别3。Claude执行脚本，仅看到输出。效率更高。

技能的TDD映射

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

整个技能创建过程遵循红-绿-重构。

何时创建技能

创建时机：

技术对您不直观明显
您会跨项目再次参考
模式广泛适用（非项目特定）
其他人会受益

不要为以下创建：

一次性解决方案
其他地方充分记录的标准实践
项目特定约定（放在CLAUDE.md中）

技能类型

技术

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

模式

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

参考

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

目录结构

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

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

单独文件用于：

重度参考（100+行） - API文档，全面语法
可重用工具 - 脚本，实用程序，模板

内联保留：

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

SKILL.md 结构

前置（YAML）：

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

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

# 技能名称

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

## 使用时机
[小内联流程图 若决策不明显]

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

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

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

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

## 常见错误
出错内容 + 修复

## 真实世界影响（可选）
具体结果

Claude搜索优化（CSO）

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

1. 丰富描述字段

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

格式： 以“使用当…”开始，聚焦触发条件

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

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

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

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

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

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

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

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

# ✅ 好：仅触发条件
description: 使用当实施任何功能或bugfix，在写实施代码前

内容：

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

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

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

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

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

# ✅ 好：技术特定技能，明确触发
description: 使用当使用React Router并处理认证重定向时

多技能协调

若有多个相关技能，使它们的触发互斥：

# csv-validator - 窄，早期触发
description: 当CSV文件上传时，立即验证格式，检查编码问题，并在任何分析前验证结构完整性。

# csv-analyzer - 广，验证后发生
description: 当分析已验证CSV数据时，生成全面统计，识别模式，检测异常值，并创建可视化。

# csv-transformer - 特定操作触发
description: 当用户请求CSV转换、转换或重塑时，修改结构，过滤行，聚合数据，或导出到不同格式。

每个技能有清晰、不重叠的触发。它们可以顺序协同工作。

2. 关键词覆盖

使用Claude会搜索的词：

错误消息：“Hook timed out”, “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 认证错误处理 401”]

# ✅ 好：最小示例（20词）
伙伴：“我们如何处理React Router中的认证错误？”
您：搜索中...
[派发子代理 → 综合]

消除冗余：

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

验证：

wc -w skills/路径/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. 交叉引用其他技能

当编写参考其他技能的文档时：

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

✅ 好：**必需子技能：** 使用超能力：测试驱动开发
✅ 好：**必备背景：** 您必须理解超能力：系统调试
❌ 差：见技能/测试/测试驱动开发（不明确是否必需）
❌ 差：@技能/测试/测试驱动开发/SKILL.md（强制加载，消耗上下文）

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

流程图使用

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

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

仅使用流程图用于：

不明显决策点
您可能过早停止的过程循环
“使用A vs B”决策

绝不使用流程图用于：

参考材料 → 表，列表
代码示例 → Markdown块
线性指令 → 编号列表
无语义含义的标签（步骤1，助手2）

见 @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: 使用当实施任何功能或bugfix，在写实施代码前

技能的红-绿-重构

遵循TDD循环：

红：写失败测试（基线）

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

它们做出什么选择？
它们使用什么合理化（逐字）？
哪些压力触发违规？

这是“观察测试失败” - 您必须观察代理自然行为，在写技能前。

绿：写最小技能

写技能，解决那些特定合理化。不添加额外内容用于假设案例。

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

重构：关闭漏洞

代理找到新合理化？添加明确对抗。重新测试直到防弹。

测试方法论： 见@testing-skills-with-subagents.md完整测试方法论：

如何写压力场景
压力类型（时间，沉没成本，权威，疲惫）
系统填补漏洞
元测试技术

构建小型聚焦技能

反模式： 一个技能试图做所有事。

# ❌ 差：瑞士军刀技能
name: content-creator
description: 当创建内容时，处理博客文章、社交媒体、电子邮件活动、文档、新闻稿和营销文案。

这太宽泛。Claude很少正确触发它。当触发时，指令太长Claude混淆。

模式： 一个技能做一件事异常好。

拆分为聚焦技能：

# ✅ 好：聚焦技能
name: blog-post-writer
description: 当写博客文章时，生成SEO优化长内容，遵循品牌指南，带适当结构和元描述。

name: social-media-adapter
description: 当转换现有内容到社交媒体帖子时，适应语气和格式用于Twitter、LinkedIn和Instagram，带适当标签。

name: email-campaign-generator
description: 当创建电子邮件活动时，生成主题行、预览文本、正文文案和CTAs，优化转换。

原则： 如果您在描述中写“和也”，您需要两个技能。

复杂工作流通过组合多个技能发生，而非将所有内容塞入一个。

技能即代码分发

最佳模式针对团队：对待技能像代码。

设置：

项目根/
├── .claude/
│   └── skills/
│       ├── csv-analyzer/
│       │   ├── SKILL.md
│       │   └── analyze.py
│       ├── blog-writer/
│       │   └── SKILL.md
│       └── git-commit-helper/
│           └── SKILL.md
├── src/
└── README.md

工作流：

在您仓库创建 .claude/skills/ 目录
每个技能是带SKILL.md和任何脚本的子文件夹
提交到git像任何其他代码
团队成员 git pull 时自动获取技能
更新版本控制，可审查

好处：

无手动分发
技能演化版本控制
技能更改代码审查
新团队成员克隆时获得完整剧本
技能通过现有开发工作流传播

反模式

❌ 叙述示例

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

重构阶段 - 关闭漏洞：

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

质量检查：

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

部署：

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

发现工作流

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

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

优化此流 - 将可搜索术语早而频繁放置。

底线

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

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

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