AgentPlaybooks

One playbook, every agent. A portable operating environment for AI agents — persona, skills, MCP servers, project instructions, and memory in one source of truth.

Keep your agents yours. AgentPlaybooks stores skills, personas, MCP servers, project instructions, and memory in one portable playbook, so you can switch platforms, use several at once, or self-host without vendor lock-in.

Your agent setup stays in sync across Claude, ChatGPT, Cursor, Codex, Gemini, local models, and future platforms. The playbook is the portable source of truth—not any single vendor or editor.

It is not another skill store or MCP registry. Skills and MCP connections are parts of a playbook; the playbook is the whole job. That holds for agents with a body too: a skill can carry demonstrations, recordings of the task in the order a robot performs them.

Highlights

What a playbook holds

• Persona: 1 per playbook, stored directly on the playbook record
• Instructions: always-on project rules — the AGENTS.md / CLAUDE.md content
• Skills: SKILL.md documents in the Agent Skills format, frontmatter preserved across every client
• Skill attachments: bundled scripts, references, and templates, round-tripped by the CLI
• Demonstrations: recordings of a skill being performed — YouTube, a pinned URL, or a LeRobot dataset — with timestamped segments, for agents that learn by watching
• MCP servers: tools and resources in Model Context Protocol format
• Memory: key-value store with tags and descriptions, with a native Hermes memory provider
• Hermes Tools plugin: connect playbook skills, MCP/OpenAPI tools, and credentials
• Canvas: versioned markdown work documents, scoped to a playbook run, so several teams can execute the same playbook without sharing work products

Credentials, without handing them over

• Secrets vault: AES-256-GCM, per-user derived keys. Agents reference a secret by name and the platform injects it server-side (use_secret), so the value never enters an agent's context. Optional per-secret host allow-lists, and an expiry that is enforced: an expired secret is refused by every path that would use it.
• Federation: other MCP servers and OpenAPI services become tools on your playbook, with their credentials resolved from that same vault by name
• Audit trail: every federated call and every vault operation, refusals included

Getting it into your tools

• Claude: one plugin brings every playbook in your account into claude.ai, Claude Desktop, Cowork, Claude Code, and mobile, signing in with OAuth — no API key. Or add a single playbook as a custom connector. See AgentPlaybooks in Claude.
• Cursor and VS Code: one-click install links for the account or a single playbook — on each playbook's Integrations tab, and in MCP Integration.
• CLI + portable Agent Plugin: audit your local agent config, then sync one playbook to Claude Code, Cursor, ChatGPT/Codex, Google Antigravity, Grok Bot and Hermes
• Agent Plugins 1.0: install the project plugin or export a single playbook as plugin.json, mcp.json, and complete Agent Skills directories. Compatible MCP hosts can also discover hosted playbook skills through the MCP Skills extension.
• Private, versioned central backups are separate from installable plugin exports; packages contain no vault secret values.
• Publishing: a public playbook's skills are served as plain markdown over HTTP at /.well-known/skills/ — installable from a URL, no registry, no sign-up
• Export formats: Agent Plugin ZIP, JSON, OpenAPI, MCP, Anthropic, Markdown

Working with other people

• API keys: role-based access control (Viewer, Coworker, Admin)
• Team collaboration: one-time editor invites without sharing human credentials or agent API keys
• Explore: practical use cases, setup guidance, and curated AgentPlaybooks starters
• Sharing: public or unlisted playbooks; keep project context in private copies
• Theme: system-aware Light and Dark modes

Tech Stack

| Category | Technology | Purpose | | --- | --- | --- | | Framework | Next.js 16 + React 19 | App Router, SSR | | Styling | Tailwind CSS 4 | Utility-first CSS | | Animation | Framer Motion | UI animations | | Icons | Lucide React | Icon library | | API | Hono | Edge API routing | | Database | Supabase | Postgres + Auth + RLS | | i18n | next-intl | Localization (en, hu, de, es) | | Docs | Plain markdown in public/docs | Fetched and rendered client-side | | Hosting | Cloudflare Workers | Edge deployment | | Adapter | @opennextjs/cloudflare | Next.js on Workers |

Live Demo

• Website: https://agentplaybooks.ai — the canonical host; https://apbks.com is a short domain for links
• Docs: https://agentplaybooks.ai/docs
• Release distribution checklist: npm, MCP registry, plugin stores, skill discovery, Hermes memory, and verification
• GitHub: https://github.com/matebenyovszky/agentplaybooks

Getting Started

Prerequisites

• Node.js 22+ (engines in package.json; CI runs 22)
• npm 11+ — npm 10 writes a lockfile npm ci then rejects
• Supabase project
• Cloudflare account (optional for deployment)

Installation

git clone https://github.com/matebenyovszky/agentplaybooks.git
cd agentplaybooks
npm install

Starters

Portable playbooks under examples/ — persona, instructions, skills, MCP, memory, and vault in a tree you control. Small MIT examples you can clone or cp -R. Not a marketplace.

| Starter | One-liner | |---|---| | coding-agent-baseline | Coding-agent playbook: instructions, two skills, safe MCP stub | | doctor-drift-demo | Review playbook with host-folder drift; the portable store stays canonical | | skills-only-starter | Smallest playbook: three skills + instructions; no MCP | | cursor-hermes-starter | Playbook with persona, instructions, and skills for Cursor and Hermes hosts |

Install into a host (optional doctor check, then sync):

npx @agentplaybooks/cli@latest doctor examples/coding-agent-baseline
npx @agentplaybooks/cli@latest sync examples/coding-agent-baseline --target=claude,cursor --apply

See examples/README.md, the CLI docs, and the Agent Plugins spec.

Environment Variables

Create a .env.local file with:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Required for the secrets vault. 32 bytes as 64 hex characters:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Losing it means losing every stored secret — no vault operation can decrypt
# without it, and rotating it invalidates everything already encrypted.
SECRETS_ENCRYPTION_KEY=

Optional:

| Variable | Effect | | --- | --- | | NEXT_PUBLIC_APP_URL | The canonical origin used for canonical tags, the sitemap and robots. Defaults to https://agentplaybooks.ai. | | ALLOWED_ORIGINS | Comma-separated CORS allow-list. Replaces the hosted defaults entirely — set it on a self-hosted instance so the project's own domains are not trusted there. | | SECRETS_REQUIRE_ALLOWED_HOSTS | true makes a secret's host allow-list mandatory: an unpinned secret cannot be used for outbound requests at all. |

Development

npm run dev

Open http://localhost:3000

Cloudflare Deployment

npm run build:worker
npm run preview
npx wrangler deploy

CLI, ChatGPT/Codex Plugin, and Claude Code Plugin (packages/cli)

agentplaybooks doctor <project> audits local agent configuration (instructions, Agent Skills, custom agents, MCP servers, likely hard-coded secrets, drift) and agentplaybooks sync <project> creates the canonical agentplaybook.json plus the platform files missing from enabled targets: Claude Code, Cursor, ChatGPT/Codex, GitHub Copilot, Gemini CLI, Google Antigravity (.agents/skills), Grok Bot (.agents/skills, which it discovers natively alongside AGENTS.md), and Hermes Agent (.agents/skills registered in ~/.hermes/config.yaml, plus that file's mcp_servers: and SOUL.md). agentplaybooks plugin export|import round-trips Agent Plugins 1.0 packages; the only manifest extension carries secret references and bindings, never secret values. login / playbooks / pull / push synchronize skills, MCP servers, and the manifest with a hosted playbook using a user API key. push also creates a private, versioned cross-platform AI agent configuration backup, including complete Agent Skills folders and portable custom agents. backups lists revisions; pull --snapshot can recover an earlier one. Secret values never move, only references declared in spec.secrets. Mutating commands show a plan first and require --apply, --yes, or interactive confirmation where supported. See packages/cli/README.md and the backup and migration guide.

The same package is a ChatGPT/Codex and Cursor plugin (skill + account MCP). Exact API-key setup and installation commands are in packages/cli/README.md.

The Claude plugin is a separate, lean folder, plugins/agentplaybooks: the account MCP connector (OAuth, no key), a playbooks skill that works in chat and Cowork, and doctor / sync commands that run the published CLI through a pinned npx. It has no bin/ directory, because claude.ai and Cowork refuse a plugin that has one. Add it on claude.ai under Customize → Plugins → Add marketplace with matebenyovszky/agentplaybooks, or in Claude Code:

/plugin marketplace add matebenyovszky/agentplaybooks
/plugin install agentplaybooks@agentplaybooks

API Overview

Public and Unlisted playbook access

Public playbooks are visible to everyone. Unlisted playbooks are accessible via GUID but hidden from search.

GET /api/playbooks/:guid
GET /api/playbooks/:guid?format=openapi
GET /api/playbooks/:guid?format=mcp
GET /api/playbooks/:guid?format=anthropic
GET /api/playbooks/:guid?format=markdown

GET /api/playbooks/:id/personas
GET /api/playbooks/:id/skills
GET /api/playbooks/:guid/memory

Note: :id supports both UUID and GUID for personas and skills.

Authenticated playbook CRUD (session auth)

GET    /api/playbooks
POST   /api/playbooks
PUT    /api/playbooks/:id
DELETE /api/playbooks/:id

Personas (owner or editor)

POST   /api/playbooks/:id/personas
PUT    /api/playbooks/:id/personas/:pid
DELETE /api/playbooks/:id/personas/:pid

Skills (owner or editor)

POST   /api/playbooks/:id/skills
PUT    /api/playbooks/:id/skills/:sid
DELETE /api/playbooks/:id/skills/:sid

Memory writes (API key or owner)

PUT    /api/playbooks/:guid/memory/:key
DELETE /api/playbooks/:guid/memory/:key

Canvas work documents

Canvas documents belong to an isolated workflow run, so multiple teams can execute the same playbook without sharing work products. They are long-form markdown artifacts that agents can revise over time. Use memory for durable facts and structured state; use canvas for deliverables such as a PR review, res