How to Make AI Coding Agents Understand Your API Gateway

AI coding agents are writing more code than ever, but they’re doing it with stale training data. If you’re using Zuplo, that means agents will generate config that doesn’t match your installed version, reference deprecated policies, or guess at handler signatures. The fix is surprisingly simple: give the agent the right docs at the right time.

Zuplo now ships version-matched documentation inside the zuplo npm package, and an AGENTS.md file at the root of your project points agents to those docs instead of whatever they remember from training.

The problem with training data

Every AI coding agent has a knowledge cutoff. Zuplo ships new policies, handlers, and configuration options regularly. When an agent writes Zuplo code from memory, it might:

• Use a policy name that was renamed two versions ago
• Generate a handler signature that doesn’t match the current API
• Miss configuration options that didn’t exist when the model was trained

The AGENTS.md convention (now adopted by over 60,000 repositories and governed under the Linux Foundation’s Agentic AI Foundation) gives you a standard way to redirect agents to your project’s actual documentation.

How Zuplo implements this

When you install the zuplo package, full documentation lands in node_modules/zuplo/docs/. The structure covers everything an agent needs:

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

No network requests needed. The docs always match your installed version. When agents like Claude Code, Cursor, or Copilot start a session, they automatically read the AGENTS.md file and know where to look before writing any code.

Getting started

New projects

If you’re starting fresh, everything is set up for you:

npx create-zuplo-api@latest

This generates AGENTS.md and CLAUDE.md automatically. No extra steps.

Existing projects

Make sure you’re on zuplo version 0.66.0 or later, then add two files to your project root.

AGENTS.md contains the core instruction:

# 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 so Claude Code users get the same instructions without duplication:

@AGENTS.md

That’s it. The AGENTS.md file is intentionally minimal. Its only job is to redirect agents from stale training data to accurate, local documentation.

Go deeper with agent skills

The bundled docs handle reference lookups well, but for more structured, task-specific guidance, you can install Zuplo’s official agent skills.

Agent skills are an open standard (originally created by Anthropic, now adopted by 26+ platforms) for packaging procedural knowledge into portable folders that agents load on demand. Where AGENTS.md says “look up the docs,” skills say “here’s exactly how to do this task, step by step.”

Zuplo publishes skills for the most common workflows:

Install them from GitHub:

npx skills add zuplo/tools

Or via .well-known discovery:

npx skills add https://zuplo.com/

Once installed, agents automatically load the relevant skill when they encounter a matching task. An agent setting up a new project loads zuplo-project-setup. An agent configuring rate limiting loads zuplo-policies. No manual invocation needed.

Optional: Add the Zuplo Docs MCP Server

For real-time search and Q&A across all Zuplo documentation (not just the version-matched bundle), you can add the Zuplo docs MCP server.

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

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

The MCP server is optional. The bundled docs and skills cover most use cases without any network dependency. The MCP server adds broader search when you need to look beyond your installed version’s documentation.

Putting it all together

You have three layers of agent support, and they stack:

1. Bundled docs are always there. Install zuplo, add AGENTS.md, and agents get version-matched reference docs with zero network overhead.
2. Agent skills add task-specific guidance. Install from zuplo/tools and agents get step-by-step workflows for setup, policies, handlers, monetization, and more.
3. The MCP server adds live search. Configure it once and agents can query across all Zuplo documentation in real time.

Start with the bundled docs. They solve the most common problem (stale training data) with the least effort. Add skills when you want agents to handle multi-step workflows reliably. Add the MCP server if you need broader documentation search.