القائمة
当创建新 skill、编辑现有 skill，或在部署前验证 skill 是否有效时使用
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
在进行任何创造性工作之前，你必须使用此 skill - 创建功能、构建组件、添加功能或修改行为。在实现之前探索用户意图、需求和设计。
当面对 2 个以上可在无共享状态或顺序依赖下处理的独立任务时使用
当你有一个书面实现计划，需要在带有 review 检查点的独立会话中执行时使用
当实现完成、所有测试通过、且你需要决定如何集成工作时使用 - 通过为合并、PR 或清理呈现结构化选项来指导开发工作的完成
当收到代码审查反馈时使用，在实现建议之前，尤其是当反馈看似不清或在技术上存疑时 - 需要技术严谨性和验证，而非表演性附和或盲目实现
当完成任务、实现主要功能或合并之前使用，以验证工作满足需求
| name | writing-skills |
| description | 当创建新 skill、编辑现有 skill，或在部署前验证 skill 是否有效时使用 |
编写 skills 就是把 TDD 应用于流程文档。
个人 skill 存放在你的运行时 skills 目录中——关于你所用运行时上的路径，参见 claude-code-tools.md、codex-tools.md、copilot-tools.md 或 gemini-tools.md。Codex、Copilot CLI 和 Gemini CLI 还都把 ~/.agents/skills/ 视为跨运行时的别名。
你编写测试用例（带 subagent 的压力场景），看它们失败（基线行为），编写 skill（文档），看测试通过（agent 合规），然后重构（关闭漏洞）。
核心原则： 如果你没有看到一个 agent 在没有这个 skill 时失败，你就不知道这个 skill 是否教对了东西。
必需的前置知识： 在使用本 skill 之前，你必须理解 superpowers:test-driven-development。那个 skill 定义了基本的 RED-GREEN-REFACTOR 循环。本 skill 将 TDD 适配到文档。
官方指南： 关于 Anthropic 官方的 skill 编写最佳实践，参见 anthropic-best-practices.md。该文档提供了补充本 skill 中以 TDD 为核心的方法的额外模式和指南。
一个 skill 是经过验证的技术、模式或工具的参考指南。Skills 帮助未来的 agent 找到并应用有效的方法。
Skills 是： 可复用的技术、模式、工具、参考指南
Skills 不是： 关于你某次如何解决问题的叙述
| TDD 概念 | Skill 创建 |
|---|---|
| 测试用例 | 带 subagent 的压力场景 |
| 生产代码 | Skill 文档（SKILL.md） |
| 测试失败（RED） | Agent 在没有 skill 时违反规则（基线） |
| 测试通过（GREEN） | Agent 在 skill 存在时合规 |
| 重构 | 在保持合规的同时关闭漏洞 |
| 先写测试 | 在编写 skill 之前运行基线场景 |
| 看它失败 | 文档化 agent 使用的确切合理化借口 |
| 最少代码 | 编写针对那些特定违规的 skill |
| 看它通过 | 验证 agent 现在合规 |
| 重构循环 | 找到新的合理化借口 → 堵住 → 重新验证 |
整个 skill 创建过程遵循 RED-GREEN-REFACTOR。
在这些情况下创建：
不要为这些创建：
有步骤可遵循的具体方法（condition-based-waiting、root-cause-tracing）
思考问题的方式（flatten-with-flags、test-invariants）
API 文档、语法指南、工具文档（office 文档）
skills/
skill-name/
SKILL.md # 主参考（必需）
supporting-file.* # 仅在需要时
扁平命名空间 - 所有 skill 处于一个可搜索的命名空间中
为以下情况使用单独文件：
保持内联：
Frontmatter（YAML）：
name 和 description（所有支持的字段见 agentskills.io/specification）name：仅使用字母、数字和连字符（不要括号、特殊字符）description：第三人称，仅描述何时使用（不是它做什么）
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# Skill Name
## Overview
这是什么？1-2 句话的核心原则。
## When to Use
[如果决策不明显，放一个小的内联流程图]
带症状和用例的列表
何时不使用
## Core Pattern（用于技术/模式）
修改前/后代码对比
## Quick Reference
用于快速浏览常见操作的表格或列表
## Implementation
简单模式的内联代码
重型参考或可复用工具链接到文件
## Common Mistakes
出了什么问题 + 修复
## Real-World Impact（可选）
具体结果
对发现至关重要： 未来的 agent 需要能找到你的 skill
目的： 你的 agent 阅读 description 来决定为给定任务加载哪些 skill。让它能回答："我现在应该读这个 skill 吗？"
格式： 以 "Use when..." 开头以聚焦触发条件
关键：description = 何时使用，而不是 skill 做什么
description 应当只描述触发条件。不要在 description 中概括 skill 的流程或工作流。
为什么这很重要： 测试揭示，当 description 概括了 skill 的工作流时，agent 可能会跟随 description 而不是阅读完整的 skill 内容。一个写着"任务之间的 code review"的 description 导致一个 agent 只做了一次 review，尽管 skill 的流程图清楚地显示了两次 review（先规范合规，再代码质量）。
当 description 改为仅"Use when executing implementation plans with independent tasks"（没有工作流概括）时，agent 正确地阅读了流程图并遵循了两阶段 review 流程。
陷阱： 概括工作流的 description 创造了一条 agent 会走的捷径。skill 的正文变成了 agent 跳过的文档。
# ❌ 坏：概括了工作流——agent 可能跟随它而不是阅读 skill
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 code
内容：
# ❌ 坏：太抽象、含糊，不包含何时使用
description: For async testing
# ❌ 坏：第一人称
description: I can help you with async tests when they're flaky
# ❌ 坏：提到了技术但 skill 并不特定于它
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
# ✅ 好：技术特定的 skill 带明确触发器
description: Use when using React Router and handling authentication redirects
使用 agent 会搜索的词：
使用主动语态，动词在前：
creating-skills 而不是 skill-creationcondition-based-waiting 而不是 async-test-helpers问题： getting-started 和频繁被引用的 skill 会加载进每一次对话。每个 token 都很重要。
目标字数：
技术：
把细节移到工具的 help 中：
# ❌ 坏：在 SKILL.md 中文档化所有标志
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# ✅ 好：引用 --help
search-conversations supports multiple modes and filters. Run --help for details.
使用交叉引用：
# ❌ 坏：重复工作流细节
When searching, dispatch subagent with template...
[20 lines of repeated instructions]
# ✅ 好：引用其他 skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
压缩示例：
# ❌ 坏：冗长示例（42 词）
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]
# ✅ 好：最简示例（20 词）
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
消除冗余：
验证：
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当编写引用其他 skill 的文档时：
只使用 skill 名称，带明确的要求标记：
**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debuggingSee skills/testing/test-driven-development（不清楚是否必需）@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）为什么不用 @ 链接： @ 语法会立即强制加载文件，在你需要它们之前就消耗了 20 万以上的上下文。
digraph when_flowchart {
"需要展示信息？" [shape=diamond];
"我可能走错的决策？" [shape=diamond];
"使用 markdown" [shape=box];
"小的内联流程图" [shape=box];
"需要展示信息？" -> "我可能走错的决策？" [label="是"];
"我可能走错的决策？" -> "小的内联流程图" [label="是"];
"我可能走错的决策？" -> "使用 markdown" [label="否"];
}
仅在以下情况使用流程图：
绝不在以下情况使用流程图：
关于 graphviz 风格规则，参见本目录下的 graphviz-conventions.dot。
为你的 human partner 可视化： 使用本目录下的 render-graphs.js 把一个 skill 的流程图渲染成 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/ # 可执行工具
何时：参考材料太大无法内联
没有先写出失败的测试，就不写 skill
这适用于新 skill 以及对现有 skill 的编辑。
先写 skill 再测试？删掉它。从头来。 不测试就编辑 skill？同样的违规。
没有例外：
必需的前置知识： superpowers:test-driven-development skill 解释了为什么这很重要。同样的原则适用于文档。
不同 skill 类型需要不同的测试方法：
示例： TDD、verification-before-completion、designing-before-coding
测试方式：
成功标准： agent 在最大压力下遵循规则
示例： condition-based-waiting、root-cause-tracing、defensive-programming
测试方式：
成功标准： agent 成功地把技术应用到新场景
示例： reducing-complexity、information-hiding concepts
测试方式：
成功标准： agent 正确地识别何时/如何应用模式
示例： API 文档、命令参考、库指南
测试方式：
成功标准： agent 找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "skill 显然很清楚" | 对你清楚 ≠ 对其他 agent 清楚。测试它。 |
| "它只是个参考" | 参考也会有空白、不清晰的段落。测试检索。 |
| "测试是杀鸡用牛刀" | 未测试的 skill 有问题。总是如此。15 分钟测试省下数小时。 |
| "出现问题我再测" | 问题 = agent 用不了 skill。在部署前测试。 |
| "测试太繁琐" | 测试比在生产环境调试糟糕的 skill 更不繁琐。 |
| "我确信它是好的" | 过度自信必然带来问题。无论如何都要测。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测" | 部署未测试的 skill 会在之后花更多时间修复它。 |
以上全部意味着：在部署前测试。没有例外。
在编写指南之前，先对基线失败进行分类。能让一种失败类型刀枪不入的形式，在另一种失败上会明显适得其反。
| 基线失败 | 正确形式 | 错误形式 |
|---|---|---|
| 在压力下跳过/违反规则（明知故犯） | 禁令 + 合理化借口表 + 危险信号（见下面的加固） | 软指南（"prefer..."、"consider..."） |
| 合规了，但输出形状错误（臃肿的 prompt、被埋没的裁决、复述的规范） | 正面配方或契约：陈述输出是什么——它的各部分，按顺序 | 禁令列表（"不要复述"、"绝不叙述"） |
| 从它们已经产出的东西中遗漏了必需元素 | 结构性的：模板中一个 REQUIRED 字段或填写的槽位 | 靠近模板的散文提醒 |
| 行为应当取决于某个条件 | 以可观察谓词为键的条件（"如果简报存在，引用它"） | 无条件规则 + 豁免条款 |
为什么禁令在塑造问题上适得其反： 在相互竞争的激励下（"让 prompt 自包含"），agent 会和"不要 X"谈判。在 dispatch-prompt 指南的正面措辞对照测试中，禁令组产生的不想要内容明显多于配方组（分布完全分离），甚至比无指南对照组更糟——对你自己的案例做微测试，而不是假设，但绝不要默认就伸手拿禁令。配方没有留下任何谈判余地：输出要么匹配陈述的形状，要么不匹配。
无论你选哪种形式的规则：
强制纪律的 skill（如 TDD）需要抵抗合理化。Agent 很聪明，在压力下会寻找漏洞。
范围： 此工具箱用于纪律失败——一个知道规则却在压力下跳过它的 agent。对于错误形状的输出或遗漏的元素，基于禁令的加固会适得其反；改用"让形式匹配失败"中的形式。
心理学说明： 理解说服技术为什么有效，有助于你系统地应用它们。关于权威、承诺、稀缺、社会认同和共同体原则的研究基础（Cialdini, 2021; Meincke et al., 2025），见 persuasion-principles.md。
不要只陈述规则——禁止特定的变通方法：
```markdown 先写代码再写测试？删除它。 ``` ```markdown 先写代码再写测试？删除它。从头来。没有例外：
</Good>
### 应对"精神 vs 字面"的论调
尽早添加基础原则：
```markdown
**违反规则的字面意义，就是违反规则的精神。**
这切断了一整类"我遵循的是精神"的合理化借口。
从基线测试中捕获合理化借口（见下面的测试小节）。agent 做出的每一个借口都进表：
| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
让 agent 在合理化时易于自检：
## Red Flags - STOP and Start Over
- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."
**All of these mean: Delete code. Start over with TDD.**
注：上表中保留英文，因为这些是 skill 内部原文示例文本，用于展示表与列表的写法。
向 description 添加：你即将违规时的症状：
description: use when implementing any feature or bugfix, before writing implementation code
遵循 TDD 循环：
在没有 skill 的情况下用 subagent 运行压力场景。文档化确切行为：
这就是"看测试失败"——你必须在编写 skill 之前看到 agent 自然会做什么。
编写针对那些特定合理化借口的 skill。不要为假设性的情况添加额外内容。
用 skill 运行相同场景。Agent 现在应当合规。
agent 找到了新的合理化借口？添加明确的计数器。重新测试直到刀枪不入。
完整的压力场景运行是最终关卡，但每次迭代都很慢且昂贵。先用微测试验证措辞本身：
微测试验证措辞；对于纪律型 skill，它们不替代压力场景。
测试方法论： 完整的测试方法论见 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 为什么坏： 标签应当有语义含义
在编写任何 skill 之后，你必须停下并完成部署流程。
不要：
下面的部署清单对每个 skill 都是强制性的。
部署未测试的 skill = 部署未测试的代码。这是对质量标准的违反。
重要：为下面每一项清单创建一个 todo。
RED 阶段 - 写失败的测试：
GREEN 阶段 - 写最少的 Skill：
name 和 description 字段（最多 1024 字符；见 spec）REFACTOR 阶段 - 关闭漏洞：
质量检查：
部署：
未来的 agent 如何找到你的 skill：
为此流程优化——把可搜索的词放得早、放得多。
创建 skills 就是把 TDD 用于流程文档。
同样的铁律：没有先写失败的测试，就不写 skill。 同样的循环：RED（基线）→ GREEN（编写 skill）→ REFACTOR（关闭漏洞）。 同样的好处：更好的质量、更少的意外、刀枪不入的结果。
如果你为代码遵循 TDD，那就为 skills 也遵循它。这是同样的纪律应用于文档。