메뉴
契约治理三件套的「文档层」——真正动手改写文档的那一个。当 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops、docs/contributing.md 落后于代码现状时，按文档映射读取最小必要文档并执行同步更新，保证项目文档自动维护。本 skill 负责「改写文档内容」；它不判断某个改动是否破坏公共契约（那是结构层，转 contract-guard），也不核对同一物理值在多处是否一致（那是值层，转 config-contract-sync）。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
契约治理三件套的「值层」。核对同一个物理契约值（MQ topic/group、OSS bucket、消息字段名/别名、内部 HTTP 路径等）在 .env/.env.example/代码生效点/Java 对端多处是否逐字相等，找出配置漂移与死值，防止消息收不到/文件取不到。本 skill 只比对「同一个值在多处是否一致」，不判断结构/语义是否破坏对端（那是结构层，转 contract-guard），也不改文档。
指导 LLM 如何使用 toLink-Rag 项目的 MQ 消息中台进行消息收发、定义新消息类型以及处理多厂商适配逻辑。
当用户认为当前模块代码实现完毕，且当前分支应为 dev，需要从 dev 基于当前修改创建规范分支、提交并发起合并到 dev 的 GitHub PR 时使用；也用于发布收口，即直接创建 dev -> master 的 release PR，不新建 release 分支。适用于“从 dev 新建分支”“把当前修改提 PR”“实现完成创建 feature/refactor 分支并 PR”“发布新版本”“dev 合并 master”等交付收口场景。本 skill 是交付链终点，并在建分支/提 PR 前执行收口门槛：测试未过、契约文档失同步、acceptance 未提升者拒绝收口。
当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量
把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。
当用户要提 issue、登记 bug、记录新需求时使用；自动识别所属项目，生成结构化 issue 内容，先在 Linear 建主记录、再在 GitHub 建镜像，并双向回链。用户说"提个 issue""记一下这个 bug""把这个需求登记一下""同步到 Linear 和 GitHub""别再依赖 Linear 自动同步"时都应触发，即使没有明确说出"Linear"或"GitHub"。
| name | doc-maintenance-sync |
| description | 契约治理三件套的「文档层」——真正动手改写文档的那一个。当 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops、docs/contributing.md 落后于代码现状时，按文档映射读取最小必要文档并执行同步更新，保证项目文档自动维护。本 skill 负责「改写文档内容」；它不判断某个改动是否破坏公共契约（那是结构层，转 contract-guard），也不核对同一物理值在多处是否一致（那是值层，转 config-contract-sync）。 |
| when_to_use | 当用户要求更新/维护项目文档，或代码/配置/数据库/MQ/API/解析器/分片/向量化已经改了、需要让 docs 下的架构、约定、参考资料、计划说明追上现状时激活——本 skill 是真正执行文档改写的环节。触发示例：'改了 API 记得更新文档'、'新增错误码同步下文档'、'调整数据模型更新 schema 文档'、'修改解析器结构'、'更新 AGENTS'、'同步文档'、'维护项目说明'。三件套切分：只是想先判定『这个改动会不会破坏公共契约、要同步哪些文档』而尚未动笔 → 先走 contract-guard 拿清单，再回本 skill 执行；只是核对某个 topic/字段在 .env/Java 多处取值是否一致 → config-contract-sync；只同步 AGENTS.md 的项目结构树（非 docs 内容）→ agents-tree-sync。 |
让项目文档跟随真实代码和已维护文档自动同步，避免 AGENTS.md / CLAUDE.md、docs/api/、docs/internals/、docs/ops/、docs/contributing.md 之间出现过期说明。
本 skill 不是要求每次改代码都重写全部文档，而是要求在相关契约变化时做最小必要同步。
在以下情况必须使用本 skill：
AGENTS.mddocs/api/、docs/internals/、docs/ops/、docs/contributing.md 下的文档以下情况一般不需要同步文档：
按变更内容选择对应文档，不要无差别更新所有文件。
| 变更内容 | 必查文档 |
|---|---|
| Agent 入口、阅读路径、文档目录职责 | AGENTS.md |
| 项目目录、核心文件、Skill 列表 | docs/internals/project_structure.md |
| 解析器抽象、PDF 后端、解析器选择策略 | docs/internals/file_parser.md |
| 分片策略、Chunk 结构、切分流水线 | docs/internals/chunking.md |
| 向量化、嵌入、Qdrant、向量存储编排 | docs/internals/vectorization.md |
| 命名规则、配置规则、数据库初始化来源 | docs/internals/naming_conventions.md |
| API 路由、请求/响应、MQ 消息契约 | docs/api/http_contracts.md |
| 错误码、异常类型、失败通知语义 | docs/api/error_codes.md |
| ORM、Pydantic、数据库表字段、核心业务模型 | docs/api/schemas/mysql.md |
| 当前 feature 的 brief / acceptance / 技术方案 / 实施报告 | .specs/<feature>/ |
docs/README.md 的入口。docs/ 核心目录或 Skill，同时检查 docs/internals/project_structure.md。rg 或 git diff 检查是否仍有旧名称、旧 topic、旧路径或旧字段残留。.env、密钥、Token、真实账号密码或服务器私密凭据。AGENTS.md 重新膨胀成完整知识库；它只保留入口和阅读路径。.specs/<feature-name>/implementation_report.md（合并后清理）。migrations/db.sql（0001 baseline）、scripts/db/init.sql（当前完整结构快照）、src/config.py、.env.example 和当前文档为准。三者按「同一改动的不同层面」分工，本 skill 是落到文档纸面、真正改写的一层：
| 层面 | skill | 回答的问题 | 产物 |
|---|---|---|---|
| 文档层（本 skill） | doc-maintenance-sync | 文档内容是否已落后于代码现状？ | 实际改写后的文档 |
| 结构层 | contract-guard | 结构/语义变了没有？破坏对端没有？该同步哪些契约文档？ | 判定 + 同步清单（不改文档） |
| 值层 | config-contract-sync | 同一个值在 .env/代码/Java 多处取值是否逐字相等？ | 取值对照表 + 统一方案 |
contract-guard 判定并产出「必须同步的契约文档清单」→ 本 skill 据清单逐篇改写。AGENTS.md 的「当前项目结构」树（目录增删移名），不涉及 docs 内容 → 转 agents-tree-sync。src/models/** → schemas/mysql.md + migration 等）见 CLAUDE.md §6，本 skill 执行其中的文档侧改写。最终回复需说明：