Supabase 的 ask-the-docs 技能解析：为 apps/docs 代码库打造“文档图书管理员“式的 Agent 知识体系

Supabase 的 ask-the-docs 技能解析：为 apps/docs 代码库打造"文档图书管理员"式的 Agent 知识体系

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

ask-the-docs 是存放于.agents/skills/ask-the-docs/下的一个Agent 技能（Skill）定义，它把 Supabase 文档应用（apps/docs）的架构知识、构建管线与评审规范沉淀为一份可持续维护的知识包，供 Agent 在回答"docs app 里 X 是怎么工作的"、或在修改apps/docs/前快速查证与规避评审问题。读完本文，你将理解这套技能文件的前置元数据与正文结构、它引用的十余份参考文档如何分工，以及贯穿其中的两条核心设计原则——先理解并复用既有代码、践行编码极简主义——并能在自己维护大型文档代码库时复刻同样的组织方法。

技能定位：两个 Job

.agents/skills/ask-the-docs/SKILL.md在 frontmatter 中声明了技能的name与description：它回答的是关于 Supabase 文档应用本身的问题（使用文档化架构、构建管线与评审模式笔记），并在提出或评审改动时套用功能设计原则。当用户询问 "how does X work in the docs app?"、"where does Y live?"、"is this approach OK for the docs app?"，以及在apps/docs/下编写非平凡改动（尤其是触碰 MDX 管线、markdown 生成、内容组件、联邦文档与面向贡献者的写作模式）之前，应当启用该技能；在必要时，技能也允许用 Mermaid 图回答架构问题。

技能开篇明确定义了两项工作：

1. 查证既有文档化知识——在开始前先检索 apps/docs 应用已有的架构、取舍、陷阱与历史决策记录，而不是靠冷读代码重新推导；
2. 预判评审反馈——在提交 PR 前就套用 codebase-reuse / minimalism 原则，提前堵住"下一轮再修"的评审意见。

这两点共同指向一个现实：一个积累了大量历史面（surface area）的文档站点，任何新增文件、构建步骤、lint 任务或内容形态都是长期的维护成本，先查证再动手是最高效的路径。

何时调用（When to invoke）与适用边界

SKILL.md 给出的触发条件非常明确，大致覆盖四类场景：

• 用户询问apps/docs的架构、约定或行为，例如 "markdown 管线是怎么工作的?"、"listings 数据文件放在哪?"、"为什么 Troubleshooting 有一个.mjs工具文件?"；
• 用户询问 LLM/Agent 消费面，例如llms.txt、markdown 协商（negotiation）、searchDocs、批量导出、Agent 上手指南、人类 vs Agent vs 爬虫、quickstart 中的 AI prompt 区块；
• 准备在apps/docs/下编写涉及 MDX 组件、internals/markdown-schema/、generate-guides-markdown.ts、内容数据模块、lint 管线、遥测事件、面向贡献者的代码片段、联邦路由、reference 代码生成，或 Management API / OpenAPI reference 页面的代码；
• 评审一个 docs-app PR 时，希望对照文档化原则做一致性检查。

技能同时划定了"不适用"的边界：一般的 Supabase 文档内容问题（应使用work-linear-issue、audit-quickstarts等其他技能），以及apps/docs/之外的应用层工作。这个边界设计保证了技能体量克制、职责单一。

用 Mermaid 图回答架构问题

SKILL.md 规定：架构与管线类问题用图通常比用散文更清晰，因此默认在回答中附带 Mermaid 图，典型场景包括：

• MDX 运行时与 markdown 导出管线的拆分；
• 构建流（Turbo → pnpmprebuild/build/postbuild→ Vercel）；
• LLM/Agent 消费面（llms.txt、协商、批量导出）；
• 联邦文档拉取流；
• CI / PR 流；
• 组件 / 数据注册表关系；
• Management API OpenAPI → codegen → reference 页面流。

它给出的理由很实在：Mermaid 代码块（`````）在 GitHub 与多数 Markdown 预览器中原生渲染，且多个 reference 文件本身已内嵌 Mermaid 图，应复用或改编而非重新推导。同时约定：图要小而聚焦单一主题，超过约 12 个节点就应拆分——这与文档"极简主义"的主线一脉相承。

核心知识库：reference/ 下的 13 份参考文件

技能的主体知识并不写在 SKILL.md 正文里，而是放在.agents/skills/ask-the-docs/reference/下的一组"短小、聚焦"的文档中，按需读取、互相引用。SKILL.md 提供的索引表（路径均已转换为仓库根相对路径）：

从这批文件可以看出知识组织策略：每个主题一份独立短文，可单独引用（例如写代码时引用 adding-features.md 的"Reuse pipelines, don't fork them"来论证某条路由应走既有 markdown-schema 处理器而非另开旁路），并刻意保持"短小"——SKILL.md 明确规定每份规范文件应控制在约250 行以内，膨胀前先拆分，只记录"未来贡献者受益于知道"的事实，若从快速阅读代码即可看出的内容则不落纸。

聊天中的四步用法

SKILL.md 给出了在对话中实际使用这套知识的方法，共四步：

1. 先读adding-features.md与app-map.md——当问题触及设计取舍或不熟悉的代码路径时先读这两份，它们刻意短小，要完整读而不是扫读；
2. 先验证再推荐——reference 内容可能滞后于真实代码，行动前须用apps/docs/...下的实际文件核实文件路径、函数名或行为等凭记忆的断言；
3. 引用原则而不只是规则——例如以 "Peradding-features.md§ 'Reuse pipelines, don't fork them', this routes through the existing markdown-schema handler rather than introducing a side path." 这种形式给出论证依据；
4. 善用 Mermaid——解释架构、流程或关系时优先配图。

其中"验证优先"的设计值得注意：它承认文档（哪怕是本项目自己的技能文档）与代码之间存在漂移风险，把"以真实代码为准"写进了使用规范，这正是这套技能文件长期可用的关键。

原则落地：reference 文件中的仓库级证据

SKILL.md 反复强调的两条设计原则（代码复用 + 编码极简主义），在其引用的参考文件中都有更具体的落点，可以直接与apps/docs的真实架构对上：

双管线与共享数据注册表。按 app-map.md 的记载，同样的内容要渲染两次：一是 MDX 运行时，React 组件渲染<MyComponent id="..." />并经数据注册表读取数据输出 HTML；二是 markdown 导出，由apps/docs/internals/markdown-schema/下同名处理器把同一 JSX 序列化为纯 markdown。其"承重规则"是：两条管线解引用同一个数据注册表（典型如apps/docs/data/<topic>/index.ts导出的 ID 键控 map 与getById查找），组件与处理器读同一份数据，JSX prop 只是id——这样两个输出天然同步，无需并行数据形态。参考实作是ContentListings：数据注册表在apps/docs/data/content-listings/、运行时组件在apps/docs/components/ContentListings/、markdown 处理器在apps/docs/internals/markdown-schema/ContentListings.ts，MDX 中写作<ContentListings id="storage-get-started" />。

新增带 markdown 表示的组件时的固定步骤（来自 app-map.md）：先把 React 组件写在apps/docs/components/；再在internals/markdown-schema/<SameName>.ts添加同名处理器；然后在apps/docs/internals/generate-guides-markdown.ts的SCHEMA对象中注册；若某组件纯属视觉呈现、应从 markdown 中丢弃，则省略处理器——生成器会自动把未知 JSX 展开为其子内容。

从成本透镜看待每项改动。adding-features.md 把每次改动拆成"Reach（覆盖面，即用户可见价值）"与"Surface（表面积，即待维护的代码/配置/词汇量）"两个维度，好改动是"每单位 surface 产出最大 reach"。它把功能形态按优先级排成五个台阶——纯内容改动 → 配置既有组件 → 新建数据形态（*.data.ts）→ 组合既有原语的薄组件 → 在packages/ui/ui-patterns新增设计系统原语（最后手段）——越往下走越要写清楚理由。这解释了为何技能要求新改动先盘点MdxBase.shared.tsx的组件映射、internals/markdown-schema/的 schema 注册表、<$Partial path="..." />的content/_partials/复用块，以及supa-mdx-lint的扩展点，而不是另起炉灶。

方向文档的约束。docs-app-direction.md 定义了总体走向：docs 项目长期目标是只做文档（其他功能迁往子项目）、持续削减表面积、追求 markdown 导出与渲染页面的一对一保真。它同时提醒不要建立在已知的脆弱部件之上（搜索、Sentry 埋点、联邦链接处理均在变动中），这恰好与 known-issues.md 的存在意义相互呼应。

构建与本地开发的佐证

对于技能中提及的构建与 MDX 话题，build-pipeline.md 给出了完整图谱：根级turbo.jsonc的build依赖^build（先构建工作区依赖），而apps/docs/turbo.jsonc扩展该任务、让build同时依赖codegen:examples（把仓库根examples/拷入apps/docs/examples）与codegen:references（写入features/docs/generated/**），随后apps/docs/package.json的 pnpm 生命周期串起prebuild（GraphQL codegen → reference codegen → 拷贝示例 →build:markdown生成 guides + reference 的 markdown →build:gz-archive产出public/docs.tar.gz）→next build→postbuild（sitemap、upload-static-assets.sh上传静态资源到 R2）。本地开发用pnpm dev（apps/docs目录内，监听 http://localhost:3001/docs），社区贡献者需在.env设置NEXT_PUBLIC_IS_PLATFORM=false。这些内容解释了为什么在apps/docs下加新内容时要先问"既有 prebuild/postbuild 钩子是否已能覆盖"。

技能自身的维护机制

SKILL.md 还专门规定了这个技能包如何自我更新：它位于supabase/supabase仓库的.agents/skills/ask-the-docs/，当apps/docs的变动使某份 reference 文件失真，或评审 PR 中涌现出普遍适用的经验时，应对本仓库开 PR 更新相应文件（与任何仓库内改动一致）。维护约束包括：每份规范文件保持在约 250 行以内、膨胀前拆分；只记录未来贡献者会受益的内容，若从快速阅读代码即可看出的事实则不必写下。这保证该知识库自身不成为新的维护负担——它示范了"知识包本身也要应用极简主义"。

在技能生态中的位置

SKILL.md 在 "Related skills" 一节列出它在整个 Agent 技能体系中的邻接关系（相关技能位于.agents/skills/下）：pm-the-docs负责受众、阶段与跨切面范围决策以及跨仓库的产品查询；test-the-docs在 Docker 隔离的本地栈上执行文档片段并产出验证报告；review-the-docs按类型化验证方式评审公开的 docs PR。加上 SKILL.md 明确"不用于一般文档内容问题"、把内容类与实现类问题在技能层面做了隔离。若你想在 Supabase 仓库中为某个大型应用建立类似的"图书管理员"，可直接对照.agents/skills/ask-the-docs/的目录形态：一份带 frontmatter 的 SKILL.md 做入口与索引，一组 ≤250 行的 reference 短文做按需加载的深度知识，外加"先查证、先引用既有管线、小而单主题的 Mermaid 图"三条使用铁律。

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase