Designing a skill collection as a coherent system — not just writing good individual skills
单个 skill 怎么写，Anthropic 官方指南已经讲透；这里讲的是更高一层——一整套 skill 加多个 agent，如何拼成一个自洽、可演化、可验证的系统。六条静态设计原则，加一套实证评估回路。
这不是"怎么写好一个 skill"的指南——progressive disclosure、description 写法、degrees of freedom 这些单个 skill 的工艺，Anthropic 官方 best-practices 已经讲清楚了。
这份文档处理的是更高一层的问题:一整套 skill 加上多个 agent,如何拼成一个自洽的系统。把每个 skill 当模块、trigger 当接口、输出当契约、核心 prompt 当内核--当零件多起来、agent 开始互相编排,零件级的正确不再蕴含系统级的正确。这是系统工程：覆盖、正交、接口契约、回归、端到端验证。下面七条原则负责静态自洽，最后的评估回路负责实证验证。
你在给一个帮你发代码的 agent 装 skill:write-tests(写测试)、review-diff(审查 diff)、debug(调试失败)、commit(提交)、refactor(重构),加一个 planner 用 workflow 把它们编排起来。每条单独看都没问题——但装在一起，问题接踵而至。下面七条原则用这套系统来演示。
You're building a coding agent: write-tests, review-diff, debug, commit, refactor — planner-orchestrated. Each skill looks fine alone. Together, things break. The seven principles below show exactly how and why.
这七条不是独立的规则，是一套相互咬合的逻辑体。每一条回答设计过程中的一个根本问题。
Seven interlocking principles — each answers one fundamental design question.
commit skill。但 refactor、review-diff 的 subagent 根本看不见 commit，照样提交没跑测试的代码。commit skill 只写"怎么提交"的工艺。review-security，因为"安全审查感觉和代码审查相关"。结果 review-diff 和 review-security trigger 重叠，同一个 diff 两个 skill 都抢着触发，agent 拿到两个互相矛盾的权威。review-diff 的一个 mode，不是独立 regime——合并，或降为 reference 文件。write-tests 和 run-tests，但没有任何 skill 处理"CI 红了，不知道为什么"。agent 遇到这个状态只能裸跑，每次即兴发明解法，行为不可预测。confidence=low + severity=critical 的发现是合法且必需的输出。证据薄就降 confidence、标高误报风险——但不要为了让自己舒服而降 severity。降 severity 来藏发现，是这个角色真正的失败。
skill/reference/responsibility.md（完整的姿态系统提示，含跳过 lens 的三态责任模型）。skill 决定如何审计一个类目；这份文件决定是否审计——后者不由 skill body 决定。
scripts/selfcheck.py（或夹具+期望输出），接进评估回路；自检变红，闸上拦住这次改动，而不是凌晨两点在生产里发现。按使用频率决定层级，不按重要性。重要但按需才用的东西，不应该常驻 prompt。
reference/：深度方法论、决策树、路由表、领域事实scripts/：可执行脚本、工具代码、数据处理Regime 的操作化定义（全方法论的中央判定谓词，先钉死再读矩阵）：两个候选 skill 属于同一 regime，当且仅当它们共享 trigger 条件且共享 good-work 标准——否则就是不同 regime。"内容相关""感觉像"不算；安全审查与代码审查共享 trigger（同一 diff），故是同一 regime 的两个 mode，不是独立 skill。
这里只列与系统自洽相关的结构钩子（Kernel anchor 追溯、Not-for 契约、智慧/法律分层）；单个字段怎么写得好，见官方指南。SKILL.md 主体留给文字和方法论：重代码 → scripts/，决策树与领域事实 → reference/（短示例片段内联无妨）。注：YAML 里 Claude 官方只强制 name 和 description 两个字段；下表里标"必须"的是本方法论的约定（用来保证系统自洽），不是平台的硬性要求。
Not for X (→ [[sibling]])。这是机器可读的契约，不是描述文字。→ 不做 X → [[兄弟 skill]]。这是接口契约。没有它，正交性无从验证，scope 悄悄蔓延。reference/ 里。高频在前，低频在后。先把代价写实，再看分类——账单在生产环境兑现，不在设计文档里。Trigger 冲突：两个 skill 在同一 turn 都 fire，凌晨 02:00 agent 选错、发出错的交接产物、planner 在误读的意图上建计划，天亮时系统已基于错误前提执行了上百个动作——post-mortem 点名的是谁让 trigger 重叠。覆盖空白：周五 17:00 发布压力下，agent 撞上一个没有 skill 接管的真实状态，抓起"probably fine / 留到下一轮"即兴一个答案，部署上线；周一回归套件才抓到，但周五的部署已经到了用户手里——留下那个矩阵格子没主的人，等于对它签字。浮空 skill：追溯不到 Kernel 原则的 skill 没东西拴住它，你删了兄弟的 reference，它的 trigger 还指向被删的文件，三周后审计发现它从那以后每次调用都在静默空转——没查入站指针就降级 reference 的人，拥有这段停机时间。你对未浮现的空白和重叠负责——把这个背上。
scripts/。决策树 → reference/routing-table.md。Schema → reference/。SKILL.md 主体留给方法论。scripts/ 或 reference/。SKILL.md 是方法论文档，不是实现文档。前面七条原则加七问，审的是静态设计的自洽性——读着对，未必跑着对。系统是否真的覆盖了状态空间、转移是否真的确定、改一处会不会碰倒他处,只有把它放回真实输入里跑才知道。
单 skill 评估问"这个零件能用吗";系统级评估问"零件装在一起,覆盖全、转移准、改一处不坏他处、串成 pipeline 还跑得通吗"。
should_trigger=true/false 回归 + blind A/B——这是官方的 skill 内评估工作流（仍是 meta-skill，且只评估单个 skill）。本文档扩展到系统级回归（trigger 消歧、覆盖、跨 agent 契约、端到端）仍是外推。评估多用自然语言 rubric 由模型判分，不是严格的断言式单元测试。
这两个话题前面已多次引用（尤其评估章节的契约测试）；这里补充它们的完整定义与模板出处。
Both concepts were referenced throughout — here's the complete definition and implementation guidance.
should_trigger eval（skill-creator v2）/ trigger disambiguationcontract_version 字段。任何 breaking 的契约变更（改字段、改路径、改格式）必须 bump 版本号、写迁移说明，并由系统级回归套件门控——这样下游才能发现上游契约变了。失败处理：契约只规定成功 schema；当 sub-skill 产出畸形 artifact、planner 路由进死胡同时怎么办，明确声明为 planner skill 的职责（重试 / 升级 / 终止），不要让责任悬空。评估 step 4 可加一步"注入契约违规，断言 planner 检测到并走定义的恢复路径"。