# 指导文档的两种呈现

指导文档共用一份内容。每篇都有独立网页 URL，后面加 `/index.md` 就是 Markdown 版本：

| 网页 | Markdown |
| --- | --- |
| `/` | `/index.md` |
| `/skills` | `/skills/index.md` |
| `/skills/shadow-puppet` | `/skills/shadow-puppet/index.md` |
| `/skills/shadow-puppet/prompt` | `/skills/shadow-puppet/prompt/index.md` |
| `/skills/image-delivery` | `/skills/image-delivery/index.md` |

这里的 skills 指指导文档，不要求使用外部技能包规范，也不要求先从某个 SKILL.md 进入。旧 `/agent`、`/agent/index.md`、`/tools/skills/...`、`/skills/<name>/SKILL.md` 和 `<doc>.md` 地址兼容保留。

`src/content/skills/guidance.ts` 是全局平面文档注册表。路径是文档的稳定标识；分组只用于浏览，不隔离引用。已有两套文档继续从 catalog 读取内容，注册表为它们生成成对 URL、共享资源引用和反向引用；新增独立文档直接注册唯一 path，无需归属某个技能。

网页正文的文档链接进入网页，Markdown 正文的文档链接进入 Markdown。图片和 API 继续使用原始资源地址。复制按钮复制当前这一篇的 Markdown 地址，每页 HTML head 也声明对应地址。反向引用从正文链接计算，两种呈现显示相同关系。

共用的 image-delivery 文档由 street-people/checks 和 shadow-puppet/delivery 引用，同时链接回各自的具体验收协议。它证明引用可以跨分组，不复制内容。