编写技能（Writing Skills）
概述
编写技能就是将测试驱动开发（TDD）应用到流程文档上。
你编写测试用例（压力场景+子代理），看它们失败（基线行为），编写技能（文档），看测试通过（代理遵从），然后重构（封堵漏洞）。
核心原则： 如果你没有看到代理在没有技能的情况下失败，你就不知道这个技能教的是否正确。
什么是技能？
技能是： 经验证的技术、模式或工具的参考指南 技能不是： 关于你如何解决某次问题的叙事
TDD 映射
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 压力场景 + 子代理 |
| 生产代码 | 技能文档（SKILL.md） |
| 测试失败（RED） | 代理在没有技能时违反规则 |
| 测试通过（GREEN） | 代理在有技能时遵从 |
| 重构（REFACTOR） | 封堵漏洞同时保持合规 |
何时创建技能
创建条件：
- 技术对你来说不是直觉性的
- 跨项目会再次引用
- 模式广泛适用
- 其他人会受益
不要创建：
- 一次性解决方案
- 标准实践（已有良好文档）
- 项目特定约定（放在 CLAUDE.md）
技能类型
- Technique（技术）：有步骤的具体方法
- Pattern（模式）：思考问题的方式
- Reference（参考）：API 文档、语法指南
SKILL.md 结构
# 技能名称
## 概述
核心原则 1-2 句话
## 何时使用
触发条件和场景
## 核心模式
前后对比代码
## 快速参考
表格或要点
## 常见错误
问题 + 修复
## 实际效果（可选）
具体成果
Claude 搜索优化（CSO）
关键：描述 = 何时使用，不是技能做什么
关键发现： 测试表明，当描述总结了技能的工作流程时，Claude 可能按描述而非阅读完整技能内容来执行。
# ❌ 差：总结了工作流——Claude 可能按此执行而跳过技能正文
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ✅ 好：只有触发条件，无工作流总结
description: Use when executing implementation plans with independent tasks in the current session
Token 效率
- getting-started 工作流：<150 词
- 常用技能：<200 词
- 其他技能：<500 词
铁律（与 TDD 相同）
没有失败测试就不编写技能
防合理化加固
封堵每个漏洞
不仅声明规则——禁止具体的变通方法。
解决"精神 vs 字面"争论
**违反规则的字面意思就是违反规则的精神。**
建立合理化表格
从基线测试中捕获的每个借口都放入表格。
创建红旗列表
让代理在找借口时能自我检查。
技能创建清单
RED 阶段：
- 创建压力场景（3+ 组合压力）
- 无技能运行场景——逐字记录基线行为
- 识别合理化模式
GREEN 阶段：
- 编写技能应对具体基线失败
- 有技能运行场景——验证代理遵从
REFACTOR 阶段：
- 识别新的合理化
- 添加显式对策
- 重新测试直到防弹