Zap is agent-native by design: every recipe is a portable skill directory with machine-readable frontmatter, and every CLI command emits structured JSON. Any agent that can run shell commands and read a URL can bootstrap a Zap project, author new recipes, and dispatch runs. This page walks through connecting each supported agent — Codex, Claude Code, Cursor, OpenClaw, Hermes, and any generic MCP-capable client — to the Zap skill registry and CLI.
This page focuses on the connection layer: how each agent finds Zap and executes it. For the agent behavioral contract (read SKILL.md first, keep spend opt-in, etc.), see Agent Setup. For the tools the Eve runtime exposes to agents, see Agent Overview. The Skill Download URLs
Every agent bootstraps from the same three endpoints. Point your agent at these before any other configuration:
| Endpoint | Purpose |
|---|
https://zap.wzrd.tech/api/skills | Full manifest of every registered skill (JSON). |
https://zap.wzrd.tech/api/skills/zap | Core Zap framework skill — recipe grammar, CLI usage, run contract. |
https://zap.wzrd.tech/api/skills/zap-authoring | Authoring skill — schema fields, prompt conventions, validation rules. |
https://zap.wzrd.tech/api/skills/{slug} | Any published recipe skill by slug. |
https://zap.wzrd.tech/api/skills/{slug}?format=json | Same skill as a structured JSON envelope. |
?format=json returns { skill, hash, files: [{ path, content }] } instead of raw Markdown — preferable for programmatic ingestion.
# Fetch the master manifest
curl -s https://zap.wzrd.tech/api/skills | jq
# Pull a specific skill as JSON
curl -s https://zap.wzrd.tech/api/skills/zap-authoring?format=json | jq
CLI Contract
All agents drive Zap through the same CLI. Two commands are enough for a full flow:
# Validate any recipe in the current project
npx @wzrdtech/zap@0.1.0 validate
# Run a recipe (defaults to mock — zero cost)
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json
--json so output is machine-parseable. The result envelope contains runId, status, zapUrl, and a per-step breakdown — no additional API is needed to observe progress.
Per-Agent Setup
Codex
Claude Code
Cursor
OpenClaw
Hermes
Generic MCP / other
OpenAI Codex CLI
Codex reads project instructions from AGENTS.md at the repo root. zap init writes this file automatically. To point Codex at the remote registry as well, add a zap section to your Codex configuration or paste the following into a session prompt:Use the Zap skills from https://zap.wzrd.tech/api/skills.
Read AGENTS.md and agent/skills/zap-authoring/SKILL.md before editing any Zap.md.
Validate with: npx @wzrdtech/zap@0.1.0 validate
Run mock with: npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json
Never pass --live without explicit user approval.
Anthropic Claude Code
Claude Code auto-loads AGENTS.md and CLAUDE.md from the workspace root. zap init writes AGENTS.md. For explicit registry access, add the following to .claude/settings.json or paste as a slash-command prompt:Zap project. Sources of truth:
- AGENTS.md
- agent/skills/zap/SKILL.md
- agent/skills/zap-authoring/SKILL.md
Remote registry: https://zap.wzrd.tech/api/skills
Before committing any recipe change, run:
npx @wzrdtech/zap@0.1.0 validate
npx @wzrdtech/zap@0.1.0 lint
Default provider is mock. Do not switch to gmi/fal without explicit user consent.
Cursor
Add a rule file at .cursor/rules/zap.mdc so every conversation in the workspace shares the same Zap context:---
description: Zap generative-video recipe conventions
globs: agent/skills/**, Zap.md, prompts/**
alwaysApply: true
---
Treat Zap.md frontmatter as executable metadata — do not move fields to prose.
Prompts live in `prompts/*.md` under each skill directory.
Default `defaults.provider: mock` for all scaffolded recipes.
Validate with `npx @wzrdtech/zap@0.1.0 validate` before committing.
Skill registry: https://zap.wzrd.tech/api/skills
agent/skills/.OpenClaw
OpenClaw treats each agent/skills/zap-*/ directory as a portable capability. Register the Zap workspace root in your OpenClaw agent config and point it at the reference docs:# openclaw.yaml
workspace:
root: ./
skills_dir: agent/skills
references:
- path: docs/reference/schema.md
- path: docs/reference/cli.md
- url: https://zap.wzrd.tech/api/skills
tools:
shell:
allow:
- "npx @wzrdtech/zap@0.1.0 validate"
- "npx @wzrdtech/zap@0.1.0 run *"
- "npx @wzrdtech/zap@0.1.0 status *"
agent/skills/ for SKILL.md files and enqueues CLI commands through the allow-listed shell tool.Hermes
Hermes uses a manifest-driven skill loader. Point it at the remote Zap skill manifest so it can hydrate the local agent/skills/ directory on first run:{
"skillSources": [
{ "type": "http", "url": "https://zap.wzrd.tech/api/skills" }
],
"cli": {
"validate": "npx @wzrdtech/zap@0.1.0 validate",
"run": "npx @wzrdtech/zap@0.1.0 run {recipe} --json",
"status": "npx @wzrdtech/zap@0.1.0 status {runId}"
},
"policies": {
"defaultProvider": "mock",
"requireExplicitLive": true
}
}
?format=json endpoint and writing files under agent/skills/.Any MCP-capable client
For any agent that isn’t listed above, provide these three pieces:
- Registry URL:
https://zap.wzrd.tech/api/skills
- CLI entry point:
npx @wzrdtech/zap@0.1.0
- Behavioral contract: the six rules in Agent Setup
The agent needs shell execution and HTTP fetch. No custom MCP server is required — the Zap CLI is itself the machine interface.Handshake Flow
Every supported agent follows the same startup sequence. If your agent isn’t listed above, replicate this flow:
Fetch the skill manifest
curl -s https://zap.wzrd.tech/api/skills
hash, path, and downloadUrl. Cache the manifest and diff against local agent/skills/ on subsequent starts to detect drift.Read the core framework skill
curl -s https://zap.wzrd.tech/api/skills/zap
Read the authoring skill before editing recipes
curl -s https://zap.wzrd.tech/api/skills/zap-authoring
Zap.md edit.Validate and run
npx @wzrdtech/zap@0.1.0 validate
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json
--live after the user has approved the quoted spend.Live-Run Handshake
When a creator asks for a real (paid) run, every agent must follow the same three-step handshake:
Show the quote
Run in mock first with --json and surface the quoteUsd field to the user. Do not proceed if the quote exceeds budget.cap_usd.
Confirm credentials are present
For CLI runs, verify GMI_API_KEY (or the required provider key) is exported. For web runs, verify the creator has connected a wallet and uploaded keys via Auth & Secrets. Dispatch with --live and capture the runId
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --live --json --input KEY=value
runId so status can be polled with zap status <runId> or GET /runs/<runId>.Never hardcode provider keys in a session prompt, agent config, or committed file. Store keys in the user’s shell environment (GMI_API_KEY), Supabase vault (for web runs), or a secrets manager — never in a .mdc, AGENTS.md, or JSON config that lives in the repo.
- Agent Setup — the behavioral contract every agent must follow.
- Agent Overview — Eve tools, pipeline grammar, and the primitive vs deterministic distinction.
- Providers — the seven BYOK secret types and provider routing.
- GMI Cloud (BYOK) — real live-run instructions for the primary video provider.
