| name | writing-skills |
| description | Methodology for creating new workflow skills. Enforces TDD for process documentation: write failing scenario first, then write the skill. Use when adding any new SKILL.md to the workflow.
|
Writing Skills — 技能的测试驱动开发
⚡ Iron Law
在没有"无此技能时的失败场景"证明之前，禁止创建新技能。
技能是流程约束，不是功能代码。如果你无法演示"没有这个技能时 Agent 会做什么错误的事"，那么这个技能要么没有必要，要么你还没理解需要解决的问题。
为什么技能需要 TDD
Agent 的行为是概率性的。一个写得不好的技能会：
- 被 Agent 忽略（太长、太模糊）
- 被 Agent 选择性执行（只执行容易的部分）
- 与 Agent 默认行为重叠（浪费 context）
- 在特定情况下反而让 Agent 行为更差（过度约束）
只有先观察"没有技能时的失败模式"，才能写出真正解决问题的技能。
技能 TDD 协议（4步）
Step 1：记录失败场景（红）
在写任何 SKILL.md 之前，运行以下测试：
场景：给 Agent 相同的任务，但不提供新技能
观察：Agent 会做什么？哪里会出错？
记录：把失败的具体行为逐字记录下来
失败场景模板（保存为 skills/<name>/failure-evidence.md）：
# 失败场景记录 — <技能名>
## 测试日期
{date}
## 测试任务
给 Agent 以下指令，不提供新技能：
"{具体任务描述}"
## 观察到的失败行为
1. Agent 做了 {X}，但应该做 {Y}
2. Agent 跳过了 {步骤}，导致 {结果}
3. Agent 产出了 {错误的产出物}，因为缺少 {约束}
## 失败的严重程度
- [ ] 严重（导致下游阻塞）
- [ ] 中等（质量下降但可补救）
- [ ] 轻微（最佳实践偏差）
## 结论：这个技能是否有必要？
{是/否，以及理由}
Step 2：定义成功标准（什么叫"技能有效"）
## 成功标准
技能有效的判定条件（全部满足才算有效）：
- [ ] Agent 在 {触发条件} 时会自动加载此技能（不需要用户提示）
- [ ] Agent 执行技能中的 {关键步骤}，而不只是读一遍就继续
- [ ] 加载技能后，Step 1 中记录的失败行为不再出现
- [ ] 技能不会导致 Agent 在 {非适用场景} 时错误触发
Step 3：写技能（绿）
技能文件格式规范：
---
name: <skill-name>
description: >
[一句话描述触发条件] Use when [具体场景].
[不要写工作流摘要，不要写"此技能会做X"——那会让 Agent 读描述就跳过全文]
---
# <技能标题> — <副标题>
## ⚡ Iron Law（如果有的话）
[不可违反的单条规则，有且仅有一条最重要的]
## 禁止行为（可选）
[明确列出禁止做的事，比指令更有效]
## [主要流程/协议]
[具体的、可执行的步骤，用 bash 命令块而不是模糊描述]
## 接力
[完成后应该调用哪个技能，或通知哪个 Agent]
命名规则：
- 目录名：
kebab-case 动名词（如 systematic-debugging, writing-skills）
- description 开头：用
Use when... 描述触发场景，不用 This skill...
Step 4：验证（重跑失败场景）
给 Agent 相同的任务，这次提供新技能
检查：Step 1 中记录的失败行为是否还出现？
如果还出现：技能写得不够清晰，回到 Step 3
如果不出现：技能有效，可以合并
技能质量检查清单
在提交新技能之前，逐项检查：
接力
新技能写完并验证后：
- 更新
CLAUDE.md 中的技能列表（如果面向用户）
- 在调用方 agent 文件中添加技能引用
- 运行
node scripts/workflow.js install-global --force 使技能全局可用
