writing-skills

编写技能

概述

编写技能就是将测试驱动开发应用于流程文档。

编写测试用例（通过子 Agent 设计压力场景），观察测试失败（基线行为），编写技能（文档），观察测试通过（Agent 遵循要求），然后重构（堵住漏洞）。

**核心原则：**如果你没有观察过 Agent 在没有技能时失败，就不知道这个技能是否教对了内容。

**个人技能存放在特定 Agent 的目录中：**Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.codex/skills

**必备背景知识：**这项技能将测试优先的纪律应用于技能编写——先观察技能如何失败，再决定是否信任它。测试方法详见 testing-skills-with-subagents（见下文）。

何时使用

满足以下条件时创建技能：

• 这项技巧对你来说并非直观易懂
• 你会在不同项目中再次参考它
• 这个模式具有广泛适用性（而非特定于某个项目）
• 其他人也能从中受益

以下情况不要创建技能：

• 一次性解决方案
• 其他地方已有充分文档说明的标准实践
• 特定于项目的约定（放入 CLAUDE.md）

技能类型

• 技巧：包含步骤的具体方法（condition-based-waiting、root-cause-tracing）
• 模式：思考问题的方式（flatten-with-flags、test-invariants）
• 参考资料：API 文档、语法指南、工具文档（office docs）

快速参考

任务	加载参考资料
理解技能的 TDD 映射	skills/writing-skills/references/tdd-mapping.md
了解技能结构和组织方式	skills/writing-skills/references/skill-structure.md
优化搜索与发现效果	skills/writing-skills/references/search-optimization.md
使用子 Agent 测试技能	skills/writing-skills/references/testing-skills.md
代码示例和流程图	skills/writing-skills/references/code-and-flowcharts.md
完整的创建检查清单	skills/writing-skills/references/checklist.md

RED-GREEN-REFACTOR 工作流

RED：编写失败的测试（基线）

1. 创建压力场景（纪律型技能需组合 3 种以上压力因素）
2. 在不使用技能的情况下运行场景——逐字记录基线行为
3. 找出合理化说辞或失败中的模式

**这一点至关重要：**编写技能之前，你必须先了解 Agent 自然会怎么做。

GREEN：编写最精简的技能

1. 编写技能，针对基线测试中发现的具体失败
2. 遵循结构指南（见 skill-structure.md）
3. 优化搜索效果（见 search-optimization.md）
4. 使用技能运行相同的场景——验证 Agent 现在是否会遵循要求

REFACTOR：堵住漏洞

1. 找出测试中出现的全新合理化说辞
2. 为纪律型技能添加明确的反制措施
3. 根据所有迭代构建合理化说辞表
4. 反复测试，直到无懈可击

**必需的子技能：**使用 testing-skills-with-subagents 了解完整的测试方法。

铁律

NO SKILL WITHOUT A FAILING TEST FIRST

这适用于新技能和对现有技能的修改。

先写技能再测试？删除它，重新开始。

没有例外：

• 不适用于“简单的补充”
• 不适用于“只是添加一个章节”
• 不适用于“文档更新”
• 删除就是删除

常见错误

错误	修正方法
先写技能再测试	删除技能，先运行基线测试
跳过基线（RED 阶段）	不观察失败，就不知道该教什么
在技能已存在时进行测试	移除技能，获取真实的基线行为
“批量处理”多个技能	完成每个技能的 RED-GREEN-REFACTOR 流程后再继续
描述含糊	以“在……时使用”开头，并包含具体触发条件
使用 @ 链接引用技能	仅使用技能名称，避免强制加载
使用多个平庸的代码示例	在最相关的语言中提供一个出色的示例
叙事式讲述	聚焦可复用的模式，而非一次性的故事

在继续下一个技能前停止

编写任何技能后，都必须停止并完成部署流程。

不要批量创建多个技能却不逐一测试。部署未经测试的技能 = 部署未经测试的代码。

完整的部署清单请参阅 checklist.md。

资源

• 官方指南：有关 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md
• Graphviz 约定：请参阅 @graphviz-conventions.dot，了解流程图样式规则
• 测试方法：使用 testing-skills-with-subagents