AgentPackRegistry
Documentation

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 — --yes alone never crosses that line. A --require-sig-verified install is exempt.
  • pack export never writes outside --out. install writes only into your project root — every write is backed up, hashed into AGENTPACK.lock, and recorded in the tamper-evident history chain, so uninstall/rollback restore your files exactly.

Adapter outputs

TargetFiles written
Claude CodeCLAUDE.md · .claude/skills/* · .claude/agents/* · .claude/settings.json
CodexAGENTS.md · .codex/config.toml · .codex/hooks.json · .codex/skills/* · .codex/agents/*
CursorAGENTS.md · .cursor/rules/*.mdc · .cursor/mcp.json
ChatGPT Appsproject-instructions.md · app-manifest.json · mcp-server/* (export-only stub)
GenericAGENTS.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

Browse the registry →