何时使用
- 创建新技能时
- 编辑现有技能时
- 部署前验证技能
编写技能 (writing-skills)
编写技能（writing-skills）
Section titled “编写技能（writing-skills）”writing-skills 是将 Test-Driven Development 应用于流程文档的 Skill。
核心原则：
如果没有看过没有技能的代理失败，你就不知道技能教的是否正确。
写作技能就是 TDD 应用于文档开发。
你写测试用例（带子代理的压力场景），看它们失败（基线行为），写技能（文档），看测试通过（代理遵守），然后重构（堵住漏洞）。
什么是 Skill？
Section titled “什么是 Skill？”Skill 是经过验证的技术、模式或工具的参考指南。帮助未来的 Claude 实例找到并应用有效方法。
Skill 是：
- 可复用技术
- 模式
- 工具
- 参考指南
Skill 不是：
- 关于你如何解决一次问题的叙事
TDD 在 Skill 创建中的映射
Section titled “TDD 在 Skill 创建中的映射”| TDD 概念 | Skill 创建 |
|---|---|
| 测试用例 | 带子代理的压力场景 |
| 生产代码 | Skill 文档（SKILL.md） |
| 测试失败（RED） | 无技能时代理违反规则（基线） |
| 测试通过（GREEN） | 技能存在时代理遵守 |
| 重构 | 在保持合规的同时堵住漏洞 |
| 先写测试 | 写技能前运行基线场景 |
| 看它失败 | 记录代理使用的具体合理化借口 |
| 最小代码 | 写技能解决那些具体违规 |
| 看它通过 | 验证代理现在遵守 |
| 重构循环 | 找新合理化 → 堵住 → 再验证 |
整个技能创建过程遵循 RED-GREEN-REFACTOR。
何时创建 Skill
Section titled “何时创建 Skill”- 技术对你来说不是直观明显的
- 你会在项目间参考这个
- 模式广泛应用（不是特定项目的）
- 其他人也会受益
- 一次性解决方案
- 标准实践已有良好文档
- 特定项目约定（放到 CLAUDE.md）
- 机械约束（如果可以用 regex/验证强制执行，就自动化 —— 把文档留给需要判断的情况）
Skill 类型
Section titled “Skill 类型”技术（Technique）
Section titled “技术（Technique）”有步骤要遵循的具体方法（condition-based-waiting, root-cause-tracing）
模式（Pattern）
Section titled “模式（Pattern）”思考问题的方式（flatten-with-flags, test-invariants）
参考（Reference）
Section titled “参考（Reference）”API 文档、语法指南、工具文档（office docs）
skills/ skill-name/ SKILL.md # 主参考（必须） supporting-file.* # 仅在需要时扁平命名空间 - 所有技能在一个可搜索命名空间
SKILL.md 结构
Section titled “SKILL.md 结构”Frontmatter（YAML）
Section titled “Frontmatter（YAML）”---name: skill-name-with-hyphensrepo: superpowersdescription: Use when [具体触发条件和症状]---- 只有两个字段：
name和description - 描述必须以 “Use when…” 开头
- 描述只写触发条件，不总结技能的工作流程
# ❌ 错误：总结工作流程 - Claude 可能按这个走而不是读完整内容repo: superpowersdescription: Use when executing plans - dispatches subagent per task with code review between tasks
# ✅ 正确：只有触发条件，没有工作流程总结repo: superpowersdescription: Use when executing implementation plans with independent tasks in the current session# Skill Name
## Overview这是什么？用 1-2 句话概括核心原则。
## When to Use[如果决策不明显，小型内联流程图]
带症状和使用场景的项目符号列表何时不使用
## Core Pattern之前/之后代码对比（针对技术/模式）
## Quick Reference用于扫描常见操作的表格或项目符号
## Common Mistakes什么问题 + 修复
## Real-World Impact具体结果（可选）铁律（与 TDD 相同）
Section titled “铁律（与 TDD 相同）”没有先失败测试就不能写 SKILL这适用于新技能和现有技能的编辑。
先写技能再测试？删掉，重来。 编辑技能不测试？同样违规。
没有例外：
- 不是”简单添加”
- 不是”就加个章节”
- 不是”文档更新”
- 不要保留未测试的更改作为”参考”
- 不要在运行测试时”适应”
- 删掉就是删掉
常见合理化借口
Section titled “常见合理化借口”| 借口 | 现实 |
|---|---|
| ”技能明显很清楚” | 你觉得清楚 ≠ 其他代理觉得清楚。测试它。 |
| “只是参考” | 参考可能有缺口、不清楚的部分。测试检索。 |
| “测试太overkill” | 未测试的技能有问题。始终。15分钟测试节省数小时。 |
| “有问题再测” | 问题 = 代理无法使用技能。部署前测试。 |
| “太乏味不想测” | 测试比调试坏技能更不乏味。 |
| “我确信它很好” | 过度自信保证有问题。无论如何要测试。 |
防止合理化的技巧
Section titled “防止合理化的技巧”明确堵住每个漏洞
Section titled “明确堵住每个漏洞”不要说规则——禁止具体变通方案：
❌ 错误：写代码在测试前？删掉它。
✅ 正确：写代码在测试前？删掉它。重来。
没有例外：- 不要保留作为"参考"- 不要在写测试时"适应"它- 不要看它- 删掉就是删掉解决”精神 vs 字面”争论
Section titled “解决”精神 vs 字面”争论”尽早添加基本原则：
违反规则的字面就是违反规则的精神。这切断了一整类”我在遵循精神”的合理化。
建立合理化表格
Section titled “建立合理化表格”从基线测试中捕获合理化。每次代理找借口都记录在表格中。
关键要点
- Skill 创建就是 TDD 应用于文档
- 必须先写测试看失败
- 描述只写触发条件，不总结流程
- 堵住每个合理化漏洞
禁止
- 先写技能再测试
- 编辑技能不测试
- 在描述中总结工作流程
- 跳过测试因为”明显清楚”
关联 Skill
Section titled “关联 Skill”- 必须前置理解：
test-driven-development（TDD 基础）。 - 互补：
systematic-debugging（调查技能问题）。
查看源文件: GitHub原始文件