菜单
文档自动维护（Docs Maintenance）——git commit 前，凡本次改动对应的 story 已 verified 且其 design.md 影响面涉及架构 / 设计 / 约定变更，必须使用本技能。文档已覆盖变更则跳过——本技能的产出是文档与代码一致，不是每次都改文档。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
需求门禁（Requirements Gate）——只要用户提出开发需求或变更请求（实现 / 新增 / 开发 / 加一个 / 修改 / 重构 / 优化 / 接入 / 修复 / add / implement / build / feature / fix），哪怕措辞很随意，且该任务还没有 status: approved 的 story.md，就必须在写任何代码之前使用本技能。不要因为需求看起来很简单而跳过。
验收门禁（Verification Gate）——与 requirements-gate 成对的下游环节：需求门禁确保做对的东西，验收门禁确保做的东西是对的。开发完成、准备 git commit、或想宣称'做完了'之前，凡存在与本次改动相关、status: approved 但尚未 verified 的 story.md，必须使用本技能。注意：测试全部通过不等于验收通过——技术正确性归 verification-before-completion，需求符合度归本技能。
| name | docs-maintenance |
| description | 文档自动维护（Docs Maintenance）——git commit 前，凡本次改动对应的 story 已 verified 且其 design.md 影响面涉及架构 / 设计 / 约定变更，必须使用本技能。文档已覆盖变更则跳过——本技能的产出是文档与代码一致，不是每次都改文档。 |
把"更新文档"从靠自觉，变成 commit 链路上的固定一环。本技能独立运作：上游技能是否安装、是否被 skip，不影响本技能的判断。
收到「文档维护」提醒或准备 commit 时，按序回答，命中即放行：
[skip-gate] / [跳过门禁] → 放行五问全部不命中 → 更新文档。
前三类是仓库内工作上下文（供在本仓库开发的 Agent）；后四类面向项目的使用者与贡献者——读者可能是人，也可能是 Agent，llms.txt 即 Agent 侧的导航入口：
| 文档 | 更新方式 | 细则 |
|---|---|---|
| AGENTS.md | 识别变更 → 增量修订 → 版本号语义化递增 → 一致性传播检查 | references/agents-md-protocol.md |
| ARCH.md | 按固定八章节定位修改；不存在时用模板初始化 | references/arch-md-structure.md、assets/arch-template.md |
| DESIGN.md | 仅初始化时调 impeccable 技能生成；已存在时把 design.md 影响面传给 impeccable，由其增量更新 | impeccable 技能 |
| README.md | 按需更新：触发判据命中才更新；不存在则直接初始化 | references/outward-docs.md |
| llms.txt | 按需更新：与 README 导航同触发，按 llmstxt.org 规范维护；不存在则直接初始化 | references/outward-docs.md |
| 用户使用说明 | 按需更新：触发判据命中才更新；不存在则直接初始化 | references/outward-docs.md |
| 技术开发说明 | 按需更新：触发判据命中才更新；不存在则直接初始化 | references/outward-docs.md |
七类文档按影响面各自独立判断，一次 commit 可能只动一个或都不动。
| 借口 | 纠正 |
|---|---|
| "改动很小，文档下次一起更新" | 下次永远不来。增量机制就是为了让每次都小到没有借口 |
| "整个重写一遍更干净" | 增量修订，定位到章节。重写破坏版本史与引用锚点 |
| "顺手优化其他章节" | 本次变更不涉及的章节一个字不动 |
| "CLAUDE.md 也改一遍保险" | 只改 AGENTS.md。改两处必出分叉 |
| "影响面我记得，不用读契约" | 以 verified story 的 AC/非目标 + design.md 影响面 + 实际 diff 为准 |
| "story 没 verified，文档先写上" | 未验收的实现不进文档 |
| "用户文档里讲讲实现原理更清楚" | 读者视角铁律：用户文档零实现细节；开发文档链接 ARCH.md，不复制 |
| "使用/开发文档不存在，先跳过吧" | 触发命中而文档不存在 = 直接初始化，不等待用户发起 |
| "README 里把使用说明全写一遍" | README 是门面：定位 + 快速开始 + 导航链接，详情归 docs |
| "Agent 看 README 就行，llms.txt 多余" | llms.txt 是机读规范：固定节序可解析，Optional 节支持上下文裁剪 |
| "约定写成'尽量遵守'比较灵活" | 不可检验的约定约束不了任何 Agent。必须 / 应当（附例外条件）/ 可以，三级措辞 |
安装说明见
INSTALL.md（面向人类，不属于技能上下文）。