ask-the-docs

Answer questions about the Supabase docs app (apps/docs) using documented architecture, build pipeline, and review-pattern notes, and apply feature-design principles (codebase reuse, coding minimalism) when proposing or critiquing changes. Use when the user asks "how does X work in the docs app?", "where does Y live?", "is this approach OK for the docs app?", or before writing non-trivial changes under apps/docs/ — especially anything touching the MDX pipeline, markdown generation, content components, federated docs, or contributor-facing authoring patterns. Can answer architecture questions w

Ask the docs-app librarian

A reference for apps/docs knowledge — architecture, build pipeline, federated docs, known fragilities — plus the feature-design principles the codebase rewards: understand and reuse the existing code before writing new code, and practice coding minimalism to keep the surface area small.

Two jobs:

Look up what's already documented about the docs app — architecture, tradeoffs, gotchas, prior decisions — instead of re-deriving from cold reads.
Pre-empt review feedback by applying the codebase-reuse / minimalism principles before opening a PR. Catches the "fix it in the next round" comments early.

When to invoke

User asks about apps/docs architecture, conventions, or behavior ("how does the markdown pipeline work?", "where do listings data files go?", "why does Troubleshooting have a .mjs utils file?").
User asks about LLM/agent consumption (llms.txt, markdown negotiation, searchDocs, bulk exports, agent onboarding guides, humans vs agents vs crawlers, AI prompt blocks in quickstarts).
About to write code under apps/docs/ that touches: MDX components, internals/markdown-schema/, generate-guides-markdown.ts, content data modules, the lint pipeline, telemetry events, contributor-facing snippets, federated routes, reference codegen, or Management API / OpenAPI reference pages.
Reviewing a docs-app PR and want a sanity check against the documented principles.

Not for: general Supabase docs content questions (use work-linear-issue, audit-quickstarts, etc.), or app-level work outside apps/docs/.

Answering with diagrams

Architecture and pipeline questions are often clearer with a diagram than with prose. Default to including a Mermaid diagram in answers about:

The MDX runtime vs markdown-export pipeline split.
Build flow (Turbo → pnpm prebuild / build / postbuild → Vercel).
LLM/agent consumption surface (llms.txt, negotiation, bulk exports).
Federated docs fetch flow.
CI / PR flow.
Component / data-registry relationships.
Management API OpenAPI → codegen → reference page flow.

Mermaid fences (`` ```mermaid `````) render natively on GitHub and most Markdown previewers. Several reference files already embed Mermaid; reuse or adapt them rather than re-deriving.

Keep diagrams small and one-topic. If a diagram needs more than a dozen nodes, split it.

Reference files

Short, focused docs under reference/. Read whichever apply to the task at hand — they cite each other where context matters.

File	What's inside
`reference/adding-features.md`	Best-practices guidance for adding features to `apps/docs`. Inventory existing code first, pick the smallest viable shape, reuse pipelines.
`reference/docs-app-direction.md`	Refactoring vision and working norms — what new work should align with.
`reference/known-issues.md`	Living list of broken, fragile, or in-flux systems. Check before depending on anything (federated docs, search, Sentry, reference-page architecture).
`reference/app-map.md`	Architecture cheat sheet — directories, the two-pipeline (MDX runtime + markdown export) model, heading/typography contract, telemetry, lint entries.
`reference/build-pipeline.md`	Turborepo + pnpm lifecycle steps for building `apps/docs` — codegen, prebuild, postbuild, Vercel deploy. Mermaid diagram included.
`reference/llm-agent-surface.md`	Audience routing, `llms.txt`, content negotiation, bulk exports.
`reference/llm-agent-parity.md`	HTML↔markdown fidelity (e.g. AI prompts), search caveat, agent onboarding guides, in-flux wiring.
`reference/federated-docs.md`	How docs pulls markdown from external repos at build time. Routes, `pageMap`, remark/rehype plugins, link transforms, known failure modes.
`reference/ci-and-lint.md`	GitHub Actions on every PR — `docs_lint`, `Docs Tests`, typecheck, prettier, Vercel preview gate. Where to add a check before creating a new one.
`reference/management-api-reference.md`	Management API OpenAPI → reference generation, including scoped PAT permission tables; why not to swap in Scalar/Redoc.
`reference/graphql-endpoint.md`	The `/api/graphql` endpoint under `apps/docs/resources/` — per-query folder layout, `rootSchema.ts`, connection/field utils, and the steps to add a new top-level query.
`reference/search-embeddings.md`	The `scripts/search/` embeddings pipeline behind `searchDocs` — content sources, processing flow, change detection, and the `page` / `page_section` tables.
`reference/gotchas.md`	Specific traps to watch for. One-liner per item.

How to use during a chat

Start by reading adding-features.md and app-map.md if the question touches design choices or unfamiliar code paths. They're small on purpose — read both, don't skim.
Verify before recommending. Reference content may lag behind the live code. Confirm with the actual files (apps/docs/...) before acting on remembered claims about file paths, function names, or behavior.
Cite the principle, not just the rule. "Per adding-features.md § 'Reuse pipelines, don't fork them', this routes through the existing markdown-schema handler rather than introducing a side path."
Reach for Mermaid when explaining architecture, flows, or relationships — see Answering with diagrams.

Updating the librarian

This skill lives in .agents/skills/ask-the-docs/ in supabase/supabase. When something in apps/docs changes in a way that makes a reference file inaccurate, or a generally-applicable lesson emerges from a PR review, open a pull request against this repo to update the relevant file, same as any other in-repo change.

Keep each canonical file under ~250 lines; split before they bloat. Capture only what a future contributor would benefit from knowing — if a fact is already obvious from a quick read of the live code, don't write it down.

Related skills

pm-the-docs — audience, stage, and cross-cutting scope calls (Frame stage of the "Write the docs" checklist, mirrored in pm-the-docs's reference file). Cross-repo product lookup (universe) lives there, not in this skill.
test-the-docs — execute docs snippets against a Docker-isolated local stack; verification report.
work-linear-issue — implementing assigned DOCS-* tickets.
review-the-docs — reviewing open docs PRs with type-specific verification.
audit-content-listings — batch conversion of overview pages to content listings.
create-pull-request — opening or updating a docs PR.