AgentPlaybooks

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: federated calls and vault operations (including refusals), plus configuration changes and memory/canvas writes, without copying secret values or document bodies into the log
• Audit evidence from the CLI: export JSONL/CSV, verify the per-playbook hash chain, and explicitly confirm retention purges with apb audit.

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, curated starters, and a searchable public playbook catalog
• Sharing: public or unlisted playbooks; keep project context in private copies
• Theme: system-aware Light and Dark modes

Self-hosting, security & audit

Keep agent configuration and credentials on your infrastructure, with controls you can inspect in the source. The Self-host page introduces the available features; the deployment guide covers setup.

See the audit guide, self-hosted mTLS guide, and security documentation for configuration, evidence, and limits. Forwarding is optional and best-effort; retention requires an operator-scheduled call. Hash chains provide tamper evidence, not a digital signature.

Tech Stack

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.gitcd agentplaybooksnpm 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.

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

npx @agentplaybooks/cli@latest doctor examples/coding-agent-baselinenpx @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.coNEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_keySUPABASE_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:

Development

npm run dev

Open http://localhost:3000

Cloudflare Deployment

npm run build:workernpm run previewnpx 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/:guidGET /api/playbooks/:guid?format=openapiGET /api/playbooks/:guid?format=mcpGET /api/playbooks/:guid?format=anthropicGET /api/playbooks/:guid?format=markdown
GET /api/playbooks/:id/personasGET /api/playbooks/:id/skillsGET /api/playbooks/:guid/memory

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

Authenticated playbook CRUD (session auth)

GET    /api/playbooksPOST   /api/playbooksPUT    /api/playbooks/:idDELETE /api/playbooks/:id

Personas (owner or editor)

POST   /api/playbooks/:id/personasPUT    /api/playbooks/:id/personas/:pidDELETE /api/playbooks/:id/personas/:pid

Skills (owner or editor)

POST   /api/playbooks/:id/skillsPUT    /api/playbooks/:id/skills/:sidDELETE /api/playbooks/:id/skills/:sid

Memory writes (API key or owner)

PUT    /api/playbooks/:guid/memory/:keyDELETE /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, research report, implementation plan, or draft that may be edited passage by passage.

GET    /api/playbooks/:guid/runsPOST   /api/playbooks/:guid/runsGET    /api/playbooks/:guid/canvas?runId=:runIdPOST   /api/playbooks/:guid/canvasGET    /api/playbooks/:guid/canvas/:slug?runId=:runIdPUT    /api/playbooks/:guid/canvas/:slug?runId=:runIdPATCH  /api/playbooks/:guid/canvas/:slug?runId=:runIdDELETE /api/playbooks/:guid/canvas/:slug?runId=:runId

PUT replaces document fields and requires expectedVersion. PATCH performs an incremental append, prepend, or exact replace operation and also requires expectedVersion. A stale version returns HTTP 409, preventing two agents from silently overwriting each other's work.

curl -X PATCH 'https://your-domain.com/api/playbooks/abc123/canvas/pr-review?runId=RUN_UUID' \  -H "Authorization: Bearer apb_your_key" \  -H "Content-Type: application/json" \  -d '{    "operation": "replace",    "search": "## Security review\nPending.",    "content": "## Security review\nNo blocking issues found.",    "expectedVersion": 3  }'

Playbook API keys (owner only)

GET    /api/playbooks/:id/api-keysPOST   /api/playbooks/:id/api-keysDELETE /api/playbooks/:id/api-keys/:kid

Human collaboration (session auth; owner manages access)

Human editors are invited with a one-time link. They can edit playbook content, while ownership controls remain owner-only.

GET    /api/playbooks/:id/collaboratorsPOST   /api/playbooks/:id/collaboratorsDELETE /api/playbooks/:id/collaborators/:collaboratorId
GET    /api/collaboration-invites/:tokenPOST   /api/collaboration-invites/:token

Invite links expire after 72 hours and can be accepted once. See Team Collaboration for the full permission model and security notes.

Playbook Secrets (owner or API key)

Secrets are encrypted using AES-256-GCM. Agents can use the use_secret MCP tool or proxy endpoint to use secrets in HTTP requests without ever reading the plaintext value.

GET    /api/playbooks/:guid/secrets          # List metadata onlyPOST   /api/playbooks/:guid/secrets          # Create encrypted secretPUT    /api/playbooks/:guid/secrets/:name    # Update/rotate secretDELETE /api/playbooks/:guid/secrets/:name    # Delete secret
# Dashboard onlyGET    /api/playbooks/:guid/secrets/reveal/:name
# Proxy external requests using a secretPOST   /api/playbooks/:guid/secrets/proxy
# Audit trail — shared with federated MCP callsGET    /api/playbooks/:guid/audit?operation=secret.

Every vault operation is recorded, refusals included: what was done, to which secret, by the owner or by which API key prefix, and for secret.use the destination host. An entry never holds a secret value, a full outbound URL, or a key. Owners and read-only auditors can read, export, and verify the trail. An agent key that performs vault operations cannot read the trail unless separately granted the auditor role. See the audit access model.

User profile and user API keys (Management)

GET    /api/user/profilePUT    /api/user/profile
GET    /api/user/api-keysPOST   /api/user/api-keysDELETE /api/user/api-keys/:kid

Public discovery and saved favorites

These APIs support public reads, dashboard skill/MCP discovery, and existing favorites. Explore is a server-rendered use-case guide with curated first-party starter links; it does not load these catalogs or automatically feature public playbooks.

GET /api/public/playbooksGET /api/public/skillsGET /api/public/skills/:idGET /api/public/mcpGET /api/public/mcp/:id
GET  /api/playbooks/:id/starPOST /api/playbooks/:id/starGET  /api/user/starred

Memory write-back (playbook API key or owner)

GET    /api/playbooks/:guid/memoryPUT    /api/playbooks/:guid/memory/:keyDELETE /api/playbooks/:guid/memory/:key

MCP endpoints

For clients that require a local stdio process, see the local MCP transport. It uses the same account tools and authorization handlers; protocol discovery starts without credentials, while data operations require your instance configuration.

GET  /api/mcp/:guid                    # MCP manifestPOST /api/mcp/:guid                    # MCP JSON-RPCPOST /api/mcp/:guid/tools/:tool        # Call one tool over plain HTTP
POST /api/mcp/manage                   # MCP management server (user API key)
GET    /api/mcp/config/:serverId       # Federated server config (owner)POST   /api/mcp/config/:serverIdPUT    /api/mcp/config/:serverIdDELETE /api/mcp/config/:serverIdPOST   /api/mcp/config/:serverId/test  # Try the connection before saving it
GET  /api/mcp-registry/search          # Search the public MCP registryGET  /.well-known/mcp-registry-auth    # Registry ownership verification

Every tool a playbook exposes is also reachable as a plain HTTP call, so a client that cannot speak MCP is not shut out:

POST /api/playbooks/:guid/operations/:operationPOST /api/control/:operation           # Account-level operations

Publishing skills over HTTP

Skills are served as plain markdown — an index plus one SKILL.md per skill, no credential, open CORS. Any client can install from a base URL with no registry and no sign-up. Only public playbooks are served; unlisted and private ones stay reachable through apb pull.

GET /.well-known/skills/                    # Site-wide: every public playbook's skillsGET /playbooks/:guid/.well-known/skills/    # One playbook

hermes skills install well-known:https://agentplaybooks.ai/.well-known/skills/<name>

Connection catalogue

GET /api/connections

Curated templates for wiring up a federated MCP server or OpenAPI service. Public, because a template is not a credential: every entry references the secrets it needs by name only, to be resolved from the playbook's vault.

Management

GET  /api/manage/openapi.jsonGET  /api/manage/playbooksPOST /api/manage/playbooks

Health

GET /api/health

API Key Usage

Playbook API keys let agents read/write memory for a single playbook.

curl -X PUT https://your-domain.com/api/playbooks/abc123/memory/user_preferences \  -H "Authorization: Bearer apb_live_xxxxxxxxxxxx" \  -H "Content-Type: application/json" \  -d '{"value": {"theme": "dark"}}'

User API keys are used for management endpoints and the MCP management server:

curl -X POST https://your-domain.com/api/mcp/manage \  -H "Authorization: Bearer apb_live_xxxxxxxxxxxx" \  -H "Content-Type: application/json" \  -d '{"jsonrpc":"2.0","id":1,"method":"list_playbooks","params":{}}'

Project Structure

agentplaybooks/  src/    app/      .well-known/skills/  # Public skill publishing (site-wide)      api/        _shared/           # auth.ts, guards.ts — where authorization lives        [[...route]]/      # Hono catch-all for most endpoints        mcp/               # MCP manifest, JSON-RPC, federation config        playbooks/         # Per-playbook routes (secrets, canvas, audit, …)      dashboard/           # Authenticated UI      enterprise/          # Self-hosting landing page      explore/             # Use cases, setup guidance, curated starters      login/               # Auth pages      page.tsx             # Marketing home    components/      playbook/            # Editor components      ui/                  # UI primitives    i18n/      messages/            # Translation files (en, hu, de, es)      request.ts           # Server-side locale resolution    lib/      mcp/                 # Federation, secret references      storage/             # Storage adapters      supabase/            # Supabase client and types      crypto.ts            # Secrets vault encryption  packages/    cli/                   # AgentPlaybooks CLI + Codex/Cursor plugin  plugins/    agentplaybooks/        # Claude plugin (claude.ai, Cowork, Claude Code)  .claude-plugin/          # Plugin marketplace manifest  docs/                    # Contributor-facing notes    security/              # Supplier-assessment pack (HU + EN)  examples/                # Starter playbooks (fork/clone/sync)  public/    blog/  docs/           # Markdown served to the client  schemas/                 # JSON schemas (agentplaybook.json, …)  scripts/                 # Seed and build scripts  supabase/    migrations/            # Database migrations  tests/                   # Vitest suites  open-next.config.ts  wrangler.jsonc

Database Schema

• playbooks: core entity (includes visibility enum: private, public, unlisted; persona fields for agent identity and instructions for always-on project rules)
• secrets: the vault — AES-256-GCM ciphertext, per-secret host allow-list, reveal flag, rotation and usage accounting
• audit_logs: owner/auditor-readable hash-chained history for federated calls, vault operations, configuration changes, and memory/canvas writes; no secret values, content bodies, full outbound URLs, or API keys. Renamed from mcp_proxy_audit_logs.
• skills: skill definitions and optional SKILL.md content
• skill_attachments: secure attachment storage for skills
• mcp_servers: MCP tools and resources
• playbook_runs: isolated executions of a reusable playbook
• canvas: versioned markdown work documents
• memories: key-value memory store
• api_keys: playbook-scoped API keys with RBAC roles
• user_api_keys: user-scoped API keys
• playbook_collaborators: accepted human editor memberships and hashed one-time invites
• profiles: public user profile data
• playbook_stars: saved playbook favorites

There is deliberately no second credential store. Federated MCP and OpenAPI servers used to keep their own encrypted secrets in mcp_server_secrets; that table was dropped (supabase/migrations/20260820_drop_mcp_server_secrets.sql) because a second store meant the credentials most worth stealing sat in the weaker box, without the rotation, expiry, usage accounting and audit trail the vault already had. transport_config.auth.token_secret now names a vault entry instead.

A note on Row Level Security

RLS is enabled on the tables listed above, but it is not the primary authorization mechanism at runtime. Almost all API routes query with the service-role key, which bypasses RLS; authorization is enforced in application code (src/app/api/_shared/guards.ts).

RLS is load-bearing for the handful of endpoints that read public playbooks with the anon key — the MCP manifest (/api/mcp/:guid), its tool routes, and the public skills/MCP listings. Those depend on the anon SELECT policies in supabase/migrations/20260107_permissions_refactor.sql. Removing or disabling those policies breaks the endpoints rather than merely relaxing them.

Policies written against auth.uid() are currently inert, because no JWT-bearing client performs table queries — the browser talks only to /api/*, never to Postgres directly.

Security

Report vulnerabilities privately — see SECURITY.md. Do not open a public issue for a security defect.

Self-hosted operators assembling a NIS2 / 418/2024. 77. § filing can start from the incident runbook (HU). Release SBOMs and cosign verify are in docs/security/supply-chain.md.

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Run the same checks CI runs, in the same order:

   bash

   npm run lint                        # eslintnpm run test:all                    # vitest + the CLI suitenpm run prebuild && npx tsc --noEmitnpm run audit:productionnpm run build

4. Commit your changes and open a Pull Request

Two things worth knowing before your first PR:

• Write the lockfile with npm 11. npm 10 produces a package-lock.json that npm ci then rejects outright, so CI fails on install before it reaches your change. npx npm@11 install works on Node 20 as well.
• Warnings are tolerated, errors are not. npm run lint currently reports a known set of react-hooks and navigation warnings, tracked in the issues — a clean run means zero errors, not zero output.

License

MIT — see LICENSE.

Use it for anything, including commercially. Keep the copyright notice and the permission notice in copies or substantial portions.