Copy page

Development

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:

Code
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:

Code
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:

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 users get the same instructions without duplicating content:

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

Code
npx skills add zuplo/tools

Or via .well-known discovery:

Code
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:

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

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