> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Set up Claude Code, Codex, Cursor and other coding agents to write your Xano backend with the Xano SDK: install the agent skill, keep the managed AGENTS.md current, and point the agent at the SDK's own docs.

Your coding agent writes the backend: tables, endpoints, functions and AI agents in TypeScript
with the Xano SDK. Three things set it up to do that well:

* the **`xano-backend` agent skill**, which tells the agent when to set up a Xano backend;
* the **`AGENTS.md`** that `init` writes into every project, the agent's brief for that project;
* the **grounding files** shipped inside `@xano/sdk`, which the brief tells the agent to read
  before it writes code.

## Install the agent skill

The skill teaches an agent when a project needs a Xano backend, how to start one with `init`, and
where to read next. Install it once per machine. Outside a project:

```bash theme={null}
npx @xano/sdk agent-skill install
```

Inside a project that already depends on the SDK, run `npx xanosdk agent-skill install`.

`install` writes the skill into each coding agent it detects on this machine, by looking for the
agent's home config directory. It writes at most two copies:

| Agent | Reads the skill from |
| - | - |
| Claude Code | `~/.claude/skills/xano-backend/SKILL.md` (under `$CLAUDE_CONFIG_DIR` when that is set) |
| Codex, Cursor, Copilot, Gemini CLI, Amp, OpenCode | `~/.agents/skills/xano-backend/SKILL.md` |

To choose agents instead of relying on detection, pass `--agent` once per agent. It takes
`claude-code`, `agents` (the shared `~/.agents` directory), `codex`, `cursor`, `copilot`, `gemini`,
`amp` or `opencode`. When no agent is detected and none is named, `install` refuses.

`--dry-run` reports what would change and writes nothing:

```bash theme={null}
npx @xano/sdk agent-skill install --dry-run
```

```
✓ claude-code: created (dry run: nothing written)
  ~/.claude/skills/xano-backend/SKILL.md
✓ agents: created (dry run: nothing written)
  ~/.agents/skills/xano-backend/SKILL.md
```

### Keep it current

Each copy carries the SDK version it came from and a digest of its content. `status` reports each
copy as one of four states:

| State | Meaning | What `install` does |
| - | - | - |
| `current` | Matches this SDK version | Leaves it unchanged |
| `stale` | From an older SDK version, unedited | Rewrites it |
| `edited` | Changed since it was installed | Leaves it alone unless you pass `--force` |
| `absent` | Not there | Writes it |

```bash theme={null}
npx xanosdk agent-skill status
npx xanosdk agent-skill install --force   # replace an edited copy
npx xanosdk agent-skill uninstall         # remove the unedited copies install wrote
```

`uninstall` keeps an edited copy and reports it. A symlinked skill directory belongs to another
installer, and neither command touches it. Nothing prompts, so all three run unattended.

### Install without the CLI

The skill also installs from the public repository, without the SDK on your machine:

```bash theme={null}
npx skills add xano-sdk/sdk
```

In Claude Code, add the repository as a plugin marketplace and install the `xano` plugin:

```text theme={null}
/plugin marketplace add xano-sdk/sdk
/plugin install xano@xano-sdk
```

<Note>
  The agent skill is for the coding agent on your machine. It is not a `knowledge()` item. A
  `knowledge()` item is markdown that the AI agents running in your Xano backend read; see
  [AI agents and MCP servers](/build/ai-agents-and-mcp-servers#knowledge).
</Note>

## The managed AGENTS.md

`xanosdk init` writes an `AGENTS.md` at the project root: the brief a coding agent reads at the
start of a session, and the file the skill sends it to. It covers where the source of truth lives,
the development loop, how the frontend calls the backend, the rules for a backend change, env
values, tests, `xano/xano.lock`, and troubleshooting.

The SDK's part sits between two markers:

```md theme={null}
<!-- BEGIN:xanosdk-agent-rules -->
...
<!-- END:xanosdk-agent-rules -->
```

Everything outside the markers is yours and is never rewritten. Add your own project notes above
or below the block.

`init` takes two flags for it:

* `--no-agents-md` writes no `AGENTS.md`.
* `--ai <preset|none>` is for scripted callers. `--ai none` is the same as `--no-agents-md`. Any
  other value, an agent name, writes the same single `AGENTS.md` that every agent reads.

### How the block stays current

The block names the SDK version it was written for. When a command that compiles the backend runs
under a coding agent (`deploy` or `export`, for example) and the installed `@xano/sdk` is newer
than the block, the command rewrites the block and says so on stderr. It does this only when:

* the project already has an `AGENTS.md` with the block (it never creates the file or adds a
  block to a file that lacks one);
* the process is not in CI;
* a coding agent appears to be driving it.

`xanosdk upgrade` refreshes the block on purpose, CI or not. Pass `--no-refresh` to any command to
leave `AGENTS.md` alone. Runs that promise to write nothing (`--dry-run`, `export --check`,
`--frozen-lock`) never refresh it.

## What the agent reads

The brief tells the agent to read the SDK's own docs before writing code, because the API it
remembers from training is not this one. They ship inside the package, so they always match the
installed version:

| File | What it is |
| - | - |
| `node_modules/@xano/sdk/llms.txt` | The router: the mental model, the deploy contract, every cross-cutting gotcha, and a list of topic files with when to open each. Read in full. |
| `node_modules/@xano/sdk/llms/*.md` | Topic files: object kinds, statements, fields, filters, tests, triggers, errors and more. Open the one or two that match the task. |
| `node_modules/@xano/sdk/llms-full.txt` | The whole set in one file. |
| `node_modules/@xano/sdk/manifest.json` | Per-entry detail: a statement's full field schema, a filter's arguments, every CLI command and flag. Query one entry with `jq`; it is too large to read whole. |

The published `.d.ts` types carry the same surface with the compiler attached. For what this site
offers agents, see [Docs for agents](/ai/docs-for-agents).

## Drive the CLI from an agent

Commands print JSON when stdout is not a terminal (help and `version` stay text), and `--json`
forces it. An agent should
read the document and the exit code rather than parse the text output.

* A non-zero exit code says what kind of failure happened: 2 means the command ran but found a
  disagreement, 5 a failed test, 8 a backend that is gone, stopped or unreachable.
* A release write (`release create`, `promote`, `tenant deploy`) reports `completed` as yes, no or
  unknown. Unknown exits 9: the agent runs the command in `resolveWith` and does not retry blind.

The full table is in [Exit codes and outcomes](/help/exit-codes-and-outcomes). The brief also
tells the agent which commands to leave to you: `pull`, `promote`, `deploy --to workspace`,
`tenant deploy` and `local update` change shared environments or the pinned Engine, so it runs
them only when asked.

## Let the agent run the backend

The Xano Engine serves an MCP server, `xano-local`, that `init` connects to Claude Code and Cursor.
Through it the agent reads tables and rows, seeds data, and runs functions, endpoints and tests on
your local backend. A session that was already running when `init` wrote the config does not
load the server: restart the agent or reconnect its MCP servers. Setup and the other agents are on
[Engine MCP server](/run/engine-mcp).

<Note>
  You may meet three MCP servers while building with the Xano SDK:

  * **The Xano Engine's local server** (`xano-local`), which your coding agent uses to inspect and
    exercise the backend on your machine. See [Engine MCP server](/run/engine-mcp).
  * **MCP servers you author**, which Xano hosts as part of the backend you deploy. See
    [AI agents and MCP servers](/build/ai-agents-and-mcp-servers).
  * **This docs site's server** at `https://sdk.docs.xano.com/mcp`, which lets an agent search
    these pages. See [Docs for agents](/ai/docs-for-agents).
</Note>

## A first prompt

With the skill installed, open your coding agent in an empty folder and describe the app:

```text theme={null}
Build a backend for a team task tracker with Xano. Users sign up and log in.
Each task has a title, a status (todo, doing, done) and an assignee.
Add endpoints to list, create and update tasks, with tests,
and deploy it to the Xano Engine so I can try it.
```

The skill has the agent run `init`, deploy to the Xano Engine (no account needed), check the
project, then read `AGENTS.md` and `llms.txt` before it writes the tables and endpoints in `xano/`.
Leave Xano out of the prompt and the skill still recognizes a request for a backend, but the agent
asks before it sets one up. On a machine the Engine does not run on, the agent tells you and
deploys to an ephemeral instead, which needs a Xano account; see
[where the Engine differs today](/run/xano-engine#where-the-engine-differs-today).

## Next

* Run what the agent built: [The Xano Engine](/run/xano-engine).
* Keep the agent inside safe limits: [Agent guardrails](/govern/agent-guardrails).
* Give the agent these docs too: [Docs for agents](/ai/docs-for-agents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.