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/supabaseask-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 图回答架构问题。技能开篇明确定义了两项工作查证既有文档化知识——在开始前先检索 apps/docs 应用已有的架构、取舍、陷阱与历史决策记录而不是靠冷读代码重新推导预判评审反馈——在提交 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→ VercelLLM/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 提供的索引表路径均已转换为仓库根相对路径文件内容reference/adding-features.md为apps/docs添加功能的最佳实践先盘点既有代码、选择最小可行形态、复用管线。reference/docs-app-direction.md重构愿景与工作规范——新工作应与之对齐。reference/known-issues.md损坏、脆弱或变动中系统的活清单在依赖任何东西前先查它联邦文档、搜索、Sentry、reference 页面架构。reference/app-map.md架构速查表——目录结构、MDX 运行时 markdown 导出双管线模型、标题/排版契约、遥测、lint 入口。reference/build-pipeline.md通过 Turborepo pnpm 生命周期构建apps/docs的步骤——codegen、prebuild、postbuild、Vercel 部署内含 Mermaid 图。reference/llm-agent-surface.md受众路由、llms.txt、内容协商、批量导出。reference/llm-agent-parity.mdHTML↔markdown 保真度如 AI prompts、搜索注意事项、Agent 上手指南、变动中的接线。reference/federated-docs.md构建时如何从外部仓库拉取 markdown路由、pageMap、remark/rehype 插件、链接变换与已知失败模式。reference/ci-and-lint.md每个 PR 上的 GitHub Actions——docs_lint、Docs Tests、typecheck、prettier、Vercel preview 门槛新增检查前先看现有检查能否吸收。reference/management-api-reference.mdManagement API OpenAPI → reference 生成含 scoped PAT 权限表以及为何不替换为 Scalar/Redoc。reference/graphql-endpoint.mdapps/docs/resources/下的/api/graphql端点——按查询组织的目录、rootSchema.ts、connection/field 工具以及添加新顶级查询的步骤。reference/search-embeddings.mdscripts/search/中支撑searchDocs的 embeddings 管线——内容来源、处理流程、变更检测与page/page_section表。reference/gotchas.md需要警惕的具体陷阱每项一行。从这批文件可以看出知识组织策略每个主题一份独立短文可单独引用例如写代码时引用 adding-features.md 的Reuse pipelines, dont fork them来论证某条路由应走既有 markdown-schema 处理器而非另开旁路并刻意保持短小——SKILL.md 明确规定每份规范文件应控制在约250 行以内膨胀前先拆分只记录未来贡献者受益于知道的事实若从快速阅读代码即可看出的内容则不落纸。聊天中的四步用法SKILL.md 给出了在对话中实际使用这套知识的方法共四步先读adding-features.md与app-map.md——当问题触及设计取舍或不熟悉的代码路径时先读这两份它们刻意短小要完整读而不是扫读先验证再推荐——reference 内容可能滞后于真实代码行动前须用apps/docs/...下的实际文件核实文件路径、函数名或行为等凭记忆的断言引用原则而不只是规则——例如以 Peradding-features.md§ Reuse pipelines, dont fork them, this routes through the existing markdown-schema handler rather than introducing a side path. 这种形式给出论证依据善用 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.tsMDX 中写作ContentListings idstorage-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 生命周期串起prebuildGraphQL codegen → reference codegen → 拷贝示例 →build:markdown生成 guides reference 的 markdown →build:gz-archive产出public/docs.tar.gz→next build→postbuildsitemap、upload-static-assets.sh上传静态资源到 R2。本地开发用pnpm devapps/docs目录内监听 http://localhost:3001/docs社区贡献者需在.env设置NEXT_PUBLIC_IS_PLATFORMfalse。这些内容解释了为什么在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/supabaseask-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 图回答架构问题。技能开篇明确定义了两项工作查证既有文档化知识——在开始前先检索 apps/docs 应用已有的架构、取舍、陷阱与历史决策记录而不是靠冷读代码重新推导预判评审反馈——在提交 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→ VercelLLM/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 提供的索引表路径均已转换为仓库根相对路径文件内容reference/adding-features.md为apps/docs添加功能的最佳实践先盘点既有代码、选择最小可行形态、复用管线。reference/docs-app-direction.md重构愿景与工作规范——新工作应与之对齐。reference/known-issues.md损坏、脆弱或变动中系统的活清单在依赖任何东西前先查它联邦文档、搜索、Sentry、reference 页面架构。reference/app-map.md架构速查表——目录结构、MDX 运行时 markdown 导出双管线模型、标题/排版契约、遥测、lint 入口。reference/build-pipeline.md通过 Turborepo pnpm 生命周期构建apps/docs的步骤——codegen、prebuild、postbuild、Vercel 部署内含 Mermaid 图。reference/llm-agent-surface.md受众路由、llms.txt、内容协商、批量导出。reference/llm-agent-parity.mdHTML↔markdown 保真度如 AI prompts、搜索注意事项、Agent 上手指南、变动中的接线。reference/federated-docs.md构建时如何从外部仓库拉取 markdown路由、pageMap、remark/rehype 插件、链接变换与已知失败模式。reference/ci-and-lint.md每个 PR 上的 GitHub Actions——docs_lint、Docs Tests、typecheck、prettier、Vercel preview 门槛新增检查前先看现有检查能否吸收。reference/management-api-reference.mdManagement API OpenAPI → reference 生成含 scoped PAT 权限表以及为何不替换为 Scalar/Redoc。reference/graphql-endpoint.mdapps/docs/resources/下的/api/graphql端点——按查询组织的目录、rootSchema.ts、connection/field 工具以及添加新顶级查询的步骤。reference/search-embeddings.mdscripts/search/中支撑searchDocs的 embeddings 管线——内容来源、处理流程、变更检测与page/page_section表。reference/gotchas.md需要警惕的具体陷阱每项一行。从这批文件可以看出知识组织策略每个主题一份独立短文可单独引用例如写代码时引用 adding-features.md 的Reuse pipelines, dont fork them来论证某条路由应走既有 markdown-schema 处理器而非另开旁路并刻意保持短小——SKILL.md 明确规定每份规范文件应控制在约250 行以内膨胀前先拆分只记录未来贡献者受益于知道的事实若从快速阅读代码即可看出的内容则不落纸。聊天中的四步用法SKILL.md 给出了在对话中实际使用这套知识的方法共四步先读adding-features.md与app-map.md——当问题触及设计取舍或不熟悉的代码路径时先读这两份它们刻意短小要完整读而不是扫读先验证再推荐——reference 内容可能滞后于真实代码行动前须用apps/docs/...下的实际文件核实文件路径、函数名或行为等凭记忆的断言引用原则而不只是规则——例如以 Peradding-features.md§ Reuse pipelines, dont fork them, this routes through the existing markdown-schema handler rather than introducing a side path. 这种形式给出论证依据善用 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.tsMDX 中写作ContentListings idstorage-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 生命周期串起prebuildGraphQL codegen → reference codegen → 拷贝示例 →build:markdown生成 guides reference 的 markdown →build:gz-archive产出public/docs.tar.gz→next build→postbuildsitemap、upload-static-assets.sh上传静态资源到 R2。本地开发用pnpm devapps/docs目录内监听 http://localhost:3001/docs社区贡献者需在.env设置NEXT_PUBLIC_IS_PLATFORMfalse。这些内容解释了为什么在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考