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
在进行任何创造性工作前必须使用——创建功能、构建组件、添加新功能或修改行为。在实现之前先探索用户意图、需求和设计。
TypeScript 和 React 开发的编码标准与最佳实践。在编写或审查代码时激活。提供命名、类型、组件设计、Hook 提取、状态管理等规范。
在用户确认要提交代码变更时使用——安全检查 diff 中的敏感数据后执行 git commit
在面对 2 个以上互不依赖、无共享状态的独立任务时使用
当有已编写的实现计划需要在独立会话中执行时使用，包含评审检查点
在实现完成、测试通过后，引导决定如何集成工作——提供合并、PR 或清理的结构化选项
| 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 也要遵循。这是同样的纪律应用于文档。