# Set up your Zuplo project for AI coding agents

Zuplo ships version-matched documentation inside the `zuplo` npm package,
allowing AI coding agents to reference accurate, up-to-date APIs and patterns.
An `AGENTS.md` file at the root of your project directs agents to these bundled
docs instead of their training data.

## How it works

When you install `zuplo`, the full Zuplo documentation is bundled at
`node_modules/zuplo/docs/`. The bundled docs cover policies, handlers, concepts,
guides, CLI reference, and more:

```txt
node_modules/zuplo/docs/
├── concepts/          # Core concepts (request lifecycle, project structure)
├── policies/          # Policy catalog, per-policy docs and JSON schemas
├── handlers/          # Handler docs (URL forward, custom handler, etc.)
├── articles/          # Guides (CORS, env vars, auth, deployment, etc.)
├── cli/               # CLI reference
├── dev-portal/        # Developer portal / Zudoku docs
├── guides/            # Step-by-step guides
└── programmable-api/  # Programmable API reference
```

This means agents always have access to docs that match your installed version
with no network request or external lookup required.

The `AGENTS.md` file at the root of your project tells agents to read these
bundled docs before writing any code. Most AI coding agents — including Claude
Code, Cursor, GitHub Copilot, Windsurf, and others — automatically read
`AGENTS.md` when they start a session.

## Getting started

### New projects

When you create a new project with `create-zuplo-api`, the `AGENTS.md` and
`CLAUDE.md` files are generated automatically. No additional setup is needed:

```bash
npx create-zuplo-api@latest
```

### Existing projects

Ensure you are on `zuplo` version `0.66.0` or later, then add the following
files to the root of your project.

`AGENTS.md` contains the instructions that agents read:

```md title="AGENTS.md"
# Zuplo: ALWAYS read docs before coding

Before any Zuplo work, find and read the relevant doc in
`node_modules/zuplo/docs/`. Your training data may be outdated — the bundled
docs are the source of truth.
```

`CLAUDE.md` uses the `@` import syntax to include `AGENTS.md`, so
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) users get the same
instructions without duplicating content:

```md title="CLAUDE.md"
@AGENTS.md
```

## Understanding AGENTS.md

The default `AGENTS.md` contains a single, focused instruction: **read the
bundled docs before writing code**. This is intentionally minimal — the goal is
to redirect agents from stale training data to the accurate, version-matched
documentation in `node_modules/zuplo/docs/`.

The bundled docs include guides, API references, policy schemas, and handler
documentation. When an agent encounters a task involving routing, policies,
authentication, rate limiting, or any other Zuplo feature, it can look up the
correct configuration in the bundled docs rather than relying on potentially
outdated training data.

You can add your own project-specific instructions to `AGENTS.md` or `CLAUDE.md`
alongside the Zuplo defaults.

## Install official skills

For a richer experience, install the official
[Zuplo agent skills](https://github.com/zuplo/tools). Skills provide
specialized, task-specific guidance that goes beyond general documentation
lookup — they teach agents how to set up projects, configure policies, write
handlers, set up monetization, and more.

### What are agent skills?

[Agent skills](https://agentskills.io) are structured instruction files that AI
coding agents load automatically. Each skill focuses on a specific domain and
includes step-by-step guidance, code patterns, and references to documentation.

### Available skills

| Skill                   | Description                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **zuplo-guide**         | Comprehensive gateway guide — documentation lookup, request pipeline, route/policy configuration, custom handlers.   |
| **zuplo-project-setup** | Step-by-step new project setup — scaffolding, routes, auth, rate limiting, CORS, env vars, deployment.               |
| **zuplo-policies**      | Policy configuration — built-in policy catalog, custom code policies, wiring policies to routes.                     |
| **zuplo-handlers**      | Request handlers — URL forwarding/rewriting, redirects, custom TypeScript handlers, Lambda, WebSockets, MCP servers. |
| **zuplo-monetization**  | API monetization — meters, plans, Stripe billing, subscriptions, usage tracking.                                     |
| **zuplo-cli**           | CLI reference — local dev, deployment, env vars, tunnels, OpenAPI tools, project management.                         |
| **zudoku-guide**        | Comprehensive Zudoku framework guide — setup, configuration, OpenAPI integration, plugins, auth, theming.            |

### Install skills

Install the skills from GitHub:

```bash
npx skills add zuplo/tools
```

Or via `.well-known` discovery:

```bash
npx skills add https://zuplo.com/
```

After installation, agents automatically load the relevant skills when working
in your project.

## Optional: Add the MCP server

For search and Q&A across all Zuplo documentation, you can also add the Zuplo
MCP server. This gives agents the ability to search docs and ask questions in
real-time.

For **Claude Code**, add to `.claude/settings.json`:

```json title=".claude/settings.json"
{
  "mcpServers": {
    "zuplo-docs": {
      "type": "http",
      "url": "https://dev.zuplo.com/mcp/docs"
    }
  }
}
```

:::tip

The MCP server is optional. The bundled docs in `node_modules/zuplo/docs/`
provide complete, version-matched documentation without any network requests.
The MCP server is useful for broader search and Q&A across all Zuplo
documentation.

:::

## Summary

There are three ways to give AI coding agents access to Zuplo documentation,
listed in priority order:

1. **Bundled docs** (recommended) — always available at
   `node_modules/zuplo/docs/`, version-matched, no setup required beyond
   `AGENTS.md`
2. **Agent skills** — install from [zuplo/tools](https://github.com/zuplo/tools)
   for task-specific guidance on project setup, policies, handlers,
   monetization, and more
3. **MCP server** — add the Zuplo docs MCP server for real-time search and Q&A