用途
本技能定义让仓库中每个技能都能与其他技能干净组合的规则。它同时处理两个问题：一个技能承诺产出什么，以及它被允许期望什么。它是使仓库能够作为系统组合、而非一堆链接文档的“执行脊柱”。
适用场景
- 创建新技能——在 skill-writing 之前加载本技能。
- 将旧技能对照当前标准进行规范化。
- 审查技能 PR 是否可接受。
- 审计仓库是否存在漂移。
- 引入新的技能类别（先在此定义其契约）。
两项标准
标准 1——内部风格模板（规范化）
每个技能，无论新旧，都必须符合以下形态，这就是“规范化”的含义。
必需 frontmatter：
---
name: <skill-slug>
description: Use when <trigger scenarios> — <what this skill covers>, <what it does not cover>. <One-line differentiator against neighbouring skills>.
---
description 规则：以 “Use when” 开头（触发式措辞）；列出应触发加载的场景；点名相邻技能以区分；单行、约 350 字符以内。
必需章节（按顺序）：标题、开篇段落、Prerequisites、When this skill applies（3–7 条具体场景）、Inputs、Outputs、Non-negotiables（非工程技能可选）、Decision rules（至少一个带阈值的决策表/阶梯）、Core content、Anti-patterns（5 条以上具体“不要这样做”，每条附修复方式）、Read next、References。
规则：SKILL.md ≤ 500 行，超出部分放入 references/；每个代码片段围栏带语言标签；除非用户明确要求，否则不使用 emoji；使用英式英语；规则用祈使语气，解释用陈述语气。
深度结构：任何超过单次阅读的内容必须抽取到 references/<topic>.md，每个引用文件 150–400 行，并遵循同样的无 emoji、英式英语、语言标签围栏规则。
交叉链接：SKILL.md 的 “Read next” 点名相邻技能；每个引用文件顶部链接回其父 SKILL.md；每个技能在 description 中声明其相邻区分点。
标准 2——输入/输出契约（组合）
每个技能声明其产出（outputs）和消费（inputs）。下游技能便可依赖这些工件存在且格式良好。基线技能产出专家技能消费的工件集，专家技能产出平台技能消费的更窄交付物。除 Inputs 和 Outputs 外，专家技能还声明其工件贡献于七个固定验证类别中的哪一个，该第三契约位于 validation-contract。
每个 SKILL.md 都有 Inputs 和 Outputs 表格：
## Inputs
| Artifact | Produced by | Required? | Why |
|---|---|---|---|
| Context map | `system-architecture-design` | required | service/module boundaries |
| Access pattern list | `database-design-engineering` | required | shapes the API contract |
| Threat model | `vibe-security-skill` | optional | informs auth rules |
## Outputs
| Artifact | Consumed by | Template |
|---|---|---|
| OpenAPI 3 spec | frontend, mobile, SDK skills | `skill-composition-standards/references/openapi-contract.md` |
| Error model | frontend, mobile | `skill-composition-standards/references/error-model.md` |
| Idempotency map | `reliability-engineering` | inline |
若技能不依赖任何上游工件，其 Inputs 章节写明：
## Inputs
None. This skill is a foundational baseline.
标准工件类型
仓库定义以下标准工件，每个在 references/ 中有模板：Context map、ADR set、Critical-flow table、Entity model、Access-pattern list、Migration plan、OpenAPI contract、Error model、Threat model、SLOs + alert plan、Release plan、Rollback plan、Runbook、Test plan + evidence、Delivery Definition of Done。产出某工件的技能必须按模板指定格式产出，下游技能消费模板格式版本。Delivery Definition of Done 是终端工件，将发布时输出打包为可检查的交接。
契约门（用于审查）
审查技能 PR 时验证：Outputs 是否声明产出工件；Inputs 是否声明消费内容；输出工件模板是否从 skill-composition-standards/references/ 链接；技能是否按模板格式而非自由形式产出。任一为否则 PR 未通过契约门。
基线输出契约（按基线技能类型）
- world-class-engineering：release gate checklist、production-readiness rubric。
- system-architecture-design：context map + critical-flow table + ADR set + dependency diagram notes + failure mode list。
- database-design-engineering：entity model + access-pattern list + index plan + migration plan + retention + tenancy notes。
- api-design-first：OpenAPI contract + auth model + error model + idempotency keys + observability notes。
- observability-monitoring：SLOs + alert rules + dashboards + runbook-per-service。
- reliability-engineering：retry/timeout matrix + degradation plan + incident playbook + postmortem template。
- deployment-release-engineering：release plan + rollback plan + migration choreography + post-deploy verification steps。
- advanced-testing-strategy：test plan + test evidence bundle + risk-based coverage map。
- vibe-security-skill：threat model + abuse case list + auth/authz matrix + secret handling plan。
完整列表与 schema 见 references/baseline-contract-register.md。
规范化工作流（升级旧技能）
- 一次性阅读当前 SKILL.md 及所有引用。
- 对照 20 点清单评分，记录差距。
- 先声明契约——编写 Inputs 和 Outputs 章节，决定应产出的工件类型并指向模板。
- 将 SKILL.md 重构为必需章节顺序，保留所有有价值内容。
- 将深度内容抽取到 references。
- 添加决策规则——若只描述“做什么”而无“何时某选项胜出”，添加决策表。
- 添加反模式——至少 5 个具体前后对比示例。
- 添加 Read next——点名 3–5 个相邻技能。
- 清理文字——无 emoji、英式英语、语言标签代码围栏。
- 运行验证器：
python -X utf8 skill-writing/scripts/quick_validate.py <skill>。
完整流程与示例见 references/normalisation-playbook.md。
执行方式
本技能机制上为建议性，惯例上为强制性。目前没有 CI 机器人阻止未通过契约门的技能合并。执行依靠：从 world-class-engineering 和 skill-writing 引用本技能；审查中使用 20 点清单；CI 中运行 quick_validate.py；每周规范化一个旧技能直至仓库规范化。未来工作：CI 钩子解析 Inputs/Outputs 表，当声称的上游工件未被任何上游技能声明时发出警告。
反模式
- 技能没有 Outputs 声明（每个技能都产出某些东西）。
- 技能声称的输入没有任何上游技能产出——该输入实际不存在。
- 输出用散文描述而非指向模板——失去可组合性。
- “References” 章节只是项目符号列表而文件不存在。
- 决策规则写成散文段落而非表格/阶梯。
- 反模式章节列出原则（“避免紧耦合”）而非具体前后示例。
- 相邻技能未在任何地方提及，导致重叠模糊。
- 技能超过 500 行且无 references/ 目录。
延伸阅读
- skill-writing——编写流程、验证器、frontmatter 规则。
- world-class-engineering——引用本技能的仓库级质量标准。
- advanced-testing-strategy、observability-monitoring、reliability-engineering、deployment-release-engineering——其契约锚定仓库的可运维性基线技能。
引用文件
- references/house-style-checklist.md——20 点审查清单
- references/normalisation-playbook.md——如何升级旧技能
- references/baseline-contract-register.md——按基线技能类型的完整工件契约登记
- references/context-map-template.md
- references/adr-template.md
- references/critical-flow-template.md
- references/openapi-contract.md
- references/error-model.md
- references/threat-model-template.md
- references/slo-template.md
- references/release-plan-template.md
- references/rollback-plan-template.md
- references/runbook-template.md
- references/test-plan-template.md