⚡

编写技能Skill writing-skills

此技能用于在创建、编辑和验证技能文档时应用测试驱动开发（TDD）方法，确保技能的质量和可重用性。关键词包括技能创建、TDD、测试驱动开发、文档测试、质量保证、软件开发、技能编写、过程文档。

测试 0 次安装 0 次浏览 更新于 3/21/2026

name: writing-skills 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.*     # 仅在需要时

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

单独文件用于：

  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 [specific triggering conditions and symptoms]
---

# 技能名称

## 概述
这是什么？核心原则用 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 且不稳定时使用

# ✅ 好：以“Use when...”开头，描述问题，无工作流
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 上下文）。必需：使用 [other-skill-name] 作为工作流。

压缩示例：

# ❌ 差：详细示例（42 词）
您的人类伙伴：“我们之前如何在 React Router 中处理认证错误？”
您：我将搜索过去对话中 React Router 认证模式。
[派生子代理带搜索查询：“React Router 认证错误处理 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. 交叉引用其他技能

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

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

  • ✅ 好：**REQUIRED SUB-SKILL:** 使用 superpowers:test-driven-development
  • ✅ 好：**REQUIRED BACKGROUND:** 您必须理解 superpowers:systematic-debugging
  • ❌ 差：见 skills/testing/test-driven-development（不清楚是否必需）
  • ❌ 差：@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）

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

流程图使用

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

好示例：

  • 完整且可运行
  • 良好注释解释 WHY
  • 来自真实场景
  • 清楚显示模式
  • 准备好适配（非通用模板）

不要：

  • 用 5+ 语言实现
  • 创建填空模板
  • 编写 contrived 示例

您擅长移植 - 一个伟大示例就足够。

文件组织

自包含技能

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 等人，2025）关于权威、承诺、稀缺性、社会认同和统一原则。

明确关闭每个漏洞

不要仅陈述规则 - 禁止特定变通方法：

<差>

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

</差>

<好>

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

**无例外：**
- 不要将其作为“参考”保留
- 不要编写测试时“适配”它
- 不要看它
- 删除意味着删除

</好>

处理“精神与文字”争论

早期添加基本原则：

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

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

构建合理化表

从基线测试捕获合理化（见下面测试部分）。代理使用的每个借口进入表：

| 借口 | 现实 |
|--------|---------|
| “太简单不需要测试” | 简单代码会坏。测试花费 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 字符）
  • [ ] 描述以“Use when…”开头并包括具体触发因素/症状
  • [ ] 描述以第三人称编写
  • [ ] 关键词贯穿搜索（错误、症状、工具）
  • [ ] 清晰概述带核心原则
  • [ ] 针对 RED 中识别的特定基线失败
  • [ ] 代码内联或链接到单独文件
  • [ ] 一个优秀示例（非多语言）
  • [ ] 运行场景带技能 - 验证代理现在遵守

REFACTOR 阶段 - 关闭漏洞：

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

质量检查：

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

部署：

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

发现工作流

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

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

为此流程优化 - 早期和经常放入可搜索术语。

底线

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

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

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