Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jnMetaCode/superpowers-zh --skill writing-skillsThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
| name | writing-skills |
| description | 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用 |
| version | 1.0.0 |
| license | MIT |
| metadata | {"hermes":{"tags":["skills","documentation"]}} |
编写技能就是将测试驱动开发应用于流程文档。
个人技能存放在智能体特定的目录中（Claude Code 用 ~/.claude/skills，Codex 用 ~/.agents/skills/）
你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。
核心原则： 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
必需背景： 在使用此技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。
官方指南： Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。
技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
技能是： 可复用的技术、模式、工具、参考指南
技能不是： 关于你某次如何解决问题的叙事
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 带子智能体的压力场景 |
| 生产代码 | 技能文档（SKILL.md） |
| 测试失败（红） | 智能体在没有技能时违反规则（基线） |
| 测试通过（绿） | 智能体在有技能时遵守规则 |
| 重构 | 在保持合规的同时堵住漏洞 |
| 先写测试 | 在编写技能之前先运行基线场景 |
| 观察失败 | 记录智能体使用的确切合理化借口 |
| 最小代码 | 编写针对那些具体违规行为的技能 |
| 观察通过 | 验证智能体现在遵守规则 |
| 重构循环 | 发现新的合理化借口 → 堵住 → 重新验证 |
整个技能创建过程遵循红-绿-重构。
创建条件：
不要创建：
有具体步骤的方法（condition-based-waiting、root-cause-tracing）
思考问题的方式（flatten-with-flags、test-invariants）
API 文档、语法指南、工具文档（office docs）
skills/
skill-name/
SKILL.md # 主参考文档（必需）
supporting-file.* # 仅在需要时
扁平命名空间 - 所有技能在一个可搜索的命名空间中
分离文件的情况：
保持内联：
Frontmatter（YAML）：
name 和 description（完整支持字段参见 agentskills.io/specification）name：只使用字母、数字和连字符（不要用括号、特殊字符）description：第三人称，仅描述何时使用（不是做什么）
---
name: Skill-Name-With-Hyphens
description: Use when [具体的触发条件和症状]
---
# 技能名称
## 概述
这是什么？用 1-2 句话说明核心原则。
## 何时使用
[如果决策不明显，使用小型内联流程图]
症状和用例的要点列表
不适用的场景
## 核心模式（技术/模式类）
前后代码对比
## 快速参考
用于快速浏览常见操作的表格或要点
## 实现
简单模式内联代码
大量参考或可复用工具链接到文件
## 常见错误
常见问题 + 修复方法
## 实际效果（可选）
具体结果
发现至关重要： 未来的 Claude 需要找到你的技能
目的： Claude 读取描述来决定为当前任务加载哪些技能。让它能回答："我现在应该读这个技能吗？"
格式： 以"Use when..."开头，聚焦于触发条件
关键：描述 = 何时使用，不是技能做什么
描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。
为什么这很重要： 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着"任务间进行代码审查"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。
当描述改为仅"在当前会话中执行包含独立任务的实现计划时使用"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。
陷阱： 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。
# 错误：总结了工作流 - Claude 可能会跟随描述而非阅读技能
description: Use when executing plans - dispatches subagent per task with code review between tasks
# 错误：流程细节太多
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# 正确：只有触发条件，无工作流摘要
description: Use when executing implementation plans with independent tasks in the current session
# 正确：仅触发条件
description: Use when implementing any feature or bugfix, before writing implementation
内容：
# 错误：太抽象、模糊，未包含何时使用
description: For async testing
# 错误：第一人称
description: I can help you with async tests when they're flaky
# 错误：提到了技术但技能并非该技术特定的
description: Use when tests use setTimeout/sleep and are flaky
# 正确：以"Use when"开头，描述问题，无工作流
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# 正确：技术特定的技能带有明确的触发条件
description: Use when using React Router and handling authentication redirects
使用 Claude 会搜索的词语：
使用主动语态，动词优先：
creating-skills 而非 skill-creationcondition-based-waiting 而非 async-test-helpers问题： getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。
目标字数：
技巧：
将细节移到工具帮助中：
# 错误：在 SKILL.md 中列出所有参数
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# 正确：引用 --help
search-conversations 支持多种模式和过滤器。运行 --help 查看详情。
使用交叉引用：
# 错误：重复工作流细节
搜索时，用模板分派子智能体……
[20 行重复的说明]
# 正确：引用其他技能
始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。
压缩示例：
# 错误：冗长的示例（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-helpersusing-skills 而非 skill-usageflatten-with-flags > data-structure-refactoringroot-cause-tracing > debugging-techniques动名词（-ing）适合描述流程：
creating-skills、testing-skills、debugging-with-logs编写引用其他技能的文档时：
仅使用技能名称，带有明确的必需标记：
**必需子技能：** 使用 superpowers:test-driven-development**必需背景：** 你必须理解 superpowers:systematic-debugging参见 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="否"];
}
仅在以下情况使用流程图：
绝不使用流程图用于：
参见 @graphviz-conventions.dot 了解 graphviz 样式规则。
为你的搭档可视化： 使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：
./render-graphs.js ../some-skill # 每个图表分别渲染
./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG
一个优秀的示例胜过多个平庸的
选择最相关的语言：
好的示例：
不要：
你擅长语言移植——一个优秀的示例就够了。
defense-in-depth/
SKILL.md # 所有内容内联
适用场景：所有内容都能放下，无需大量参考
condition-based-waiting/
SKILL.md # 概述 + 模式
example.ts # 可适配的工作代码
适用场景：工具是可复用的代码，不只是叙述
pptx/
SKILL.md # 概述 + 工作流
pptxgenjs.md # 600 行 API 参考
ooxml.md # 500 行 XML 结构
scripts/ # 可执行工具
适用场景：参考资料太多无法内联
没有失败的测试就不写技能
这适用于新技能和对现有技能的编辑。
先写技能再测试？删掉它。重新开始。 编辑技能不测试？同样违规。
无例外：
必需背景： superpowers:test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
不同类型的技能需要不同的测试方法：
例如： TDD、完成前验证、编码前设计
测试方式：
成功标准： 智能体在最大压力下遵循规则
例如： condition-based-waiting、root-cause-tracing、defensive-programming
测试方式：
成功标准： 智能体成功将技术应用于新场景
例如： reducing-complexity、information-hiding 概念
测试方式：
成功标准： 智能体正确识别何时/如何应用模式
例如： API 文档、命令参考、库指南
测试方式：
成功标准： 智能体找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "技能显然很清晰" | 对你清晰 ≠ 对其他智能体清晰。测试它。 |
| "这只是参考资料" | 参考资料可能有遗漏、不清楚的地方。测试检索。 |
| "测试太过了" | 未测试的技能总有问题。15 分钟测试省下数小时。 |
| "有问题再测试" | 问题 = 智能体无法使用技能。在部署前测试。 |
| "测试太繁琐" | 测试比在生产中调试坏技能少繁琐得多。 |
| "我有信心它很好" | 过度自信保证出问题。无论如何都要测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的技能比后面修复浪费更多时间。 |
以上所有都意味着：部署前测试。无例外。
在写指导内容之前，先给基线失败归类。能让某一类失败变得无懈可击的形式，用在另一类上会可测量地反噬。
| 基线失败 | 正确的形式 | 错误的形式 |
|---|---|---|
| 压力之下跳过/违反规则（明知故犯） | 禁令 + 合理化借口表 + 红线（见下方"让技能经受住合理化的考验"） | 软性建议（"优先……"、"考虑……"） |
| 遵守了，但产出的形状不对（提示词臃肿、结论被埋、复述规格） | 正面配方或契约：直接说明产出是什么 —— 它由哪些部分组成、按什么顺序 | 禁令清单（"不要复述"、"绝不旁白"） |
| 在他们本来就会产出的东西里漏掉了必需元素 | 结构性手段：在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |
| 行为应当取决于某个条件 | 挂在可观察谓词上的条件句（"如果简报存在，就引用它"） | 无条件规则 + 一堆例外条款 |
为什么禁令在"塑形"类问题上会反噬： 在存在竞争性激励时（比如"让提示词自包含"），智能体会跟"不要 X"讨价还价。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显多于配方组（两组分布完全分离），甚至比"完全不给指导"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但永远不要把禁令当默认选择。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。
无论你选哪种形式，都适用的规则：
执行纪律的技能（如 TDD）需要抵抗合理化。智能体很聪明，在压力下会找到漏洞。
心理学说明： 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。
不要只是陈述规则——禁止具体的变通方法：
```markdown 先写代码再写测试？删掉它。 ``` ```markdown 先写代码再写测试？删掉它。重新开始。无例外：
</Good>
### 应对"精神 vs 字面"的辩论
在前面加入基础原则：
```markdown
**违反规则的字面意思就是违反规则的精神。**
这切断了整类"我遵循的是精神"的合理化借口。
从基线测试中捕获合理化借口（参见下方测试章节）。智能体使用的每个借口都进入表中：
| 借口 | 现实 |
|------|------|
| "太简单不值得测试" | 简单的代码也会出错。测试只需 30 秒。 |
| "我后面再测试" | 测试立即通过什么也证明不了。 |
| "后写测试效果一样" | 后写测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
让智能体容易自查是否在合理化：
## 红线 - 停下来重新开始
- 先写代码再写测试
- "我已经手动测试过了"
- "后写测试效果一样"
- "重要的是精神不是仪式"
- "这个情况不同，因为……"
**以上所有都意味着：删除代码。用 TDD 重新开始。**
在描述中添加：你即将违反规则时的症状：
description: use when implementing any feature or bugfix, before writing implementation code
遵循 TDD 循环：
在没有技能的情况下运行压力场景。逐字记录行为：
这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。
编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。
用技能运行相同的场景。智能体应该现在遵守。
智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。
完整的压力场景是最后一道关卡，但它每轮迭代都又慢又贵。先用微型测试验证措辞本身：
微型测试验证的是措辞；对纪律执行类技能，它不能替代压力场景。
测试方法论： 参见 @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 为什么不好： 标签应有语义意义
编写任何技能后，你必须停下来完成部署流程。
不要：
下面的部署清单对每个技能都是强制性的。
部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。
重要：使用 TodoWrite 为下面的每个清单项创建待办。
红色阶段 - 编写失败的测试：
绿色阶段 - 编写最小技能：
name 和 description 字段（最多 1024 字符；参见 spec）重构阶段 - 堵住漏洞：
质量检查：
部署：
未来的 Claude 如何找到你的技能：
为此流程优化 - 把可搜索的术语放在前面和各处。
Based on SOC occupation classification
