技能写作与测试指南Skill writing-skills

---

name: 技能写作与测试指南 description: 在创建新技能、编辑现有技能或部署前验证技能工作时使用 - 通过子代理测试在写作前应用测试驱动开发（TDD）到过程文档，迭代直到对抗合理化漏洞

写作技能

概述

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

个人技能写入 ~/.claude/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文档、语法指南、工具文档（Office文档）

目录结构

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

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

单独文件用于：

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

保持内联：

• 原则和概念
• 代码模式（< 50行）
• 其他一切

SKILL.md 结构

前端元数据（YAML）：

• 仅支持两个字段：name 和 description
• 最大1024字符总计
• name: 仅使用字母、数字和连字符（无括号、特殊字符）
• description: 第三人称，包括它做什么和何时使用它
  • 以“Use when…”开头以关注触发条件
  • 包括特定症状、情况和上下文
  • 如果可能，保持低于500字符

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
---

# 技能名称

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

## 何时使用
[如果决策非明显，小型内联流程图]

项目列表与症状和使用案例
何时不使用

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

## 快速参考
表格或项目用于扫描常见操作

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

## 常见错误
什么出错 + 修复

## 实际影响（可选）
具体结果

Claude 搜索优化（CSO）

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

1. 丰富描述字段

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

格式： 以“Use when…”开头以关注触发条件，然后解释它做什么

内容：

• 使用具体触发器、症状和情况，信号此技能适用
• 描述问题（竞争条件、不一致行为）而非语言特定症状（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
• ✅ testing-skills-with-subagents 非 subagent-skill-testing

4. 令牌效率（关键）

问题： getting-started 和 frequently-referenced 技能加载到每个对话。每个令牌计数。

目标词数：

• getting-started 工作流：每个 <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
# getting-started 工作流：目标每个 <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 {
    "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 vs B”决策

永不使用流程图用于：

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

参见 @graphviz-conventions.dot 以获取graphviz样式规则。

代码示例

一个优秀示例胜过许多平庸示例

选择最相关语言：

• 测试技术 → 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、验证前完成、设计前编码

测试用：

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

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

技术技能（如何指导）

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

测试用：

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

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

模式技能（心理模型）

示例： 减少复杂性、信息隐藏概念

测试用：

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

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

参考技能（文档/API）

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

测试用：

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

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

跳过测试的常见合理化

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

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

使技能对抗合理化漏洞

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

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

明确关闭每个漏洞

不要只陈述规则 - 禁止特定变通：

<坏>

在测试前编写代码？删除它。

</坏>

<好>

在测试前编写代码？删除它。重新开始。

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

</好>

解决“精神与文字”争论

早期添加基础原则：

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

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

构建合理化表

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

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

创建红旗列表

使代理在合理时自我检查容易：

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

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

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

更新CSO以获取违规症状

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

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

技能的RED-GREEN-REFACTOR

遵循TDD循环：

RED：编写失败测试（基线）

运行压力场景与子代理没有技能。记录确切行为：

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

这是“观看测试失败” - 您必须在编写技能之前看到代理自然做什么。

GREEN：编写最小技能

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

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

REFACTOR：关闭漏洞

代理找到新合理化？添加明确反驳。重新测试直到对抗漏洞。

必需子技能： 使用 superpowers:testing-skills-with-subagents 以获取完整测试方法：

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

反模式

❌ 叙述示例

“在会话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，为技能遵循它。这是应用于文档的相同纪律。