AI Gateway — Agent Skill

Manage Statamic content through a safe, authenticated tool execution gateway. Supports managing multiple Statamic sites from a single agent installation.

Before first use, follow the setup in INSTALL.md. For the endpoint contract, see references/api.md.

Site Registry

Credentials are stored in ~/.config/ai-gateway/sites.json (override with AI_GATEWAY_SITES_CONFIG).

{
  "sites": {
    "marketing": { "base_url": "https://marketing.example.com", "token": "token-aaa..." },
    "docs": { "base_url": "https://docs.example.com", "token": "token-bbb..." }
  }
}

Look up base_url and token by site name before every request.

Endpoints

All requests require Authorization: Bearer {token}.

Discovery-First Workflow

Do not guess tool arguments. Always discover before executing:

1. GET /capabilities — see which tools are enabled on this site
2. GET /capabilities/{tool.name} — get the argument schema, validation rules, example request/response, allowed targets, denied fields, and behavioral notes for that tool
3. Use the returned information to construct your /execute request

This is the primary way to learn how to use any tool. The capabilities endpoints are the source of truth.

Request Envelope

{
    "tool": "tool.name",
    "arguments": { },
    "request_id": "optional-tracking-id",
    "idempotency_key": "optional-dedup-key",
    "confirmation_token": "optional-if-confirming"
}

Response Envelope

Success: { "ok": true, "tool": "...", "result": { ... }, "meta": { ... } }

Error: { "ok": false, "tool": "...", "error": { "code": "...", "message": "..." }, "meta": { ... } }

Rules

> ⛔ CRITICAL — Structured field values are READ-ONLY structures.

> Bard, Replicator, Grid, and similar fields store values as deeply nested ProseMirror/TipTap JSON. When reading these back from entry.get or global.get, you will see arrays of node objects with type, attrs, content, and marks keys.

>

> You MUST NOT alter the structure. Never add, remove, reorder, or rename nodes, attributes, or marks. You may only change the literal text strings inside leaf nodes — nothing else.

>

> To update a rich-text field: (1) fetch with entry.get/global.get, (2) change only text values, (3) send back structurally identical. Violating this corrupts content.

1. Look up base_url and token from sites.json before every request.
2. Discover before executing. Call /capabilities then /capabilities/{tool} before using any tool for the first time on a site.
3. Only call tools where enabled: true. Only target allowlisted resources. forbidden means off-limits.
4. data must be a JSON object, never an array or string. Don't send unknown argument keys.
5. Prefer entry.upsert over entry.create — safer and idempotent.
6. navigation.update is a full tree replacement. Always fetch with navigation.get first.
7. Confirmation-gated tools require user approval. If requires_confirmation: true in capabilities: (1) send the request, (2) receive confirmation_required with a token, (3) show the user the operation_summary and ask permission, (4) only if approved, resend with confirmation_token. Never auto-confirm.
8. If rate_limited, back off and retry.
9. Include the site name in request_id (e.g. marketing:upsert-about).
10. After bulk content changes, consider warming caches: stache.warm rebuilds content indexes, static.warm regenerates static pages.

Error Codes