Menú
当创建新 skill、编辑现有 skill，或在部署前验证 skill 是否有效时使用
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional 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 也遵循它。这是同样的纪律应用于文档。