# For AI agents

> Agent Skills, llms.txt, Markdown pages and a docs MCP server that help coding agents use better-supabase correctly.

Source: https://bettersupabase.com/docs/for-ai-agents

## Agent Skills [#agent-skills]

The package ships [Agent Skills](https://agentskills.io) that teach coding
agents the conventions in these docs:

| Skill                     | Covers                                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `better-supabase`         | Queries, writes, Results, cursors, Temporal values, the codegen loop after a schema change, and upgrades                 |
| `better-supabase-api`     | Adapters, `allow` and `scopes`, REST resources, MCP tools, AI chat routes, jobs and their cleanup, idempotency, webhooks |
| `better-supabase-auth`    | Sessions, typed claims, OAuth clients and agents, `checkSession`, claim changes, authorization providers                 |
| `better-supabase-testing` | `asUser`, `signLocalJwt`, delegated-token tests, Temporal in tests, typed seeds, pgTAP, doctor in CI                     |

Install them with the [`skills`](https://skills.sh) CLI, which supports
Cursor, Claude Code, Codex, OpenCode and most other agents:

```bash
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:

```bash
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`. Set `skills: { agents: ["cursor", "claude"] }`
in the config to pick the folders without `--agent`. 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](/docs/frameworks/mcp) that runs as the signed-in user; the
[Supabase library MCP blocks guide](/docs/guides/supabase-blocks) covers the
Supabase library's MCP server and headless app blocks.

Supabase's own [MCP server](https://supabase.com/docs/guides/getting-started/mcp)
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`](/docs/ai-sdk/mcp#supabases-mcp-server), or serve it from your
app behind your own auth with
[`supabaseMcpHandler`](/docs/frameworks/mcp#supabases-mcp-server). 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](#docs-mcp-server):

```bash
/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](/docs/guides/data-api-grants) on every new table; Supabase's
skills explain the policies in depth:

```bash
npx skills add supabase/agent-skills
```

## Docs as Markdown [#docs-as-markdown]

* [`/llms.txt`](/llms.txt) is an index of every page with absolute links to
  their Markdown, grouped by the sidebar sections, and
  [`/llms-full.txt`](/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`](/docs/repository/filtering.md), and the
  docs home is [`/docs.md`](/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 server [#docs-mcp-server]

`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](cursor://anysphere.cursor-deeplink/mcp/install?name=better-supabase-docs\&config=eyJ1cmwiOiJodHRwczovL2JldHRlcnN1cGFiYXNlLmNvbS9tY3AifQ==)
or [VS Code](vscode:mcp/install?%7B%22name%22%3A%22better-supabase-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fbettersupabase.com%2Fmcp%22%7D),
or add it to Cursor by hand:

```json title=".cursor/mcp.json"
{
  "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:

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

## Ask AI and browser agents [#ask-ai-and-browser-agents]

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](https://webmachinelearning.github.io/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 on [#what-agents-should-rely-on]

* 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](/docs/extending/authorization-providers)).