Menu
当需要创建新 skill、编辑现有 skill，或在部署前验证 skill 效果时必须使用
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
在开展任何创造性工作之前必须使用：创建功能、构建组件、添加能力或修改行为。在动手实现前，先探索用户意图、需求并制定设计。
当同时面对 2 个及以上相互独立、无共享状态且无顺序依赖的任务时必须使用本技能
当需要在一个独立会话中执行已撰写的实现计划，并通过检查点进行复核时必须使用
当实现完成、所有测试通过且需要决定如何集成工作时必须使用——通过呈现结构化的本地合并、创建 PR 或清理工作树等选项，指导开发工作的收尾
当收到代码审查反馈、准备采纳建议前必须使用，尤其当反馈表述不清或技术上可疑时——要求技术严谨与验证，禁止表面附和或盲目执行
当完成任务、实现主要功能或在合并前需要验证工作是否符合要求时必须使用
| name | writing-skills |
| description | 当需要创建新 skill、编辑现有 skill，或在部署前验证 skill 效果时必须使用 |
编写 skill 就是将测试驱动开发（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 是针对已验证技术、模式或工具的参考指南。skill 帮助未来的 agent 找到并应用有效的方法。
skill 是： 可复用的技术、模式、工具、参考指南
skill 不是： 关于你曾经如何解决某个问题的叙事
| TDD 概念 | Skill 创建 |
|---|---|
| 测试用例 | 使用 subagent 的施压场景 |
| 生产代码 | Skill 文档（SKILL.md） |
| 测试失败（RED） | 在没有 skill 时 agent 违反规则（基线） |
| 测试通过（GREEN） | 有 skill 时 agent 遵守规则 |
| 重构 | 在保持合规的同时堵住漏洞 |
| 先写测试 | 在编写 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 # Main reference (required)
supporting-file.* # Only if needed
扁平命名空间 — 所有 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
What is this? Core principle in 1-2 sentences.
## When to Use
[Small inline flowchart IF decision non-obvious]
Bullet list with SYMPTOMS and use cases
When NOT to use
## Core Pattern (for techniques/patterns)
Before/after code comparison
## Quick Reference
Table or bullets for scanning common operations
## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools
## Common Mistakes
What goes wrong + fixes
## Real-World Impact (optional)
Concrete results
发现至关重要： 未来的 agent 需要找到你的 skill
目的： 你的 agent 会读取 description 来决定为当前任务加载哪些 skill。让它能回答：“我现在应该读这个 skill 吗？”
格式： 以 "Use when..." 开头，聚焦触发条件
关键：Description = 何时使用，而不是 Skill 做什么
description 只应描述触发条件。不要在 description 中总结 skill 的流程或工作流。
原因： 测试发现，当 description 总结了 skill 的工作流时，agent 可能会直接按 description 行事，而不是阅读完整的 skill 内容。一条写着 "code review between tasks" 的 description 导致某个 agent 只做了一次审查，尽管该 skill 的流程图清楚地显示应进行两次审查（先 spec 合规性，再代码质量）。
当 description 改为 "Use when executing implementation plans with independent tasks"（不总结工作流）后，agent 正确地阅读了流程图，并遵循了两阶段审查流程。
陷阱： 总结工作流的 description 会成为 agent 走捷径的依据。skill 正文就会变成被 agent 跳过的文档。
# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code
内容：
# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing
# ❌ BAD: First person
description: I can help you with async tests when they're flaky
# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky
# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects
使用 agent 可能会搜索的词：
使用主动语态，动词开头：
creating-skills，不用 skill-creationcondition-based-waiting，不用 async-test-helpers问题： getting-started 和频繁引用的 skill 会加载到每一次对话中。每个 token 都很重要。
目标字数：
技巧：
将细节移到工具帮助中：
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
使用交叉引用：
# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]
# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
压缩示例：
# ❌ BAD: Verbose example (42 words)
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"]
# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
消除冗余：
验证：
wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total
根据你做什么或核心洞察来命名：
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（强制加载，浪费上下文）为什么不要用 @ 链接： @ 语法会立即强制加载文件，在需要之前就消耗 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"];
}
仅在以下情况使用流程图：
不要在以下情况使用流程图：
本目录中的 graphviz-conventions.dot 包含 graphviz 样式规则。
为人类伙伴可视化： 使用本目录中的 render-graphs.js 将 skill 的流程图渲染为 SVG：
./render-graphs.js ../some-skill # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG
一个优秀的示例胜过多个平庸的示例
选择最相关的语言：
好的示例：
不要：
你很擅长移植——一个出色的示例就够了。
defense-in-depth/
SKILL.md # Everything inline
何时：所有内容都能容纳，无需大量参考资料
condition-based-waiting/
SKILL.md # Overview + patterns
example.ts # Working helpers to adapt
何时：工具是可复用代码，而不只是叙述
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable tools
何时：参考资料太多，不适合内联
NO SKILL WITHOUT A FAILING TEST FIRST
这适用于新 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 概念
测试方法：
成功标准： agent 能正确识别何时/如何应用模式
示例： API 文档、命令参考、库指南
测试方法：
成功标准： agent 能找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "这个 skill obviously 很清楚" | 对你清楚 ≠ 对其他 agent 清楚。测试它。 |
| "这只是参考资料" | 参考资料也可能有缺口、有不清楚的部分。测试检索。 |
| "测试太过了" | 未测试的 skill 总是有问题。15 分钟测试能节省数小时。 |
| "有问题我再测试" | 问题 = agent 无法使用 skill。在部署前测试。 |
| "测试太繁琐" | 测试比在生产环境中调试糟糕的 skill 要轻松。 |
| "我确信它很好" | 过度自信必然导致问题。还是要测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的 skill 会在之后浪费更多时间修复。 |
所有这些说法的意思都是：部署前必须测试。没有例外。
在编写指导之前，先对基线失败进行分类。能防范某一种失败类型的形式，对另一种失败类型可能会明显适得其反。
| 基线失败 | 正确形式 | 错误形式 |
|---|---|---|
| 在压力下跳过/违反规则（明知故犯） | 禁止条款 + 合理化理由表 + 红旗信号（见下方的 Bulletproofing） | 软性指导（"prefer..."、"consider..."） |
| 遵守了，但输出形状错误（提示臃肿、结论被埋没、重复 spec） | 正面配方或契约：说明输出是什么——按顺序列出其组成部分 | 禁止清单（"don't restate"、"never narrate"） |
| 遗漏了已生成内容中的必要元素 | 结构性：在他们填写的模板中设置 REQUIRED 字段或槽位 | 模板附近的文字提醒 |
| 行为应取决于某个条件 | 基于可观察谓词的条件（"if the brief exists, reference it"） | 无条件规则 + 豁免条款 |
为什么禁止条款在塑造型问题上适得其反： 在竞争性激励（“让提示自包含”）下，agent 会与 "don't X" 进行协商。在针对 dispatch-prompt 指导的措辞对比测试中，禁止条款组明显产生了更多不想要的内容，分布上与配方组完全分离，甚至比无指导对照组更差——要对自己的案例进行微观测试，而不是假设，但默认不要使用禁止条款。配方式指导没有协商余地：输出要么符合声明的形状，要么不符合。
无论选择哪种形式，遵循以下规则：
强制执行纪律的 skill（如 TDD）需要抵御合理化。agent 很聪明，在压力下会寻找漏洞。
适用范围： 本工具包针对纪律性失败——即 agent 知道规则却在压力下跳过。对于输出形状错误或遗漏元素的情况，基于禁止的 bulletproofing 会适得其反；请改用“根据失败类型选择形式”中的形式。
心理学提示： 理解说服技巧为何有效，有助于你系统地应用它们。关于权威、承诺、稀缺、社会认同和一致性原则的研究基础，请参见 persuasion-principles.md（Cialdini, 2021；Meincke et al., 2025）。
不要只陈述规则——要禁止具体的规避方式：
```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.No exceptions:
</Good>
### 应对“精神 vs 字面”争论
尽早加入基础原则：
```markdown
**Violating the letter of the rules is violating the spirit of the rules.**
这能切断整个“我遵循的是精神”类别的合理化理由。
从基线测试中捕获合理化理由（见下方的测试部分）。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.**
在 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：
为此流程优化 — 尽早并频繁地放置可搜索术语。
创建 skill 就是为流程文档做 TDD。
同样的铁律：没有先失败的测试，就没有 skill。
同样的循环：RED（基线）→ GREEN（编写 skill）→ REFACTOR（堵住漏洞）。
同样的收益：更好的质量、更少的意外、无懈可击的结果。
如果你为代码遵循 TDD，也请为 skill 遵循它。这是将同样的纪律应用于文档。