Statamic AI Gateway

Manage Statamic content through a tool execution gateway (composer require stokoe/ai-gateway).

Security Scan

The skill is internally consistent: it only needs a local sites.json (or env override) and curl/jq to call per-site AI gateway endpoints, which matches its stated purpose of managing Statamic sites via an execution gateway.

Purpose & Capability

Name/description (Statamic AI Gateway) align with the declared requirements: curl/jq and a sites registry containing base_url and token. Requested artifacts (sites.json and AI_GATEWAY_SITES_CONFIG) are exactly what you would expect for a gateway that proxies requests to multiple Statamic sites.

Instruction Scope

SKILL.md explicitly instructs the agent to read the configured sites.json, look up base_url and token, call /capabilities then /capabilities/{tool} before executing, and follow confirmation gates. The instructions do not ask the agent to read unrelated files or credentials; the only secret accessed is the declared sites.json. The guidance is narrow and discovery-first, which limits accidental misuse.

Install Mechanism

This is instruction-only and has no install spec or downloads, so nothing is written to disk by the skill itself. Required binaries (curl, jq) are standard and reasonable for the documented curl-based workflow.

Credentials

The skill asks for a single primary environment variable (AI_GATEWAY_SITES_CONFIG) and a local config path (~/.config/ai-gateway/sites.json) that stores site tokens. That is proportional to its purpose, but be aware this central registry stores bearer tokens that grant management access to each configured site; protecting that file and limiting what sites you add are important operational considerations.

Persistence & Privilege

always is false and the skill is user-invocable with normal autonomous invocation allowed. There is no attempt to modify other skills or persist beyond the documented sites.json; requested privileges are appropriate for operation.

Assessment

This skill appears to do what it says, but it centralizes per-site bearer tokens in a single local file. Before installing: (1) verify the GitHub homepage/author and that you trust the AI gateway addon running on each site; (2) store sites.json in a protected location and use chmod 600 as recommended; (3) add only sites you control or trust (a malicious site URL/token could be used to extract or modify content); (4) prefer short-lived or scoped tokens if the site supports them and rotate tokens if compromised; (5) keep the agent configured so that any confirmation-gated operations require interactive user approval (do not auto-confirm write operations). If you see any additional install scripts, code files, or requests for unrelated credentials (AWS keys, SSH keys, etc.), stop and re-evaluate — those would change this assessment.

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

Method	Path	Purpose
POST	/ai-gateway/execute	Execute a tool
GET	/ai-gateway/capabilities	List all tools and their enabled state
GET	/ai-gateway/capabilities/{tool}	Get full usage docs for a specific tool

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

Code	HTTP	Action
unauthorized	401	Check token in sites.json
forbidden	403	Target not in allowlist
tool_not_found	404	Check name against /capabilities
tool_disabled	403	Tool is off on this site
validation_failed	422	Read error.message and error.details
resource_not_found	404	Collection/entry/global/nav/taxonomy missing
conflict	409	Entry exists — use entry.upsert
rate_limited	429	Wait and retry
confirmation_required	200	Resend with confirmation_token (after user OK)
execution_failed	500	Retry or report
internal_error	500	Retry or report