编写技能

写技能就是给「流程文档」做 TDD。

你写测试用例（带压力的场景）→ 看它失败（基线行为）→ 写技能（文档）→ 看它通过 （代理遵守）→ 重构（堵漏洞）。

核心原则：如果你没有亲眼看到代理在没有该技能时失败，你就不知道这个技能教的是不是对的东西。

⚠️ 本仓库的第一条铁律

技能正文只描述动作，不指名工具。

正确的写法：「调用一次路由决策」「查一条条款」「跑一次提示词诊断」。 错误的写法：写死 mcp__collab-charter__charter_route 或某个平台的专用工具名。

这样一份技能正文才能在 Claude Code / Codex / Cursor / Gemini CLI 上通用， 平台差异全部收敛到 harnesses/tool-mapping.md。新增平台时只需加一列映射， 不碰任何技能文件——这是本项目最重要的不变式。

RED-GREEN-REFACTOR

目录结构

skills/
  skill-name/
    SKILL.md              # 主参考（必需）
    references/           # 重参考（100+ 行）才拆分
    assets/               # 可复用工具、脚本

扁平命名空间 —— 所有技能在一个可搜索的命名空间下。 保持内联：原则与概念、短代码片段（<50 行）、其他一切。

frontmatter：只有两个必填字段

---
name: skill-name-with-hyphens
description: 当 [具体触发条件与症状] 时使用
---

• name：只用字母、数字、连字符（无括号、无特殊字符）
• description：第三人称，只描述何时使用，绝不概述技能内容或流程

为什么 description 不能概述流程

实测发现：当 description 概述了工作流，代理会照着 description 做，而不是去读 技能正文。曾有一个技能在流程图里明确要求两轮审查（先查规格符合性、再查代码质量）， 但 description 写成「任务间做代码审查」，代理就只做了一轮。

陷阱：概述流程的 description 会制造捷径，技能正文沦为代理跳过的文档。

# ❌ 错：概述了流程
description: 当执行计划时使用——每个任务派发子代理，任务间做代码审查

# ✅ 对：只写触发条件
description: 当提交前需要核实工作是否达到要求时使用

关键词覆盖

使用代理会搜索的词：错误信息原文、症状（flaky / hanging / 静默忽略）、同义词、 真实工具名与命令。

命名：动词开头，主动语态

• ✅ using-charter、feature-cluster-syntax
• ❌ charter-usage、skill-creation

形式匹配失败类型（最容易被忽略的一条）

写指引前，先给基线失败分类。某种形式对一种失败有效，对另一种会反向恶化。

为什么禁令对「形状问题」会反噬：在竞争性动机下（如「让提示词自包含」）， 代理会跟「不要 X」讨价还价。实测中禁令臂产出的不想要内容是配方臂的两倍以上。

两条配套规则：

• 不要加「细微差别条款」——「不要 X，除非它重要」等于重新开启谈判。真实例外 必须写成挂在可观测谓词上的独立条件式。
• 豁免条款不限定范围——「此限制不适用于代码块」仍然会抑制代码块。

反合理化（仅用于纪律类技能）

范围：只针对「知道规则却在压力下跳过」的失败。对形状错误或漏项，禁令式加固会反噬。

堵死每个漏洞，不写「精神与字面」

违反规则的字面，就是违反规则的精神。

这一句能一次性砍掉整类「我遵循的是精神」的合理化。

建合理化对照表

| 借口 | 事实 |
|---|---|
| 「太简单了不用测」 | 简单代码照样出问题。测一次 30 秒。 |
| 「我事后补测」 | 事后测试立刻通过什么也证明不了。 |

建红旗清单

让代理在被合理化诱惑时能自查：

## 红旗 —— 停下重来
- 先写代码后写测试
- 「我已经手动测过了」
- 「这是特殊情况…」

常见反模式

部署前检查清单

RED

• 写压力场景（纪律类技能需 3 个以上复合压力）
• 无技能跑一遍，逐字记录基线行为
• 归纳出代理使用的合理化话术

GREEN

• name 只用字母数字连字符
• description 以触发条件开头、第三人称、未概述流程
• 全文关键词覆盖（错误信息、症状、真实工具名）
• 指引形式与失败类型匹配（见「形式匹配失败类型」）
• 有技能跑同样场景，代理已遵守

REFACTOR

• 找出新的合理化 → 加显式反制 → 重测至无漏洞
• 红旗清单 + 合理化对照表已建立

质量

• 只在决策非显然时用小流程图
• 有快速参考表
• 无叙事化故事
• 无 @ 强制加载链接（会立刻吃掉大量上下文）

与宪章的关系

本技能落实 7-R4（跨工具一致性，技能必须平台无关）与 0.8-C1（关键约束不丢失）。 本仓库自身的技能编写遵循本条铁律：动作词汇 + 平台映射表，而非平台专用工具名。