{
  "markdown": "# AgentPlaybooks\n\n**One playbook, every agent.** A portable operating environment for AI agents — persona, skills, MCP servers, project instructions, and memory in one source of truth.\n\nKeep 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.\n\nYour 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.\n\n## Highlights\n\n**What a playbook holds**\n\n- Persona: 1 per playbook, stored directly on the playbook record\n- Instructions: always-on project rules — the `AGENTS.md` / `CLAUDE.md` content\n- Skills: JSON schema definitions plus optional SKILL.md content\n- Skill attachments: secure file storage for code, prompts, and docs\n- MCP servers: tools and resources in Model Context Protocol format\n- Memory: key-value store with tags and descriptions\n- Canvas: versioned markdown work documents, scoped to a playbook run, so several\n  teams can execute the same playbook without sharing work products\n\n**Credentials, without handing them over**\n\n- Secrets vault: AES-256-GCM, per-user derived keys. Agents reference a secret by\n  name and the platform injects it server-side (`use_secret`), so the value never\n  enters an agent's context. Optional per-secret host allow-lists.\n- Federation: other MCP servers and OpenAPI services become tools on your\n  playbook, with their credentials resolved from that same vault by name\n- Audit trail: every federated call and every vault operation, refusals included\n\n**Getting it into your tools**\n\n- CLI + Claude Code plugin: audit your local agent config, then sync one playbook\n  to Claude Code, Cursor, ChatGPT/Codex, Google Antigravity, Grok Bot and Hermes\n- Publishing: a public playbook's skills are served as plain markdown over HTTP\n  at `/.well-known/skills/` — installable from a URL, no registry, no sign-up\n- Export formats: JSON, OpenAPI, MCP, Anthropic, Markdown\n\n**Working with other people**\n\n- API keys: role-based access control (Viewer, Coworker, Admin)\n- Team collaboration: one-time editor invites without sharing human credentials or agent API keys\n- Marketplace: Public and Unlisted playbooks, skills, MCP servers\n- Theme: system-aware Light and Dark modes\n\n## Tech Stack\n\n| Category | Technology | Purpose |\n| --- | --- | --- |\n| Framework | [Next.js 16](https://nextjs.org/) + [React 19](https://react.dev/) | App Router, SSR |\n| Styling | [Tailwind CSS 4](https://tailwindcss.com/) | Utility-first CSS |\n| Animation | [Framer Motion](https://www.framer.com/motion/) | UI animations |\n| Icons | [Lucide React](https://lucide.dev/) | Icon library |\n| API | [Hono](https://hono.dev/) | Edge API routing |\n| Database | [Supabase](https://supabase.com/) | Postgres + Auth + RLS |\n| i18n | [next-intl](https://next-intl-docs.vercel.app/) | Localization (en, hu, de, es) |\n| Docs | Plain markdown in `public/docs` | Fetched and rendered client-side |\n| Hosting | [Cloudflare Workers](https://workers.cloudflare.com/) | Edge deployment |\n| Adapter | [@opennextjs/cloudflare](https://opennext.js.org/) | Next.js on Workers |\n\n## Live Demo\n\n- Website: https://agentplaybooks.ai — the canonical host; https://apbks.com is a short domain for links\n- Docs: https://agentplaybooks.ai/docs\n- GitHub: https://github.com/matebenyovszky/agentplaybooks\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 22+ (`engines` in `package.json`; CI runs 22)\n- npm 11+ — npm 10 writes a lockfile `npm ci` then rejects\n- Supabase project\n- Cloudflare account (optional for deployment)\n\n### Installation\n\n```bash\ngit clone https://github.com/matebenyovszky/agentplaybooks.git\ncd agentplaybooks\nnpm install\n```\n\n### Environment Variables\n\nCreate a `.env.local` file with:\n\n```env\nNEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co\nNEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key\nSUPABASE_SERVICE_ROLE_KEY=your_service_role_key\n\n# Required for the secrets vault. 32 bytes as 64 hex characters:\n#   node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\n# Losing it means losing every stored secret — no vault operation can decrypt\n# without it, and rotating it invalidates everything already encrypted.\nSECRETS_ENCRYPTION_KEY=\n```\n\nOptional:\n\n| Variable | Effect |\n| --- | --- |\n| `NEXT_PUBLIC_APP_URL` | The canonical origin used for canonical tags, the sitemap and robots. Defaults to `https://agentplaybooks.ai`. |\n| `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. |\n| `SECRETS_REQUIRE_ALLOWED_HOSTS` | `true` makes a secret's host allow-list mandatory: an unpinned secret cannot be used for outbound requests at all. |\n\n### Development\n\n```bash\nnpm run dev\n```\n\nOpen http://localhost:3000\n\n### Cloudflare Deployment\n\n```bash\nnpm run build:worker\nnpm run preview\nnpx wrangler deploy\n```\n\n## CLI and Claude Code Plugin (`packages/cli`)\n\n`agentplaybooks doctor <project>` audits local agent configuration\n(instructions, Agent Skills, MCP servers, likely hard-coded secrets, drift)\nand `agentplaybooks sync <project>` creates the canonical\n`agentplaybook.json` plus the platform files missing from enabled targets:\nClaude Code (`.claude/skills` + `.mcp.json`), Cursor (`.cursor/skills` +\n`.cursor/mcp.json`), ChatGPT/Codex (`.codex/skills` + `.codex/config.toml`),\nGoogle Antigravity (`.agents/skills`), Grok Bot (`.agents/skills`, which it\ndiscovers natively alongside `AGENTS.md`), and Hermes Agent (`.agents/skills`\nregistered in `~/.hermes/config.yaml`, plus that file's `mcp_servers:` and\n`SOUL.md`).\n`login` / `playbooks` / `pull` / `push` synchronize skills, MCP servers, and the\nmanifest with a hosted playbook using a user API key; secret values never move,\nonly the references the playbook declares in `spec.secrets`. All mutating\ncommands are plan-only until `--apply`. See\n[packages/cli/README.md](packages/cli/README.md).\n\nThe same package doubles as a Claude Code / Claude Cowork plugin (skill +\nslash commands). Install it from this repository:\n\n```text\n/plugin marketplace add matebenyovszky/agentplaybooks\n/plugin install agentplaybooks@agentplaybooks\n```\n\n## API Overview\n\n### Public and Unlisted playbook access\n\nPublic playbooks are visible to everyone. Unlisted playbooks are accessible via GUID but hidden from search.\n\n\n```\nGET /api/playbooks/:guid\nGET /api/playbooks/:guid?format=openapi\nGET /api/playbooks/:guid?format=mcp\nGET /api/playbooks/:guid?format=anthropic\nGET /api/playbooks/:guid?format=markdown\n\nGET /api/playbooks/:id/personas\nGET /api/playbooks/:id/skills\nGET /api/playbooks/:guid/memory\n```\n\nNote: `:id` supports both UUID and GUID for personas and skills.\n\n### Authenticated playbook CRUD (session auth)\n\n```\nGET    /api/playbooks\nPOST   /api/playbooks\nPUT    /api/playbooks/:id\nDELETE /api/playbooks/:id\n```\n\n### Personas (owner or editor)\n\n```\nPOST   /api/playbooks/:id/personas\nPUT    /api/playbooks/:id/personas/:pid\nDELETE /api/playbooks/:id/personas/:pid\n```\n\n### Skills (owner or editor)\n\n```\nPOST   /api/playbooks/:id/skills\nPUT    /api/playbooks/:id/skills/:sid\nDELETE /api/playbooks/:id/skills/:sid\n```\n\n### Memory writes (API key or owner)\n\n```\nPUT    /api/playbooks/:guid/memory/:key\nDELETE /api/playbooks/:guid/memory/:key\n```\n\n### Canvas work documents\n\nCanvas documents belong to an isolated workflow run, so multiple teams can execute the same\nplaybook without sharing work products. They are long-form markdown artifacts that agents can revise over time. Use\nmemory for durable facts and structured state; use canvas for deliverables such as a PR review,\nresearch report, implementation plan, or draft that may be edited passage by passage.\n\n```http\nGET    /api/playbooks/:guid/runs\nPOST   /api/playbooks/:guid/runs\nGET    /api/playbooks/:guid/canvas?runId=:runId\nPOST   /api/playbooks/:guid/canvas\nGET    /api/playbooks/:guid/canvas/:slug?runId=:runId\nPUT    /api/playbooks/:guid/canvas/:slug?runId=:runId\nPATCH  /api/playbooks/:guid/canvas/:slug?runId=:runId\nDELETE /api/playbooks/:guid/canvas/:slug?runId=:runId\n```\n\n`PUT` replaces document fields and requires `expectedVersion`. `PATCH` performs an incremental\n`append`, `prepend`, or exact `replace` operation and also requires `expectedVersion`. A stale\nversion returns HTTP `409`, preventing two agents from silently overwriting each other's work.\n\n```bash\ncurl -X PATCH 'https://your-domain.com/api/playbooks/abc123/canvas/pr-review?runId=RUN_UUID' \\\n  -H \"Authorization: Bearer apb_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"operation\": \"replace\",\n    \"search\": \"## Security review\\nPending.\",\n    \"content\": \"## Security review\\nNo blocking issues found.\",\n    \"expectedVersion\": 3\n  }'\n```\n\n### Playbook API keys (owner only)\n\n```\nGET    /api/playbooks/:id/api-keys\nPOST   /api/playbooks/:id/api-keys\nDELETE /api/playbooks/:id/api-keys/:kid\n```\n\n### Human collaboration (session auth; owner manages access)\n\nHuman editors are invited with a one-time link. They can edit playbook content, while ownership controls remain owner-only.\n\n```\nGET    /api/playbooks/:id/collaborators\nPOST   /api/playbooks/:id/collaborators\nDELETE /api/playbooks/:id/collaborators/:collaboratorId\n\nGET    /api/collaboration-invites/:token\nPOST   /api/collaboration-invites/:token\n```\n\nInvite links expire after 72 hours and can be accepted once. See [Team Collaboration](https://agentplaybooks.ai/docs/team-collaboration) for the full permission model and security notes.\n\n### Playbook Secrets (owner or API key)\n\nSecrets 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.\n\n```\nGET    /api/playbooks/:guid/secrets          # List metadata only\nPOST   /api/playbooks/:guid/secrets          # Create encrypted secret\nPUT    /api/playbooks/:guid/secrets/:name    # Update/rotate secret\nDELETE /api/playbooks/:guid/secrets/:name    # Delete secret\n\n# Dashboard only\nGET    /api/playbooks/:guid/secrets/reveal/:name\n\n# Proxy external requests using a secret\nPOST   /api/playbooks/:guid/secrets/proxy\n\n# Audit trail — shared with federated MCP calls\nGET    /api/playbooks/:guid/audit?operation=secret.\n```\n\nEvery vault operation is recorded, refusals included: what was done, to which secret, by the\nowner or by which API key prefix, and for `secret.use` the destination host. An entry never\nholds a secret value, a full outbound URL, or a key. Owner access only — a playbook API key\nperforms vault operations but cannot read the record of them.\n\n### User profile and user API keys (Management)\n\n\n```\nGET    /api/user/profile\nPUT    /api/user/profile\n\nGET    /api/user/api-keys\nPOST   /api/user/api-keys\nDELETE /api/user/api-keys/:kid\n```\n\n### Marketplace and stars\n\n```\nGET /api/public/playbooks\nGET /api/public/skills\nGET /api/public/skills/:id\nGET /api/public/mcp\nGET /api/public/mcp/:id\n\nGET  /api/playbooks/:id/star\nPOST /api/playbooks/:id/star\nGET  /api/user/starred\n```\n\n### Memory write-back (playbook API key or owner)\n\n```\nGET    /api/playbooks/:guid/memory\nPUT    /api/playbooks/:guid/memory/:key\nDELETE /api/playbooks/:guid/memory/:key\n```\n\n### MCP endpoints\n\n```\nGET  /api/mcp/:guid                    # MCP manifest\nPOST /api/mcp/:guid                    # MCP JSON-RPC\nPOST /api/mcp/:guid/tools/:tool        # Call one tool over plain HTTP\n\nPOST /api/mcp/manage                   # MCP management server (user API key)\n\nGET    /api/mcp/config/:serverId       # Federated server config (owner)\nPOST   /api/mcp/config/:serverId\nPUT    /api/mcp/config/:serverId\nDELETE /api/mcp/config/:serverId\nPOST   /api/mcp/config/:serverId/test  # Try the connection before saving it\n\nGET  /api/mcp-registry/search          # Search the public MCP registry\nGET  /.well-known/mcp-registry-auth    # Registry ownership verification\n```\n\nEvery tool a playbook exposes is also reachable as a plain HTTP call, so a\nclient that cannot speak MCP is not shut out:\n\n```\nPOST /api/playbooks/:guid/operations/:operation\nPOST /api/control/:operation           # Account-level operations\n```\n\n### Publishing skills over HTTP\n\nSkills are served as plain markdown — an index plus one `SKILL.md` per skill, no\ncredential, open CORS. Any client can install from a base URL with no registry\nand no sign-up. Only *public* playbooks are served; unlisted and private ones\nstay reachable through `apb pull`.\n\n```\nGET /.well-known/skills/                    # Site-wide: every public playbook's skills\nGET /playbooks/:guid/.well-known/skills/    # One playbook\n```\n\n```bash\nhermes skills install well-known:https://agentplaybooks.ai/.well-known/skills/<name>\n```\n\n### Connection catalogue\n\n```\nGET /api/connections\n```\n\nCurated templates for wiring up a federated MCP server or OpenAPI service.\nPublic, because a template is not a credential: every entry references the\nsecrets it needs **by name only**, to be resolved from the playbook's vault.\n\n### Management\n\n```\nGET  /api/manage/openapi.json\nGET  /api/manage/playbooks\nPOST /api/manage/playbooks\n```\n\n### Health\n\n```\nGET /api/health\n```\n\n## API Key Usage\n\nPlaybook API keys let agents read/write memory for a single playbook.\n\n```bash\ncurl -X PUT https://your-domain.com/api/playbooks/abc123/memory/user_preferences \\\n  -H \"Authorization: Bearer apb_live_xxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"value\": {\"theme\": \"dark\"}}'\n```\n\nUser API keys are used for management endpoints and the MCP management server:\n\n```bash\ncurl -X POST https://your-domain.com/api/mcp/manage \\\n  -H \"Authorization: Bearer apb_live_xxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"list_playbooks\",\"params\":{}}'\n```\n\n## Project Structure\n\n```\nagentplaybooks/\n  src/\n    app/\n      .well-known/skills/  # Public skill publishing (site-wide)\n      api/\n        _shared/           # auth.ts, guards.ts — where authorization lives\n        [[...route]]/      # Hono catch-all for most endpoints\n        mcp/               # MCP manifest, JSON-RPC, federation config\n        playbooks/         # Per-playbook routes (secrets, canvas, audit, …)\n      dashboard/           # Authenticated UI\n      enterprise/          # Self-hosting landing page\n      explore/             # Marketplace\n      login/               # Auth pages\n      page.tsx             # Marketing home\n    components/\n      playbook/            # Editor components\n      ui/                  # UI primitives\n    i18n/\n      messages/            # Translation files (en, hu, de, es)\n      request.ts           # Server-side locale resolution\n    lib/\n      mcp/                 # Federation, secret references\n      storage/             # Storage adapters\n      supabase/            # Supabase client and types\n      crypto.ts            # Secrets vault encryption\n  packages/\n    cli/                   # AgentPlaybooks CLI + Claude Code plugin\n  .claude-plugin/          # Plugin marketplace manifest\n  docs/                    # Contributor-facing notes\n  public/\n    blog/  docs/           # Markdown served to the client\n  schemas/                 # JSON schemas (agentplaybook.json, …)\n  scripts/                 # Seed and build scripts\n  supabase/\n    migrations/            # Database migrations\n  tests/                   # Vitest suites\n  open-next.config.ts\n  wrangler.jsonc\n```\n\n## Database Schema\n\n- playbooks: core entity (includes visibility enum: private, public, unlisted; persona fields for agent identity and `instructions` for always-on project rules)\n- secrets: the vault — AES-256-GCM ciphertext, per-secret host allow-list, reveal flag, rotation and usage accounting\n- audit_logs: owner-readable audit trail for federated MCP calls and secrets vault operations (`secret.*`); never holds values, full URLs or keys. Renamed from `mcp_proxy_audit_logs`.\n- skills: skill definitions and optional SKILL.md content\n- skill_attachments: secure attachment storage for skills\n- mcp_servers: MCP tools and resources\n- playbook_runs: isolated executions of a reusable playbook\n- canvas: versioned markdown work documents\n- memories: key-value memory store\n- api_keys: playbook-scoped API keys with RBAC roles\n- user_api_keys: user-scoped API keys\n- playbook_collaborators: accepted human editor memberships and hashed one-time invites\n- profiles: public user profile data\n- playbook_stars: marketplace stars\n\nThere is deliberately **no second credential store**. Federated MCP and OpenAPI\nservers used to keep their own encrypted secrets in `mcp_server_secrets`; that\ntable was dropped (`supabase/migrations/20260820_drop_mcp_server_secrets.sql`)\nbecause a second store meant the credentials most worth stealing sat in the\nweaker box, without the rotation, expiry, usage accounting and audit trail the\nvault already had. `transport_config.auth.token_secret` now names a vault entry\ninstead.\n\n### A note on Row Level Security\n\nRLS is enabled on the tables listed above, but it is **not** the primary\nauthorization mechanism at runtime. Almost all API routes query with the\nservice-role key, which bypasses RLS; authorization is enforced in application\ncode (`src/app/api/_shared/guards.ts`).\n\nRLS *is* load-bearing for the handful of endpoints that read public playbooks\nwith the anon key — the MCP manifest (`/api/mcp/:guid`), its tool routes, and\nthe public skills/MCP listings. Those depend on the anon `SELECT` policies in\n`supabase/migrations/20260107_permissions_refactor.sql`. Removing or disabling\nthose policies breaks the endpoints rather than merely relaxing them.\n\nPolicies written against `auth.uid()` are currently inert, because no\nJWT-bearing client performs table queries — the browser talks only to\n`/api/*`, never to Postgres directly.\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run the same checks CI runs, in the same order:\n\n   ```bash\n   npm run lint                        # eslint\n   npm run test:all                    # vitest + the CLI suite\n   npm run prebuild && npx tsc --noEmit\n   npm run audit:production\n   npm run build\n   ```\n\n4. Commit your changes and open a Pull Request\n\nTwo things worth knowing before your first PR:\n\n- **Write the lockfile with npm 11.** npm 10 produces a `package-lock.json` that\n  `npm ci` then rejects outright, so CI fails on install before it reaches your\n  change. `npx npm@11 install` works on Node 20 as well.\n- **Warnings are tolerated, errors are not.** `npm run lint` currently reports a\n  known set of `react-hooks` and navigation warnings, tracked in the issues —\n  a clean run means zero *errors*, not zero output.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nUse it for anything, including commercially. Keep the copyright notice and the\npermission notice in copies or substantial portions.\n",
  "bytes": 18994,
  "sha": "c11a39f727485cbea215b0edcd6b3138bbccd129545db278b85c2e6117c3211e",
  "repo_slug": "matebenyovszky/agentplaybooks",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_agentplaybooks_agentplaybooks_c03598cc/readme"
}