AgentPack Registry Documentation
The AgentPack standard, security model, adapter behavior, and the agentpack CLI — at a glance.
AgentPack standard
An AgentPack is a portable, installable bundle of AI agent behavior. The manifest is `AGENTPACK.yaml`. Each pack is composed of atoms — instruction, rule, skill, hook, command, subagent, mcp_server, plugin, workflow, context_pack, template, eval. Profiles (safe / standard / full / enterprise) select which atoms install.
Security model
Risk is computed from atom risk levels, required permissions, and the install profile. Permission summaries are first-class — no silent capability escalation. Hooks, secrets, MCP servers, and shell execution always surface as warnings, and executable content is gated behind an explicit --allow-exec unless the pack is signature-verified.
Adapters & cross-surface
AgentPack compiles to Claude Code (CLAUDE.md, .claude/skills, .claude/agents, .claude/settings.json), Codex (AGENTS.md, .codex/config.toml, .codex/hooks.json, .codex/skills), Cursor (.cursor/rules, .cursor/mcp.json, AGENTS.md), ChatGPT Apps (project-instructions.md, MCP app skeleton), and Generic (AGENTS.md, skills/, README-agent.md, agentpack.json) — the AGENTS.md output is also what agents like Google Antigravity read. Beyond file installs, `pack plugin` builds a Claude Code plugin, `pack mcpb` a .mcpb bundle, and `pack chat` a Claude Chat project bundle.
CLI
The agentpack CLI: guide (ChatGPT and Claude export routes with manual setup), init, import, validate, inspect, plan, pack (export / plugin / mcpb / chat), doctor, install, uninstall, diff, history, rollback, verify, update, plus registry auth (login, whoami, tokens, publish) and cache. `pack export` is pure (writes only under --out). `install` writes into your project root after showing a diff and prompting — backs up overwritten files, writes AGENTPACK.lock with per-atom SHA-256 checksums, and tracks every action in `.agentpack/history.jsonl` (hash-chained, WAL-protected). `import --from claude | claude-code | codex | chatgpt-gpt` compiles an existing setup into a pack.
Install / update / verify
`agentpack install` takes a local path, a git source (github:owner/repo@ref#subpath — no registry or account needed), or a registry id: diff against project root → permission summary → confirm → backup → write → install manifest at `.agentpack/installed/<pack>.json` → AGENTPACK.lock → history append. `agentpack uninstall` reverses it (delete created, restore backups, unmerge shared files). `agentpack verify` computes on-disk SHA-256 against the lockfile and reports drift (--all iterates every installed pack). `agentpack update` keeps installs current from their recorded source: --check re-resolves and exits 10 when an update is available; the apply path runs a BASE/LOCAL/NEW three-way reconcile (your edits are retained or conflict loudly — never silently clobbered), removes upstream-deleted files surgically, and re-runs every install gate on the delta (an unsigned exec-bearing update still requires --allow-exec). `agentpack rollback` undoes the most recent install (or all installs after a given history id with --to). The hash chain in `history.jsonl` makes the audit log tamper-evident. Personal config: install/update take --scope user to target ~/.claude (state at ~/.claude/.agentpack/), and `import --into <pack> --diff` folds live-config edits back into the pack repo.
Anatomy of an AgentPack
Every pack has a manifest, a set of atoms, install profiles, and a compatibility table:
agentpack: "1.0"
metadata:
id: "your-publisher.your-pack"
name: "Your Pack"
version: "0.1.0"
publisher: "your-publisher"
compatibility:
targets:
claude-code:
status: supported
profiles:
safe:
include: [ "instruction:project-defaults" ]
full:
include: [ "*" ]
atoms:
- id: "instruction:project-defaults"
type: instruction
name: "Project Defaults"
description: "Default project guidance for agents."
path: "atoms/instructions/project-defaults.md"
risk_level: low
Security and permissions
- Hook atoms are always high risk — they run shell commands after edits.
- MCP servers requiring secrets escalate to high.
- Shell + secrets + network + filesystem.write together raises the plan to critical.
- Safe profile excludes hooks, MCP servers, and shell-executing atoms.
- Unsigned packs that ship executable content (hooks, MCP servers, bang-bash commands) require an explicit
--allow-exec—--yesalone never crosses that line. A--require-sig-verified install is exempt. pack exportnever writes outside--out.installwrites only into your project root — every write is backed up, hashed intoAGENTPACK.lock, and recorded in the tamper-evident history chain, so uninstall/rollback restore your files exactly.
Adapter outputs
| Target | Files written |
|---|---|
| Claude Code | CLAUDE.md · .claude/skills/* · .claude/agents/* · .claude/settings.json |
| Codex | AGENTS.md · .codex/config.toml · .codex/hooks.json · .codex/skills/* · .codex/agents/* |
| Cursor | AGENTS.md · .cursor/rules/*.mdc · .cursor/mcp.json |
| ChatGPT Apps | project-instructions.md · app-manifest.json · mcp-server/* (export-only stub) |
| Generic | AGENTS.md · skills/* · README-agent.md · agentpack.json |
| Antigravity (via Generic) | reads the Generic target's AGENTS.md + GEMINI.md — verified against agy 1.1.0; skills use the same SKILL.md spec |
Beyond file installs, pack plugin compiles a pack into a Claude Code plugin (installable from a plugin marketplace — Code, Cowork, Desktop, web), pack mcpb builds a .mcpb bundle from stdio MCP servers, and pack chat emits a Claude Chat project bundle. Each atom carries an honest portability ceiling — inspect shows what reaches every surface and what stays terminal-only (hooks, ambient CLAUDE.md).
CLI commands
agentpack init # scaffold a starter AGENTPACK.yaml
agentpack import --from <src> # compile an existing setup into a pack
# (claude | claude-code | codex | chatgpt-gpt)
# --into <pack> --diff: fold live edits back
# into an existing pack (preview, then apply)
agentpack validate [path] # validate a manifest
agentpack inspect [path] # metadata, atoms, profiles, risk, portability
agentpack plan [path] \
--target <t> --profile <p> # plan + risk + permission summary
agentpack pack export [path] \
--target <t> --out <dir> # write platform-native files
agentpack pack plugin|mcpb|chat # Claude Code plugin / .mcpb / Chat bundle
agentpack install <src> # local path · github:owner/repo@ref#subpath
# · registry id
# --scope user: install into ~/.claude
agentpack verify <packId>|--all # drift detection against the lockfile
agentpack update [--check] # three-way-reconcile update from the recorded
# source (--check: exit 10 = update available)
agentpack diff / history / rollback / uninstall
agentpack login · whoami · tokens · publish · cache # optional registry
agentpack doctor # environment checks