For AI agents

Agent SkillsCopy Anchor Link

The package ships Agent Skills that teach coding agents the conventions in these docs:

Install them with the skills CLI, which supports Cursor, Claude Code, Codex, OpenCode and most other agents:

npx skills add ScaleDockHQ/better-supabase
npx skills add ScaleDockHQ/better-supabase --skill better-supabase -a cursor

That installs the skills from the main branch. To install the ones that match the version in your lockfile, use the CLI:

pnpm better-supabase skills install                 # into the agent folders the project has
pnpm better-supabase skills install --agent cursor,claude
pnpm better-supabase skills install --check         # in CI, after upgrading

Skills go to .cursor/skills, .claude/skills or .agents/skills, or to your home directory with --global. Reinstall after an upgrade, and --check tells you when they are stale. --from <dir> installs skills from a folder instead of the package, to try a change before you publish it.

To give your users' agents a way into your app, add an MCP server that runs as the signed-in user; the Supabase library MCP blocks guide covers the Supabase library's MCP server and headless app blocks.

Supabase's own MCP server is a different tool: it administers a project (SQL, migrations, logs, docs search) for the people who run it. Connect an agent to it with supabaseMcp, or serve it from your app behind your own auth with supabaseMcpHandler. Tools for your app's users belong in your own MCP server, where they run with RLS.

In Claude Code, the repository is also a plugin marketplace. The plugin installs the same skills and connects the docs MCP server:

/plugin marketplace add ScaleDockHQ/better-supabase
/plugin install better-supabase@better-supabase

The repository has a Cursor plugin manifest (.cursor-plugin/plugin.json) with the same skills and server.

These skills cover better-supabase. For Supabase itself (Auth, Storage, RLS and Postgres performance), add Supabase's own skills too. The better-supabase skill's schema workflow already asks for RLS, policies and Data API grants on every new table; Supabase's skills explain the policies in depth:

npx skills add supabase/agent-skills

Docs as MarkdownCopy Anchor Link

• /llms.txt is an index of every page with absolute links to their Markdown, grouped by the sidebar sections, and /llms-full.txt is every page as one Markdown file. Both also answer under /docs: /docs/llms.txt and /docs/llms-full.txt.
• Every page is also Markdown at its own URL plus .md, for example /docs/repository/filtering.md, and the docs home is /docs.md. Requests with Accept: text/markdown get the same content at the normal URL, and each page links its Markdown with <link rel="alternate" type="text/markdown">.
• Callouts, steps, cards, tabs and prop tables come out as plain Markdown (blockquotes, numbered headings, link lists and tables), not as JSX.
• An unknown docs URL answers 404, so an agent can tell a missing page from a real one.

Docs MCP serverCopy Anchor Link

https://bettersupabase.com/mcp is a read-only MCP server (Streamable HTTP) with three tools: search_docs runs a full-text search over the pages and their headings, get_page returns one page as Markdown, and list_pages returns the whole index. It speaks the 2026-07-28 revision and answers 2025 clients statelessly, takes no token and never sees your project. Install it in one click in Cursor or VS Code, or add it to Cursor by hand:

{
  "mcpServers": {
    "better-supabase-docs": { "url": "https://bettersupabase.com/mcp" }
  }
}

or to Claude Code with claude mcp add --transport http better-supabase-docs https://bettersupabase.com/mcp, or commit it for everyone on the project in .mcp.json, which Claude Code reads:

{
  "mcpServers": {
    "better-supabase-docs": {
      "type": "http",
      "url": "https://bettersupabase.com/mcp"
    }
  }
}

Ask AI and browser agentsCopy Anchor Link

The Ask AI panel on every docs page answers from these docs. It searches the pages and reads the ones it needs before it answers, and shows each search and page it read.

In a browser with WebMCP, the docs pages register two read-only tools on document.modelContext: search_docs and read_page, which returns a page's Markdown. A browser agent can call them without reading the rendered page.

What agents should rely onCopy Anchor Link

• Types come from generated code. After a migration, run better-supabase gen and fix the errors instead of casting.
• Repository calls return a Result. Check result.ok or return the Result from a handler.
• Every JSON output of the CLI has a $schema URL, and --check flags exit with 1 on drift, so agents can verify their own changes.
• better-supabase doctor reports security and performance findings with stable codes, so an agent can fix them one by one and rerun it.
• Claims follow one contract: the active tenant in tenant_id (the claims block renames it), memberships as { scope, id, roles }, and plan features in features. Roles, memberships and the tenant never come from user_metadata or from request input. When the config has an authorization provider whose hook owns memberships, don't add the tenant SQL module (authorization providers).