Menú
Use when creating new skills, editing existing skills, or verifying skills work before deployment
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
| name | writing-skills |
| description | Use when creating new skills, editing existing skills, or verifying skills work before deployment |
编写技能就是将测试驱动开发应用于流程文档。
个人技能存放在智能体特定的目录中（Claude Code 用 ~/.claude/skills，Codex 用 ~/.agents/skills/）
你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵从），然后重构（堵住漏洞）。
核心原则： 如果你没有亲眼看到智能体在没有技能的情况下失败，你就不知道这个技能教的是否正确。
必需背景： 在使用本技能之前，你必须理解 superpowers:test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档领域。
官方指导： 关于 Anthropic 官方技能编写最佳实践，参见 anthropic-best-practices.md。本文档提供了补充 TDD 聚焦方法的额外模式和指南。
技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效方法。
技能是： 可复用技术、模式、工具、参考指南
技能不是： 关于你曾经如何一次性解决问题 的叙事
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 带子智能体的压力场景 |
| 生产代码 | 技能文档（SKILL.md） |
| 测试失败（红） | 无技能时智能体违反规则（基线） |
| 测试通过（绿） | 有技能时智能体遵从（合规） |
| 重构 | 在保持合规的同时堵住漏洞 |
| 先写测试 | 编写技能前运行基线场景 |
| 观察失败 | 记录智能体使用的确切借口 |
| 最小代码 | 编写技能针对那些特定违规 |
| 观察通过 | 验证智能体现在遵从 |
| 重构循环 | 发现新借口 → 堵住 → 重新验证 |
整个技能创建过程遵循红-绿-重构。
创建时机：
不要为以下创建：
具体方法，带有要遵循的步骤（condition-based-waiting，root-cause-tracing）
思考问题的方式（flatten-with-flags，test-invariants）
API 文档、语法指南、工具文档（office docs）
skills/
skill-name/
SKILL.md # 主参考（必需）
supporting-file.* # 仅在需要时
扁平命名空间 - 所有技能在一个可搜索的命名空间中
单独文件的条件：
保持内联：
前言（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
发现的关键： 未来的 Claude 需要找到你的技能
目的： Claude 阅读描述来决定为给定任务加载哪些技能。让它回答："我现在应该读这个技能吗？"
格式： 以 "Use when..." 开始，聚焦触发条件
关键：描述 = 何时使用，不是技能做什么
描述应该只描述触发条件。不要在描述中总结技能的过程或工作流。
为什么这很重要： 测试揭示，当描述总结技能工作流时，Claude 可能会跟随描述而不是阅读完整的技能内容。说 "code review between tasks" 的描述导致 Claude 做了一次审查，即使技能流程图清楚显示有两次审查（规范合规然后代码质量）。
当描述改为只说 "Use when executing implementation plans with independent tasks"（无工作流总结）时，Claude 正确阅读了流程图并遵循了两阶段审查流程。
陷阱： 总结工作流的描述创造了一条 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。
# ❌ 错误：总结工作流 - Claude 可能跟随这个而不是阅读技能
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
# ❌ 错误：提到技术但技能并不特定于该技术
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
# ✅ 正确：技术特定的技能，有明确触发器
description: Use when using React Router and handling authentication redirects
使用 Claude 会搜索的词：
使用主动语态，动词优先：
creating-skills 不是 skill-creationcondition-based-waiting 不是 async-test-helpers问题： getting-started 和频繁引用的技能加载到每个对话中。每个 token 都重要。
目标字数：
技术：
将细节移到工具帮助中：
# ❌ 错误：在 SKILL.md 中记录所有参数
search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N
# ✅ 正确：参考 --help
search-conversations 支持多种模式和过滤器。运行 --help 查看详情。
使用交叉引用：
# ❌ 错误：重复工作流细节
搜索时，用模板分配子智能体...
[20 行重复指令]
# ✅ 正确：引用其他技能
始终使用子智能体（节省 50-100x 上下文）。必需：使用 [other-skill-name] 了解工作流。
压缩示例：
# ❌ 错误：冗长示例（42 词）
搭档："在 React Router 之前我们如何处理认证错误？"
你："我会搜索过去的对话中 React Router 认证模式。"
[分配带搜索查询的子智能体："React Router 认证错误处理 401"]
# ✅ 正确：最小示例（20 词）
搭档："我们在 React Router 中如何处理认证错误？"
你：搜索中...
[分配子智能体 → 综合]
消除冗余：
验证：
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编写引用其他技能的文档时：
仅使用技能名称，带明确的必需标记：
**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 {
"需要展示信息吗？" [shape=diamond];
"我可能在哪个决定点出错？" [shape=diamond];
"使用 markdown" [shape=box];
"小型内联流程图" [shape=box];
"需要展示信息吗？" -> "我可能在哪个决定点出错？" [label="是"];
"我可能在哪个决定点出错？" -> "小型内联流程图" [label="是"];
"我可能在哪个决定点出错？" -> "使用 markdown" [label="否"];
}
仅在以下情况使用流程图：
永远不要为以下使用流程图：
参见 @graphviz-conventions.dot 了解 graphviz 样式规则。
为你的搭档可视化： 使用本目录中的 render-graphs.js 将技能流程图渲染为 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/ # 可执行工具
适用：参考材料太大无法内联
没有失败的测试就不能有技能
这适用于新技能和现有技能的编辑。
写技能前测试？删除它。重头来。 编辑技能不测试？同样违反规则。
没有例外：
必需背景： superpowers:test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
不同的技能类型需要不同的测试方法：
示例： TDD、完成前验证、设计前编码
测试方法：
成功标准： 智能体在最大压力下遵循规则
示例： condition-based-waiting、root-cause-tracing、defensive-programming
测试方法：
成功标准： 智能体成功将技术应用于新场景
示例： reducing-complexity、information-hiding concepts
测试方法：
成功标准： 智能体正确识别何时/如何应用模式
示例： API 文档、命令参考、库指南
测试方法：
成功标准： 智能体找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "技能显然很清楚" | 你清楚 ≠ 其他智能体清楚。测试它。 |
| "只是参考而已" | 参考可能有漏洞、不清楚的部分。测试检索。 |
| "测试太过度了" | 未测试的技能有问题。每次都是。15分钟测试节省数小时。 |
| "如果出问题再测试" | 问题 = 智能体无法使用技能。部署前测试。 |
| "太乏味了不想测" | 测试比在生产中调试坏技能更不乏味。 |
| "我确信它很好" | 过度自信保证出问题。还是要测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的技能会浪费更多时间稍后修复。 |
所有这些意思是：部署前测试。没有例外。
强制纪律的技能（如 TDD）需要抵御借口。智能体很聪明，在压力下会找漏洞。
心理学笔记： 理解为什么说服技术有效帮助你系统地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini，2021；Meincke 等，2025）关于权威、承诺、稀缺、社会认同和统一原则。
不要只陈述规则——禁止具体变通方案：
<坏>
测试前写代码？删除它。
</坏>
<好>
测试前写代码？删除它。重头来。
**没有例外：**
- 不要保留作为"参考"
- 不要在写测试时"适配"
- 不要看它
- 删除就是删除
</好>
尽早添加基本原则：
**违反规则的字面就是违反规则的精神。**
这切断了一整类"我在遵循精神"的借口。
从基线测试中捕获借口（参见下面的测试部分）。智能体提出的每个借口都放入表中：
| 借口 | 现实 |
|--------|---------|
| "太简单不需要测试" | 简单代码也会坏。测试只需30秒。 |
| "我之后测试" | 测试立即通过什么都证明不了。 |
| "之后测试也能达到同样目标" | 后测 = "这是做什么的？" 先测 = "这应该做什么？" |
让智能体在找借口时容易自我检查：
## 红旗 - 停止并重头来
- 测试前写代码
- "我已经手动测试过了"
- "之后测试也能达到同样目的"
- "这是精神不是仪式"
- "这不一样因为..."
**所有这些意思是：删除代码。从 TDD 重头来。**
添加到描述中：你即将违反规则时的症状：
description: use when implementing any feature or bugfix, before writing implementation code
遵循 TDD 循环：
在无技能的情况下，用子智能体运行压力场景。记录确切行为：
这就是"观察测试失败"——你必须看到智能体自然做什么，然后才能写技能。
写技能针对那些特定借口。不要为假设情况添加额外内容。
用技能运行相同场景。智能体现在应该遵从。
智能体发现了新借口？添加明确的反驳。重新测试直到无懈可击。
测试方法论： 参见 @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 为什么坏： 标签应该有语义意义
编写任何技能后，你必须停止并完成部署流程。
不要：
以下部署清单对每个技能都是必需的。
部署未测试的技能 = 部署未测试的代码。违反质量标准。
重要：使用 TodoWrite 为以下每个清单项创建待办事项。
红阶段 - 写失败的测试：
绿阶段 - 写最小技能：
name 和 description 字段（最多 1024 字符；参见 规范）重构阶段 - 堵住漏洞：
质量检查：
部署：
未来 Claude 如何找到你的技能：
为此优化 - 将可搜索词早早且频繁放置。
创建技能就是流程文档的 TDD。
同样的铁律：没有失败的测试就不能有技能。 同样的循环：红（基线）→ 绿（写技能）→ 重构（堵洞）。 同样好处：更高质量、更少意外、无懈可击的结果。
如果你为代码遵循 TDD，也为技能遵循。这是应用于文档的相同纪律。
Before any creative work — creating features, building components, adding capabilities, or modifying behavior — you must use this skill. Explore user intent, requirements, and design before implementation.
Use when executing implementation plans with independent tasks in the current session
Use when implementing any feature or bug fix, before writing implementation code
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup