القائمة
在创建新 skill、编辑已有 skill 或部署前验证 skill 是否有效时使用
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | writing-skills |
| description | 在创建新 skill、编辑已有 skill 或部署前验证 skill 是否有效时使用 |
编写 skill 就是将测试驱动开发应用于流程文档。
个人 skill 放在代理特定目录中（Claude Code 用 ~/.agents/skills，Codex 用 ~/.agents/skills/）
你编写测试用例（用子代理的压力场景），看它们失败（基线行为），编写 skill（文档），看测试通过（代理遵守），然后重构（封堵漏洞）。
核心原则： 如果你没有看到代理在没有 skill 的情况下失败，你就不知道 skill 是否教了正确的东西。
必备背景： 使用此 skill 前你必须理解 test-driven-development。那个 skill 定义了基本的红-绿-重构循环。此 skill 将 TDD 适配到文档。
官方指南： 关于 Anthropic 官方 skill 编写最佳实践，参见 anthropic-best-practices.md。该文档提供了补充此 skill 中 TDD 方法的额外模式和指南。
Skill 是经过验证的技术、模式或工具的参考指南。Skill 帮助未来的 Claude 实例找到并应用有效的方法。
Skill 是： 可复用的技术、模式、工具、参考指南
Skill 不是： 关于你某次如何解决问题的叙事
| TDD 概念 | Skill 创建 |
|---|---|
| 测试用例 | 用子代理的压力场景 |
| 生产代码 | Skill 文档（SKILL.md） |
| 测试失败（红） | 代理在没有 skill 时违反规则（基线） |
| 测试通过（绿） | 代理在有 skill 时遵守 |
| 重构 | 封堵漏洞同时保持合规 |
| 先写测试 | 在编写 skill 之前运行基线场景 |
| 看它失败 | 记录代理使用的确切合理化借口 |
| 最少代码 | 编写针对那些具体违规的 skill |
| 看它通过 | 验证代理现在遵守了 |
| 重构循环 | 找到新的合理化借口 → 封堵 → 重新验证 |
整个 skill 创建过程遵循红-绿-重构。
创建条件：
不要为以下情况创建：
具有步骤的具体方法（condition-based-waiting、root-cause-tracing）
思考问题的方式（flatten-with-flags、test-invariants）
API 文档、语法指南、工具文档（office docs）
skills/
skill-name/
SKILL.md # 主参考文件（必需）
supporting-file.* # 仅在需要时
扁平命名空间 — 所有 skill 在一个可搜索的命名空间中
分离文件的条件：
保持内联：
Frontmatter（YAML）：
name 和 descriptionname：仅使用字母、数字和连字符（无括号、特殊字符）description：第三人称，仅描述何时使用（不描述它做什么）
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# Skill 名称
## 概述
这是什么？核心原则用 1-2 句话。
## 何时使用
[如果决策不明显，小型内联流程图]
症状和用例的项目符号列表
何时不使用
## 核心模式（技术型/模式型）
前后代码对比
## 快速参考
表格或项目符号，便于扫描常见操作
## 实现
简单模式内联代码
重度参考或可复用工具链接到文件
## 常见错误
什么会出错 + 修复
## 真实世界影响（可选）
具体结果
对发现至关重要： 未来的 Claude 需要找到你的 skill
目的： Claude 读取 description 来决定为给定任务加载哪些 skill。让它回答："我现在应该读这个 skill 吗？"
格式： 以"Use when..."开头聚焦于触发条件
关键：Description = 何时使用，不是 Skill 做什么
Description 应仅描述触发条件。不要在 description 中概括 skill 的流程或工作流。
为什么重要： 测试发现当 description 概括了 skill 的工作流时，Claude 可能会遵循 description 而不是阅读完整的 skill 内容。一个说"任务之间进行代码评审"的 description 导致 Claude 只做了一次评审，即使 skill 的流程图清楚显示了两次评审（先规格合规再代码质量）。
当 description 改为仅"Use when executing implementation plans with independent tasks"（无工作流概述）时，Claude 正确读取了流程图并遵循了两阶段评审流程。
陷阱： 概括工作流的 description 创建了 Claude 会走的捷径。Skill 正文变成了 Claude 跳过的文档。
# ❌ 差：概括了工作流 — Claude 可能遵循此处而非读 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
使用 Claude 会搜索的词：
使用主动语态，动词优先：
creating-skills 而非 skill-creationcondition-based-waiting 而非 async-test-helpers问题： getting-started 和高频引用的 skill 会加载到每次对话中。每个 token 都很重要。
目标词数：
技巧：
将细节移到工具帮助中：
# ❌ 差：在 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 test-driven-development**REQUIRED BACKGROUND:** You MUST understand systematic-debuggingSee 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 将 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 不测试？同样违规。
没有例外：
必备背景： test-driven-development skill 解释了为什么这很重要。同样的原则适用于文档。
不同 skill 类型需要不同的测试方法：
示例： TDD、verification-before-completion、designing-before-coding
测试方式：
成功标准： 代理在最大压力下遵循规则
示例： condition-based-waiting、root-cause-tracing、defensive-programming
测试方式：
成功标准： 代理成功将技术应用于新场景
示例： reducing-complexity、information-hiding 概念
测试方式：
成功标准： 代理正确识别何时/如何应用模式
示例： API 文档、命令参考、库指南
测试方式：
成功标准： 代理找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "Skill 显然很清晰" | 对你清晰 ≠ 对其他代理清晰。测试它。 |
| "这只是参考" | 参考可能有缺口、不清晰的章节。测试检索。 |
| "测试太过了" | 未测试的 skill 都有问题。始终如此。15 分钟测试省数小时。 |
| "出了问题再测" | 问题 = 代理无法使用 skill。部署前测试。 |
| "测试太繁琐" | 测试比在生产中调试有问题的 skill 更不繁琐。 |
| "我有信心它很好" | 过度自信保证有问题。无论如何测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的 skill 后修复它浪费更多时间。 |
以上所有都意味着：部署前测试。没有例外。
执行纪律的 skill（如 TDD）需要抵抗合理化。代理很聪明，在压力下会找到漏洞。
心理学注释： 理解说服技术为什么有效可以帮助你系统地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025）关于权威、承诺、稀缺性、社会证明和统一性原则。
不要只陈述规则——禁止具体的变通方法：
```markdown 先写代码再写测试？删掉它。 ``` ```markdown 先写代码再写测试？删掉它。重新开始。没有例外：
</Good>
### 应对"精神 vs 字面"的论证
尽早添加基础原则：
```markdown
**违反规则的字面意思就是违反规则的精神。**
这切断了整类"我在遵循精神"的合理化借口。
从基线测试中捕获合理化借口（见下方测试章节）。代理提出的每个借口都进入表格：
| 借口 | 现实 |
| -------------------------- | --------------------------------------------- |
| "太简单不需要测试" | 简单代码也会出错。测试只要 30 秒。 |
| "我之后再写测试" | 立即通过的测试什么都不证明。 |
| "后写测试也能达到同样目的" | 后写 = "这做了什么？" 先写 = "这应该做什么？" |
让代理在合理化时容易自检：
## 红旗 — 停下来重新开始
- 先写代码再写测试
- "我已经手动测试过了"
- "后写测试也能达到同样目的"
- "重要的是精神不是仪式"
- "这个情况不同因为..."
**以上所有都意味着：删掉代码。用 TDD 重新开始。**
在 description 中添加：你即将违反规则时的症状：
description: use when implementing any feature or bugfix, before writing implementation code
遵循 TDD 循环：
在没有 skill 的情况下用子代理运行压力场景。记录确切行为：
这是"看测试失败"——你必须在编写 skill 之前看到代理自然地做什么。
编写针对那些具体合理化借口的 skill。不要为假设情况添加额外内容。
用 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 = 部署未测试的代码。这违反了质量标准。
重要：使用 TodoWrite 为下方每个清单项创建 todo。
红阶段 — 写失败测试：
绿阶段 — 写最少 Skill：
重构阶段 — 封堵漏洞：
质量检查：
部署：
未来的 Claude 如何找到你的 skill：
为此流程优化 — 尽早并经常放置可搜索的术语。
创建 skill 就是流程文档的 TDD。
同样的铁律：没有先写失败测试，不写 skill。 同样的循环：红（基线）→ 绿（写 skill）→ 重构（封堵漏洞）。 同样的好处：更好的质量、更少的意外、无懈可击的结果。
如果你对代码遵循 TDD，对 skill 也要遵循。这是同样的纪律应用于文档。
在进行任何创造性工作前必须使用——创建功能、构建组件、添加新功能或修改行为。在实现之前先探索用户意图、需求和设计。
TypeScript 和 React 开发的编码标准与最佳实践。在编写或审查代码时激活。提供命名、类型、组件设计、Hook 提取、状态管理等规范。
在用户确认要提交代码变更时使用——安全检查 diff 中的敏感数据后执行 git commit
在面对 2 个以上互不依赖、无共享状态的独立任务时使用
当有已编写的实现计划需要在独立会话中执行时使用，包含评审检查点
在实现完成、测试通过后，引导决定如何集成工作——提供合并、PR 或清理的结构化选项