ask-the-docs

bởi supabase

Trả lời các câu hỏi về ứng dụng tài liệu Supabase (apps/docs) bằng cách sử dụng kiến trúc được ghi chép, quy trình build và các ghi chú về mẫu đánh giá, đồng thời áp dụng thiết kế tính năng…

npx skills add https://github.com/supabase/supabase --skill ask-the-docs

Tải ZIP GitHub

108.4k

Dùng thử kỹ năng nàyĐược tài trợ

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, Cursor, 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 download → Redocly bundle → codegen → `ApiEndpointSection`; why not to swap in Scalar/Redoc.
`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).
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.