用途
docs-manager 是一个文档同步与初始化技能，目标是让项目文档与代码保持一致。它适用于两类场景：一是在代码、规格或测试发生变更后，对受影响的上下文、配置、规格/测试归属以及派生/演示输出进行更新（update 模式）；二是显式初始化或核对选定的参考文档（init 模式）。
主要能力
技能采用模式化设计，每次调用只使用一种模式：
--mode=update：按变更影响范围执行上下文/配置检查，定位规格/测试归属，处理派生/演示输出，最后生成报告（输出至 tmp/reports/docs-update-{YYMMDD}-{HHMM}.md）。该模式支持可选参数：modules=… changed_files=… phases=… skip_phases=… tc_mode=… freshness={impact|full|off} base=…。--mode=init：通过扫描初始化或核对选定的、适用的参考文档；仅在显式指定--mode=init时运行。
模式路由为强制步骤：若指定了 --mode=update 或 --mode=init，则选择对应模式；若没有模式标志，但自然语言请求匹配 update 的触发意图（如“update docs”“docs impacted by my changes”“sync docs after code change”“doc sync”“documentation update”），则选择 update；若既无模式标志也无匹配请求，则只展示模式分派表并停止，不询问、不执行。init 只能由显式 --mode=init 选择。
确定模式后，必须先完整读取对应的 references/mode-update.md 或 references/mode-init.md，再按其契约执行。
使用方式
调用形式如 $docs-manager --mode=update 或 $docs-manager --mode=init。在 Codex 环境中，需以 $skill-name 形式调用，加载已注册的 .agents/skills/<name>/SKILL.md 并用 Codex 工具执行，无需单独的 Skill 工具或 Claude 模式切换。
流程为：检测模式 → 完整读取对应参考 → 解析范围与归属 → 运行质量门禁 → 审查并报告证据。协议顺序除非用户批准偏离，否则应保留；工作流中的门禁固定不变，其他步骤可在记录原因与证据后灵活调整。
另需注意：docs-manager 子代理（agent_type="docs-manager"）是一个代理，并非本技能本身，它驱动 $docs-manager --mode=update。单文档重建属于 scan（$scan --target=<key>），一次性刷新全部选定参考文档属于 scan-all；update 会升级到它们，init 则委托给 scan，二者都不是本技能的模式。
约束与规则
- 每次调用只能使用一种模式，只加载所选模式的主体。
- 所有主张需基于证据（file:line），置信度需超过 80% 才可行动。
- 任务跟踪需在每个步骤开始和完成时保持最新。
- 需对每个范围内的文档验证共享的输出质量内容检查，包括返回的扫描结果，并保留只读审计边界。
- 当处理超过 200 行的 Markdown 技能/文档内容时，需验证顶部与标题链接的目录，编辑后刷新，并在只读审计中报告缺口。
- 外来工具名称需映射到宿主可用能力；名称不匹配无需批准，但实际不可用的必需能力应在适配前停止并附带步骤/证据向用户提问。
适用场景与限制
适用于需要在代码变更后同步文档、或需要初始化参考文档的工程流程。其限制包括：不猜测模式；未显式指定 --mode=init 时不启动 init；不编造未在资料中提供的功能或步骤。具体细节需以对应模式的参考文件为准。