Skill 文档 Manifest

docs/skill-docs.yml 是 skill 文档集成的唯一登记入口，记录发布来源、预期挂载位置和复核指纹。scripts/check_skill_docs.py 使用它校验接入状态；实际发布正文和导航由各子仓的 docs.manifest.yml 声明。

顶层字段

字段	类型	说明
schema_version	integer	manifest schema 版本。当前为 1。
description	string	manifest 用途说明。
skills	mapping	以 skill 名称为 key 的文档发布登记表。

Skill 条目字段

每个 skills.<name> 条目应包含：

字段	类型	说明
path	string	skill 子仓在主仓中的路径，例如 skills/ppt-deep-search。
mount	string	预期的文档挂载位置，例如 docs/skills/ppt-deep-search；当前同步脚本按子仓目录名固定生成该位置，不读取此字段来更改输出目录。
status	string	文档接入状态；当前登记中有 bootstrap 和 stable。此字段不控制同步或发布。
publish.mode	string	发布模式。当前使用 subrepo-manifest。
publish.entry	string	发布后的入口文档路径。
publish.skill_manifest	string	文档检查使用的子仓 manifest 路径；当前同步脚本固定读取子仓根目录的 docs.manifest.yml。
docs_review.source_fingerprint	string	文档来源复核指纹。
docs_review.reviewed_at	string	复核日期，格式为 YYYY-MM-DD。
docs_review.reviewed_by	string	复核人或复核 agent。
docs_review.note	string	复核说明。

发布模式

当前稳定发布模式为 subrepo-manifest。

在该模式下，主仓构建文档前运行 scripts/sync_skill_docs.py。脚本按 .gitmodules 中 skills/ 下的子仓路径发现 skill，读取每个子仓根目录的 docs.manifest.yml，将声明的页面同步到 docs/skills/<子仓目录名>/，并生成 Skills 索引和侧边栏。

当前同步脚本只检查 docs/skill-docs.yml 文件存在，不按其中的 mount、status 或 publish.skill_manifest 字段选择输出目录、过滤 skill 或更换 manifest 文件。登记信息应与上述实际路径保持一致。

同步后的 docs/skills/ 与 docs/public/skill-static/ 是生成产物，不应作为主仓手写源码维护。

指纹规则

docs_review.source_fingerprint 用来标记 skill 文档来源已被复核。相关文档来源变化后，应重新运行文档同步或复核流程，并刷新指纹。

发布站点的远端一致性由 publish-state.json 校验。该状态文件是构建产物，不应写回 docs/public/material-quality/ 作为源码。

示例

skills:
  ppt-deep-search:
    path: skills/ppt-deep-search
    mount: docs/skills/ppt-deep-search
    status: bootstrap
    publish:
      mode: subrepo-manifest
      entry: docs/skills/ppt-deep-search/index.md
      skill_manifest: docs.manifest.yml
    docs_review:
      source_fingerprint: sha256:...
      reviewed_at: "2026-06-04"
      reviewed_by: agent
      note: 已接入子仓 docs.manifest.yml，构建时从子仓同步文档。