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:

1. Look up what's already documented about the docs app — architecture, tradeoffs, gotchas, prior decisions — instead of re-deriving from cold reads.
2. 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.

How to use during a chat

1. 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.
2. 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.
3. 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."
4. 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.