Official agent skill

Ask The Docs

by supabase in supabase/supabase

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…

OfficialApache-2.0Auto-check passedDocuments & Office

Install Ask The Docs

skills CLI
$ npx skills add supabase/supabase --skill ask-the-docs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install supabase/supabase ask-the-docs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/supabase/supabase.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/ask-the-docs .claude/skills/ask-the-docs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ask-the-docs
GitHub stars
111k
Token cost
~2.4k tokens
SKILL.md length
813 words
Files
14
Skills in repo
22
Repo updated
First seen
Licence
Apache-2.0

At a glance

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…

  • Works in 2 steps: Look up what's already documented about… → Pre-empt review feedback by applying the…
  • The user asks how does X work in the docs app?
  • SKILL.md covers When to invoke, Answering with diagrams, Reference files and How to use during a chat, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Ask The Docs is an agent skill from supabase/supabase, published by the product's own GitHub organization. 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…

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 14 other files (for example `reference/adding-features.md`, `reference/app-map.md` and `reference/build-pipeline.md`).

It sits in Documents & Office, covering Markdown and CI/CD. It works with Supabase. The repository describes itself as: The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications. The licence is Apache-2.0.

When your agent uses it

  • The user asks how does X work in the docs app?
  • Where does Y live?
  • Is this approach OK for the docs app?
  • Before writing non-trivial changes under apps/docs/ — especially anything touching the MDX pipeline

Example prompts

  • “how does X work in the docs app?”
  • “where does Y live?”
  • “is this approach OK for the docs app?”
  • “/ask-the-docs”

Requirements

  • Docker

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. Look up what's already documented about the docs app —
  2. Pre-empt review feedback by applying the codebase-reuse /

What it can do on your machine

Read from SKILL.md and the folder at commit 0b85e0d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ask The Docs loads about 2.4k tokens when it runs. Until then it costs about 162 tokens; SKILL.md has 813 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~162
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from supabase/supabase at commit 0b85e0d, republished under its Apache-2.0 licence (© supabase). 813 words, ~2,393 tokens.

Download SKILL.mdSave it as .claude/skills/ask-the-docs/SKILL.md (or your agent's skills folder). This skill also uses 13 other files; get the full folder from GitHub.
name
ask-the-docs
description
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 with Mermaid diagrams when helpful.

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.

FileWhat's inside
reference/adding-features.mdBest-practices guidance for adding features to apps/docs. Inventory existing code first, pick the smallest viable shape, reuse pipelines.
reference/docs-app-direction.mdRefactoring vision and working norms — what new work should align with.
reference/known-issues.mdLiving list of broken, fragile, or in-flux systems. Check before depending on anything (federated docs, search, Sentry, reference-page architecture).
reference/app-map.mdArchitecture cheat sheet — directories, the two-pipeline (MDX runtime + markdown export) model, heading/typography contract, telemetry, lint entries.
reference/build-pipeline.mdTurborepo + pnpm lifecycle steps for building apps/docs — codegen, prebuild, postbuild, Vercel deploy. Mermaid diagram included.
reference/llm-agent-surface.mdAudience routing, llms.txt, content negotiation, bulk exports.
reference/llm-agent-parity.mdHTML↔markdown fidelity (e.g. AI prompts), search caveat, agent onboarding guides, in-flux wiring.
reference/federated-docs.mdHow docs pulls markdown from external repos at build time. Routes, pageMap, remark/rehype plugins, link transforms, known failure modes.
reference/ci-and-lint.mdGitHub Actions on every PR — Docs Tests, typecheck, prettier, Vercel preview gate. Where to add a check before creating a new one.
reference/management-api-reference.mdManagement API OpenAPI → reference generation, including scoped PAT permission tables; why not to swap in Scalar/Redoc.
reference/graphql-endpoint.mdThe /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.mdThe scripts/search/ embeddings pipeline behind searchDocs — content sources, processing flow, change detection, and the page / page_section tables.
reference/gotchas.mdSpecific traps to watch for. One-liner per item.
Show full SKILL.md (265 more words)Show less

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.

  • 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.

© supabase, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 13 other files in .agents/skills/ask-the-docs of supabase/supabase.

  • SKILL.md
  • reference/adding-features.md
  • reference/app-map.md
  • reference/build-pipeline.md
  • reference/ci-and-lint.md
  • reference/docs-app-direction.md
  • reference/federated-docs.md
  • reference/gotchas.md
  • reference/graphql-endpoint.md
  • reference/known-issues.md
  • reference/llm-agent-parity.md
  • reference/llm-agent-surface.md
  • reference/management-api-reference.md
  • reference/search-embeddings.md

Open the folder on GitHubat commit 0b85e0d

Compare with similar skills

Ask The Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ask The Docs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ask The Docs this skillsupabase/supabase111k—~2.4kAutomated safety check: PassApache-2.0
Take Doc Screenshotspgplex/pgconsole155—~841Automated safety check: PassApache-2.0
Triageflowershow/flowershow1.1k—~1.9kAutomated safety check: PassAGPL-3.0
Data Scraper Agentaffaan-m/ECC276k5 repos~6.3kAutomated safety check: NotesMIT
Data Scraper Agentaffaan-m/ECC276k1 repos~5.2kAutomated safety check: NotesMIT
Data Scraper Agentaffaan-m/ECC276k—~377Automated safety check: PassMIT

Similar skills

  • Take Doc Screenshots

    pgplex/pgconsole

    Take screenshots of the running pgconsole app for documentation.

    155 GitHub stars~841 tokensUpdated 1 mo ago
    DatabasesAuto-check passed
  • Triage

    flowershow/flowershow

    Automatically triage a newly opened GitHub issue — categorise it, verify the claim, and apply the right category and state so a maintainer or agent can pick it up.

    1.1k GitHub stars~1.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Data Scraper Agent

    affaan-m/ECC

    Build a fully automated AI-powered data collection agent for any public source — job boards, prices, news, GitHub, sports, anything.

    276k GitHub starsUsed in 5 repos~6.3k tokens
    DevOps & CloudAuto-check: notes
  • Data Scraper Agent

    affaan-m/ECC

    构建一个全自动化的AI驱动数据收集代理,适用于任何公共来源——招聘网站、价格信息、新闻、GitHub、体育赛事等任何内容。按计划进行抓取,使用免费LLM(Gemini Flash)丰富数据,将结果存储在Notion/Sheets/Supabase中,并从用户反馈中学习。完全免费在GitHub Actions上运行。适用于用户希望自动监控、收集或跟踪任何公共数据的场景。

    276k GitHub starsUsed in 1 repo~5.2k tokens
    DevOps & CloudAuto-check: notes
  • Data Scraper Agent

    affaan-m/ECC

    任意のパブリックソース(ジョブボード、価格、ニュース、GitHub、スポーツなど)用の完全自動化されたAI搭載データ収集エージェントを構築します。スケジュールでスクレイプし、無料LLM(Gemini Flash)でデータを豊かにし、Notion/Sheets/Supabaseに結果を保存し、ユーザーフィードバックから学習します。GitHub…

    276k GitHub stars~377 tokensUpdated 4 days ago
    DevOps & CloudAuto-check passed
  • Supabase CI Integration

    jeremylongshore/tons-of-skills-marketplace

    Configure Supabase continuous-integration and deployment pipelines with GitHub Actions: link projects, push migrations, deploy Edge Functions, generate types, and run tests against local Supabase…

    2.8k GitHub stars~2k tokensUpdated today
    DevOps & CloudAuto-check passed

More from supabase/supabase

All 22 skills in this repo
  • Official

    React composition patterns that scale. An agent skill from supabase/supabase.

    111k GitHub starsUsed in 58 repos~726 tokens
    Auto-check passed
  • Clickhouse Logs Queries

    supabase/supabase

    Official

    Write, review, and migrate Supabase logs queries against the ClickHouse-backed logs table (the logs.all.otel analytics endpoint).

    111k GitHub stars~2.4k tokensUpdated today
    Auto-check passed
  • Review The Docs

    supabase/supabase

    Official

    Review Supabase docs changes locally in your supabase/supabase checkout — either an open PR (triage, classify, verify) or your own branch before opening a PR (local self-review).

    111k GitHub stars~4.6k tokensUpdated today
    Auto-check passed
  • Vitest

    supabase/supabase

    Official

    Vitest API and config reference (Jest-compatible) — mocking with vi., spies, fake timers, coverage configuration, fixtures, snapshots, and test filtering.

    111k GitHub starsUsed in 12 repos~1.1k tokens
    Auto-check passed
  • Safe SQL Execution

    supabase/supabase

    Official

    A skill your agent uses whenever code will build, return, fetch, or execute SQL that runs against a user's real Postgres database — even when the request reads like an ordinary feature or bug fix…

    111k GitHub stars~4.2k tokensUpdated today
    Auto-check passed
  • Studio E2E Tests

    supabase/supabase

    Official

    Write and run Playwright E2E tests for Supabase Studio (e2e/studio).

    111k GitHub stars~2.8k tokensUpdated today
    Auto-check passed

Works with

Questions about Ask The Docs

What does Ask The Docs do?

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…. Ask The Docs is an agent skill from supabase/supabase, published by the product's own GitHub organization. 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.

When should I use Ask The Docs?

Ask The Docs fits situations like: the user asks how does X work in the docs app?; where does Y live?; is this approach OK for the docs app?; before writing non-trivial changes under apps/docs/ — especially anything touching the MDX pipeline.

How do I install Ask The Docs in Claude Code?

Run `npx skills add supabase/supabase --skill ask-the-docs -a claude-code`. Or copy the skill folder (.agents/skills/ask-the-docs in supabase/supabase) into .claude/skills/ask-the-docs in your project. Claude Code loads it when a task matches its description.

How do I install Ask The Docs in Codex?

Run `npx skills add supabase/supabase --skill ask-the-docs -a codex`. Or copy the skill folder (.agents/skills/ask-the-docs in supabase/supabase) into .agents/skills/ask-the-docs in your project. Codex loads it when a task matches its description.

Can I use Ask The Docs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add supabase/supabase --skill ask-the-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ask-the-docs, .gemini/skills/ask-the-docs, .github/skills/ask-the-docs and .opencode/skills/ask-the-docs in your project.

What does Ask The Docs need to run?

SKILL.md names no scripts, command-line tools or credentials: Ask The Docs is instructions for the agent only. Our summary lists: Docker.

Does Ask The Docs access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Ask The Docs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ask The Docs use?

Ask The Docs is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ask The Docs use?

About 2.4k tokens (SKILL.md is roughly 9.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ask The Docs?

Skills that share tags, products or a category with Ask The Docs: Take Doc Screenshots (pgplex/pgconsole, 155 stars), Triage (flowershow/flowershow, 1.1k stars), Data Scraper Agent (affaan-m/ECC, 276k stars) and Data Scraper Agent (affaan-m/ECC, 276k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ask The Docs?

supabase (a GitHub organization, an official publisher) maintains it in supabase/supabase, which has 111,256 GitHub stars. The repository holds 22 skills in this directory. The repository was last updated on October 9, 2026.

Source: supabase/supabase on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.