写作技能Skill writing-skills

---

名称: 写作技能 描述: 将TDD应用于文档 - 创建生产就绪的技能。在编写新技能时使用。包括清晰散文的写作风格指南。 版本: 1.1 别名: [写作] 模型: opus 调用者: 两者 用户可调用: 是 工具: [读取, 写入, 编辑, Bash, 任务] 最佳实践:

• RED: 首先在没有技能的情况下进行基线测试
• GREEN: 编写最小技能以解决违规
• REFACTOR: 关闭新合理化中的漏洞
• 描述必须仅为触发条件 error_handling: 严格 流式传输: 支持 已验证: 否 最后验证时间: 2026-02-19T05:29:09.098Z

---

写作技能

概述

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

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

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

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

必需背景： 您必须在使用此技能前理解tdd。该技能定义了基本的RED-GREEN-REFACTOR循环。此技能将TDD适应于文档。

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

什么是技能？

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

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

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

技能的TDD映射

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

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

何时创建技能

创建当：

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

不为以下创建：

• 一次性解决方案
• 其他地方有良好文档的标准实践
• 项目特定约定（放在CLAUDE.md中）
• 机械约束（如果可用regex/验证强制执行，自动化它 - 将文档保存用于判断调用）

技能类型

技术

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

模式

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

参考

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

目录结构

skills/
  技能名称/
    SKILL.md              # 主参考（必需）
    支持文件.*     # 仅当需要时

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

为以下单独文件：

1. 重参考（100+行） - API文档，综合语法
2. 可重用工具 - 脚本，实用程序，模板

保持内联：

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

SKILL.md结构

Frontmatter（YAML）：

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

---
name: Skill-Name-With-Hyphens
description: 当 [具体触发条件和症状] 时使用
---

# 技能名称

## 概述

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

## 何时使用

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

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

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

前后代码比较

## 快速参考

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

## 实现

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

## 常见错误

出错内容 + 修复

## 现实世界影响（可选）

具体结果

Claude搜索优化（CSO）

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

1. 丰富描述字段

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

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

关键：描述 = 何时使用，非技能作用

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

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

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

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

# X 坏：总结工作流 - Claude可能遵循此而不是阅读技能
description: 当执行计划时使用 - 每个任务派发子代理，任务间进行代码审查

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

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

# V 好：仅触发条件
description: 当实施任何功能或错误修复时，在编写实施代码前使用

内容：

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

# X 坏：太抽象，模糊，不包括何时使用
description: 用于异步测试

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

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

# V 好：以“Use when...”开头，描述问题，无工作流
description: 当测试有竞争条件、时间依赖性或通过/失败不一致时使用

# V 好：技术特定技能，明确触发器
description: 当使用React Router并处理身份验证重定向时使用

2. 关键词覆盖

使用Claude会搜索的词语：

• 错误消息：“Hook timed out”, “ENOTEMPTY”, “race condition”
• 症状：“flaky”, “hanging”, “zombie”, “pollution”
• 同义词：“timeout/hang/freeze”, “cleanup/teardown/afterEach”
• 工具：实际命令、库名、文件类型

3. 描述性命名

使用主动语态，动词优先：

• V creating-skills 非 skill-creation
• V condition-based-waiting 非 async-test-helpers

4. 令牌效率（关键）

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

目标字数：

• 入门工作流：每个<150字
• 频繁加载技能：总数<200字
• 其他技能：<500字（仍需简洁）

技术：

将细节移到工具帮助：

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

# V 好：参考 --help
search-conversations 支持多种模式和过滤器。运行 --help 获取细节。

使用交叉引用：

# X 坏：重复工作流细节

搜索时，使用模板派发子代理...
[20行重复指令]

# V 好：引用其他技能

始终使用子代理（50-100x上下文节省）。必需：使用 [其他技能名称] 用于工作流。

压缩示例：

# X 坏：冗长示例（42字）

您的人类伙伴：“我们以前在React Router中如何处理身份验证错误？”
您：我将搜索过去对话中的React Router身份验证模式。
[派发子代理，搜索查询：“React Router authentication error handling 401”]

# V 好：最小示例（20字）

伙伴：“在React Router中如何处理身份验证错误？”
您：搜索中...
[派发子代理 -> 合成]

消除冗余：

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

验证：

wc -w skills/路径/SKILL.md
# 入门工作流：目标每个<150
# 其他频繁加载：目标总数<200

按您做或核心洞察命名：

• V condition-based-waiting > async-test-helpers
• V using-skills 非 skill-usage
• V flatten-with-flags > data-structure-refactoring
• V root-cause-tracing > debugging-techniques

动名词（-ing）适用于过程：

• creating-skills, testing-skills, debugging-with-logs
• 主动，描述您采取的行动

4. 交叉引用其他技能

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

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

• V 好：**必需子技能：** 使用 tdd
• V 好：**必需背景：** 您必须理解调试
• X 坏：参见 skills/testing/test-driven-development（不清楚是否必需）
• X 坏：@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技能解释为什么这重要。相同原则适用于文档。

测试所有技能类型

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

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

示例： TDD, verification-before-completion, designing-before-coding

测试用：

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

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

技术技能（如何指导）

示例： condition-based-waiting, root-cause-tracing, defensive-programming

测试用：

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

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

模式技能（心理模型）

示例： reducing-complexity, information-hiding concepts

测试用：

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

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

参考技能（文档/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 了解完整测试方法论：

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

反模式

X 叙述示例

“在会话2025-10-03，我们发现空projectDir导致…” 为什么坏： 太具体，不可重用

X 多语言稀释

example-js.js, example-py.py, example-go.go 为什么坏： 平庸质量，维护负担

X 流程图中的代码

step1 [label=“import fs”];
step2 [label=“read file”];

为什么坏： 无法复制粘贴，难读

X 通用标签

helper1, helper2, step3, pattern4 为什么坏： 标签应有语义意义

停止：移动到下一个技能前

编写任何技能后，您必须停止并完成部署过程。

不要：

• 批量创建多个技能而不测试每个
• 当前技能验证前移动到下一个
• 跳过测试因为“批量更高效”

下面的部署清单对每个技能是强制性的。

部署未测试技能 = 部署未测试代码。这是质量标准违规。

技能创建清单（TDD适应）

重要：使用TodoWrite为下面每个清单项创建待办事项。

RED阶段 - 编写失败测试：

• [ ] 创建压力场景（纪律技能3+组合压力）
• [ ] 运行场景无技能 - 逐字记录基线行为
• [ ] 识别合理化/失败模式

GREEN阶段 - 编写最小技能：

• [ ] 名称仅使用字母、数字、连字符（无括号/特殊字符）
• [ ] YAML frontmatter，仅名称和描述（最大1024字符）
• [ ] 描述以“Use when…”开头，包括具体触发器/症状
• [ ] 描述以第三人称编写
• [ ] 整个关键词用于搜索（错误，症状，工具）
• [ ] 清晰概述与核心原则
• [ ] 解决RED中识别的特定基线失败
• [ ] 代码内联或链接到单独文件
• [ ] 一个优秀示例（非多语言）
• [ ] 运行场景有技能 - 验证代理现在遵守

REFACTOR阶段 - 关闭漏洞：

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

质量检查：

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

部署：

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

发现工作流

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

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

优化此流程 - 尽早并经常放置可搜索术语。

底线

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

相同铁律：没有先失败测试，没有技能。 相同循环：RED（基线） -> GREEN（编写技能） -> REFACTOR（关闭漏洞）。 相同好处：更好质量，更少惊喜，防弹结果。

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

写作风格指南

编写技能内容时，遵循这些散文指南以清晰、直接沟通：

语音和语调

• 像人类说话一样写作。避免企业行话和营销废话。
• 自信和直接。避免软化短语如“我认为，” “可能，” 或 “可以。”
• 使用主动语态代替被动语态。
• 使用积极措辞 - 说某物是什么而不是它不是什么。
• 当针对外部受众时，多说“你”而不是“我们”。
• 使用收缩如“我会，” “不会，” 和 “不能” 以更温暖语调。

具体性和证据

• 用事实和数据具体，而不是模糊最高级。
• 用具体示例或指标支持主张。
• 突出客户和社区成员超过公司成就。
• 使用现实、基于产品的示例代替代码中的 foo/bar/baz。
• 使内容具体、视觉和可证伪。

标题创建

• 在标题中做出承诺，让读者知道如果他们点击会得到什么。
• 挖掘观众持有的争议点并用数据支持它们（明智使用，避免点击诱饵）。
• 分享独特有帮助的内容，让读者在生活有意义方面更好。
• 避免模糊标题如“我对XYZ的想法。”标题应是意见或可分享事实。
• 先写占位标题，完成内容，然后花时间迭代标题。

禁用词（替换为）

• a bit -> 移除
• a little -> 移除
• actually/actual -> 移除
• agile -> 移除
• arguably -> 移除
• assistance -> “帮助”
• attempt -> “尝试”
• battle tested -> 移除
• best practices -> “已验证方法”
• blazing fast/lightning fast -> “构建XX%更快”
• business logic -> 移除
• cognitive load -> 移除
• commence -> “开始”
• delve -> “深入”
• disrupt/disruptive -> 移除
• facilitate -> “帮助”或“使容易”
• game-changing -> 具体好处
• great -> 移除或具体
• implement -> “做”
• individual -> “男人”或“女人”
• initial -> “首先”
• innovative -> 移除
• just -> 移除
• leverage -> “使用”
• mission-critical -> “重要”
• modern/modernized -> 移除
• numerous -> “许多”
• out of the box -> 移除
• performant -> “快速可靠”
• pretty/quite/rather/really/very -> 移除
• referred to as -> “称为”
• remainder -> “其余”
• robust -> “强大”
• seamless/seamlessly -> “自动”
• sufficient -> “足够”
• that -> 经常可移除，上下文依赖
• thing -> 具体
• utilize -> “使用”
• webinar -> “在线活动”

禁用短语

• I think/I believe/we believe -> 直接陈述
• it seems -> 移除
• sort of/kind of -> 移除
• pretty much -> 移除
• a lot/a little -> 具体
• By developers, for developers -> 移除
• We can't wait to see what you'll build -> 移除
• We obsess over ___ -> 移除
• The future of ___ -> 移除
• We're excited -> “我们期待”
• Today, we're excited to -> 移除

避免LLM模式

• 用分号、逗号或句子中断替换em破折号（—）。
• 避免以“Great question!”, “You’re right!”, 或 “Let me help you.” 开头响应。
• 不使用短语如“Let’s dive into…”
• 跳过陈词滥调介绍如“In today’s fast-paced digital world”或“In the ever-evolving landscape of.”
• 避免短语如“it’s not just [x], it’s [y].”
• 避免自我引用免责声明如“As an AI”或“I’m here to help you with.”
• 不使用高中作文结尾：“In conclusion,” “Overall,” 或 “To summarize.”
• 避免以“Hope this helps!”或类似结尾。
• 避免过度使用过渡词如“Furthermore,” “Additionally,” 或 “Moreover.”
• 用直接陈述替换“In conclusion”。
• 避免对冲词：“might,” “perhaps,” “potentially”除非不确定性真实。
• 不对冲短语堆叠：“may potentially,” “it’s important to note that.”
• 不创建完美对称段落或列表以“Firstly… Secondly…”开头
• 避免标题大小写标题；偏好句子大小写。
• 复制粘贴时移除Unicode伪影：智能引号（”），em破折号，非断空格。
• 使用 `` 代替 ‘’。
• 删除空引用占位符如“[1]”无实际源。

标点和格式

• 一致使用牛津逗号。
• 稀疏使用感叹号。
• 句子可以以“But”和“And”开头 - 但不过度使用。
• 为清晰，可能时使用句号代替逗号。

---

内存协议（强制）

开始前： 读取 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设中断：如果不在内存中，它没有发生。