Doctor: audit your agent configuration

apb doctor .            # human-readable health report
apb doctor . --json     # stable machine-readable output
apb doctor . --strict   # exit code 2 on high/critical findings (CI)

Doctor is read-only and local-only. It discovers AGENTS.md, CLAUDE.md, .cursorrules, SKILL.md files, and MCP configs across platform folders and reports:

• Agent Skills specification violations (missing name/description, bad names)
• Likely hard-coded credentials, including in the scripts and references a

• Insecure http:// MCP URLs outside localhost
• Same-named skills or MCP servers whose definitions drift between platforms
• A deterministic 0–100 health score

Sync: one playbook, every agent

apb sync .                       # plan only — shows what would be written
apb sync . --apply               # write the manifest and missing platform files
apb sync . --target=codex        # write only the named target(s) this run

Sync normalizes what it finds into the canonical agentplaybook.json manifest, then generates the files missing from each enabled deployment target:

Without --target, detected platforms are enabled automatically. Passing --target= writes only those named targets this run, not in addition to what was auto-detected. antigravity and hermes are opt-in — add an entry to spec.targets in agentplaybook.json:

{ "id": "codex", "type": "codex", "enabled": true, "config": {} }

Syncing across tools instead of inside a project

Most people's skills do not live in a project at all — they sit in ~/.cursor/skills, ~/.claude/skills, or a Hermes profile. --global plans the same fan-out across those home stores:

apb sync --global --target=claude,cursor,hermes        # plan
apb sync --global --target=claude,cursor,hermes --apply

The portable store for the global scope is ~/.agents/skills, and the manifest lives in ~/.agentplaybooks/agentplaybook.json rather than in your home directory. Two deliberate limits:

• Skills and custom agents only. A global MCP config holds credentials — an auth header, a

• Skills a client ships with itself are left out: Cursor's managed set and

Publishing this machine as a playbook

apb login                    # once, per remote
apb push --global            # plan
apb push --global --apply    # create or update the workstation playbook

This uploads the machine's own skills, links ~/.agentplaybooks/remote.json to that playbook, and leaves MCP configuration entirely local — a home-scoped MCP config is where auth headers live, and a playbook is something you share.

Adopting a credential that is already hard-coded

apb secrets adopt --global                                  # plan: read-only, no vault key needed
apb secrets adopt --global --apply                          # store in the vault, change no file
apb secrets adopt --global --apply --rewrite=.cursor/mcp.json  # also replace the literal with ${VAR}

The plan names every credential it found, the file and key path it sits in, its length, and whether that client is documented to expand ${VAR} — never the value itself. --apply on its own only fills the vault: nothing on disk changes, so a configuration that works today keeps working. A literal is replaced only in a file you name explicitly.

No backup of the original is written, on purpose: it would be a second plaintext copy of the credential. And once a value has been on disk it should be rotated — it may also be in git history, shell history, and editor backups. Afterwards the value can reach a client without ever being written down again:

apb secrets run -- claude        # or: hermes chat, codex, ...

Safety rules:

• Plan-only unless --apply is passed explicitly.
• Same-named definitions with different content are conflicts: reported

• Modified files are backed up under .agentplaybooks/backups/ first.
• Secret values never enter the manifest — only environment references.
• Line endings are normalized (CRLF is treated as LF), so the same skill has

Remote sync: share playbooks with your team

export AGENTPLAYBOOKS_API_KEY=<your-user-api-key>
apb login               # verify and store the key (~/.agentplaybooks, 0600)
apb playbooks           # list playbooks your key can access

apb push --apply        # hosted records + private versioned portable backup
apb backups <guid>      # list backup revision IDs
apb pull <guid> --apply # restore the latest portable backup
apb pull <guid> --snapshot=<id> --apply # restore an earlier revision

The private backup carries instructions, the full skill tree (including scripts/assets), custom agents, MCP references, and the manifest. It is immutable, survives deletion of the playbook record, and is owner-recoverable by GUID. Vault values are never fetched into it; review arbitrary skill assets for embedded credentials. The hosted playbook's separate skills and MCP records remain available for live use:

• Local → hosted (push): the project's instruction file, the skills and

• Hosted → local (pull + sync --apply): a snapshot restores the

push refuses an incomplete upload if source definitions conflict. The backup is bounded to 1,000 files, 4 MiB total, and 1 MiB per file. See Cross-platform Agent Backups for the exact scope and platform limits; local overrides, hooks, permission settings, and worktrees are deliberately not portable.

Claude Code reads CLAUDE.md and does not read AGENTS.md, but it does support @ imports. So the claude target does not copy your instructions — it writes a CLAUDE.md containing @AGENTS.md. One source of truth, nothing to drift. If you already have a CLAUDE.md without that import, sync says so instead of rewriting your file.

On a fresh machine the portable store is the only thing on disk, and it is not a deployment target — so nothing would be written. Enable the tools you have:

apb pull <guid> --apply
apb sync --target=claude,codex --apply

sync also lists the agent tools it detects for your user when no target is enabled, so you know what to pass.

OpenAPI federation servers are a hosted-only capability with no local client equivalent; pull reports them instead of writing a half-translated config. Secret values never move in either direction — see below. Use --url= or AGENTPLAYBOOKS_URL for self-hosted deployments.

Export: one playbook, one Hermes bot

A Hermes Agent bot is a profile: its own persona, skills, model, memory and history. Hermes installs and updates one from a directory or a git URL, so export hermes writes that directory from a playbook rather than inventing a second delivery mechanism.

apb pull <playbook-guid> --apply            # the playbook onto disk
apb export hermes ./bots/research --apply   # as a Hermes distribution
hermes profile install ./bots/research --name research
apb sync --target=hermes --profile=research --apply

What lands in the directory is distribution.yaml, SOUL.md from the playbook's persona, and skills// holding each skill's SKILL.md with the files it bundles. Nothing is fetched: the source is what pull already wrote, so the same project produces the same distribution offline.

The fourth command is not optional. Unlike hermes profile create, profile install copies no config.yaml, so a bot installed from a distribution has no providers and no model and cannot answer anything. sync --profile= seeds the bot's configuration from the installation's own and merges the playbook's MCP servers into it. The plan says when it is seeding rather than copying a whole configuration silently.

A distribution carries no config.yaml of its own on purpose. profile install replaces that file rather than merging it, so shipping one would overwrite the providers the machine is configured for and pin the bot's model to whatever was true at export time. Which model a bot runs is a local decision, and changing it per bot is most of the reason to have one.

To take a later change, re-run pull and export hermes, then:

hermes profile update research

The distribution's files are replaced; the bot's sessions, memories, .env and configuration are not touched. The manifest declares only what the export actually ships, so a playbook with no persona does not claim SOUL.md and an update cannot delete a SOUL.md someone wrote by hand.

Because the bot is a playbook, sharing the playbook shares the bot. A colleague who accepts a collaboration invite runs the same four commands and has the same agent, with their own memory and history.

Which playbook a command works on

The working directory decides. pull --apply and push write .agentplaybooks/remote.json in the project root, and every command that talks to a playbook reads the guid from there:

apb secrets status                     # the playbook linked to this directory
apb secrets status ../other-project    # the playbook linked to that directory
apb secrets status --playbook=<guid>   # ignore the link, name the playbook

The credential is resolved separately, and never from the link file: AGENTPLAYBOOKS_PLAYBOOK_KEY if it is set, otherwise the playbook-scoped key secrets login stored for that server and guid. One machine can hold keys for several playbooks without them being interchangeable, and a link to a playbook you have no key for is an error that names the command to run.

Commands that write name their target first. Being one directory over is an easy mistake, and a credential in the wrong vault is a tedious one to undo.

Secrets: no plaintext value ever touches the disk

apb secrets login <guid>     # a playbook-scoped key, stored 0600
apb secrets status           # what's needed vs in the vault vs in this shell
pass show deploy/api | apb secrets push DEPLOY_API_KEY
apb secrets run -- npm run deploy

• status prints names and state only: needed by the playbook, present in

• push takes the value from stdin or --from-env= — never from a

• run fetches the declared secrets into memory, injects them into one child

• These commands use a playbook-scoped API key rather than your account-wide

If your agent talks to the hosted playbook as an MCP server, you need none of this: the use_secret tool makes the platform inject the credential server-side, so the value never enters the agent's context either.

Connecting an OAuth provider

Some connections are authorized rather than pasted: they need a refresh token, and only a browser can obtain the first one. auth does that once.

apb secrets push GOOGLE_CLIENT_SECRET   # the exchange needs it
apb auth gmail

It runs authorization-code + PKCE against a loopback redirect, then hands the code to the server, which performs the exchange and writes the refresh token straight to the vault. Neither the client secret nor the refresh token touches this machine.

client_id is not a secret — it travels in the authorize URL your browser opens — so it is a literal value in the MCP server's transport_config.auth.client_id, which is also where federation reads it. auth reads the same field, so it need not be passed; --client-id=… and AGENTPLAYBOOKS_OAUTH_CLIENT_ID override it. Full detail in Federated MCP & OpenAPI Tools.

The playbook carries the contract, not the credential

A playbook states which credentials it needs; the values stay where they belong. sync collects every environment reference it finds in your MCP configuration (${VAR}, $VAR, env:VAR) into spec.secrets:

"secrets": [
  { "name": "DEPLOY_API_KEY", "ref": "env:DEPLOY_API_KEY", "required": true }
]

That makes the playbook portable and self-describing: a teammate who pulls it knows exactly which variables to set, without anyone ever transmitting a key. If you edit an entry — pointing it at a vault, or marking it optional — your version is preserved on the next sync. Literal credential values are never written into the manifest and never uploaded; doctor flags them and push refuses to run until they are replaced with references.

Connect: reach the playbook itself, not a copy of it

sync and pull move a playbook's contents into the files your tools read. connect does the other direction: it points a tool at the playbook's own MCP endpoint, so memory, skills, and every federated tool arrive live through one connection.

agentplaybooks connect 011d8a7fa0ec4016 --target=claude --name=apbks-dev --apply

That writes the entry and nothing else:

{
  "mcpServers": {
    "apbks-dev": {
      "type": "http",
      "url": "https://agentplaybooks.ai/api/mcp/011d8a7fa0ec4016",
      "headers": { "X-API-Key": "${APBKS_KEY_APBKS_DEV}" }
    }
  }
}

The key is never written — the config carries the reference, and the tool expands it at launch. Two details worth knowing, because both fail silently:

• Set the variable before starting the tool. A variable added afterwards is

• The credential goes in X-API-Key by default, not Authorization. A

Claude Code & Claude Cowork plugin

The repository marketplace installs the AgentPlaybooks Claude plugin: the account MCP connector (OAuth, no key), a playbooks skill, and /agentplaybooks:doctor and :sync, which run this CLI through a pinned npx. It works in claude.ai chat and Cowork as well as Claude Code — on claude.ai, add it under Customize → Plugins → Add marketplace. See AgentPlaybooks in Claude. In Claude Code:

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

After installing, ask Claude things like "audit my agent config" or "make my Claude skills available in Cursor and ChatGPT" — the skill knows the safe workflow (plan first, apply after your approval).

Other platforms

• ChatGPT / Codex: skills land in .codex/skills/, MCP servers in

• Google Antigravity: reads project skills from .agents/skills/, which

• Grok Bot (xAI): discovers skills from a fixed set of roots that already

• Hermes Agent: everything for one profile lives in ~/.hermes (or

• Cursor: skills in .cursor/skills/, MCP servers in .cursor/mcp.json.