Adg

Agent Directory Group (ADG)

adg is one umbrella CLI with two domains, each aligned to an existing ecosystem so there is little new to learn:

| Domain | Command | Aligns to | |--------|---------|-----------| | plugins | adg plugins | the Codex plugin flow (~/.agents/plugins/marketplace.json) | | skills | adg skills | vercel-labs/skills — a vendored fork (see [vendor/skills](vendor/skills/PROVENANCE.md)) |

For plugins, one universal manifest — .agents/.plugin.json — is the source of truth. Runtime-specific manifests (.claude-plugin/plugin.json, .codex-plugin/plugin.json) are generated from it, so a plugin is authored once and adapted to each runtime.

Control plane vs export. ADG's own management lives in the lock (.plugin-lock.json: provenance, sha256 integrity, dependencies) — that is the only file ADG treats as authoritative. marketplace.json is a thin runtime-facing export kept in the de-facto shape Codex consumes; ADG never manages plugins through it.

See [docs/authoring.md](docs/authoring.md) to author a plugin, and [docs/agents-spec.md](docs/agents-spec.md) for the .agents/ directory spec.

Why

• Skill explosion — hundreds of skills become unmanageable; ADG groups them

into versioned, discoverable plugins.

• Runtime fragmentation — Claude and Codex use different plugin layouts;

ADG generates each from a single source.

• Reproducibility — .plugin-lock.json records source, version and a content

hash for every installed plugin.

---

Install and quick start

Install the CLI once, then run adg from anywhere:

npm install -g @rbbtsn0w/adg          # stable channel
npm install -g @rbbtsn0w/adg@beta     # pre-release channel
brew tap RbBtSn0w/tap
brew install adg
# or run ad-hoc, no install:
npx @rbbtsn0w/adg --help

Typical end-user flow — pull a marketplace into your global store, then load it into the runtimes you use:

# 1) collect plugins into the global store (~/.agents/plugins)
adg plugins add anthropics/knowledge-work-plugins --ref main --global
#    large monorepo? fetch only what you need:
adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global

# 2) load into the runtimes you use
adg plugins link --target codex  --global     # Codex discovers ~/.agents/plugins natively
adg plugins link --target claude --global     # Claude loads via ~/.claude/skills symlinks

# 3) keep it current
adg plugins update --global
adg plugins list --global

Machine consumers can use adg plugins list --json and adg plugins status --json; see [docs/cli-json.md](docs/cli-json.md) for the stable output and exit-code contract.

adg is the only command you invoke — no Node build step beyond the global install. To hack on the CLI itself, see [Developing from source](#developing-from-source).

Copy-paste prompt for coding agents

Paste the prompt below into Codex, Claude Code, or another coding agent to have it install ADG, add a plugin source, connect the installed plugins to the active runtime, and verify the result. Replace the placeholders before sending it.

Set up ADG for this environment and use it to install plugins from
anthropics/knowledge-work-plugins.

Requirements:
1. Inspect the current environment first. If `adg` is unavailable, install the
   stable `@rbbtsn0w/adg` package with an available supported package manager
   (`brew install adg` after `brew tap RbBtSn0w/tap`, or
   `npm install -g @rbbtsn0w/adg`). Do not modify the current project yet.
2. Use the  scope explicitly on every mutating command:
   `--global` for plugins shared across projects, or `--project` for this
   repository only. Do not rely on interactive prompts.
3. Inspect the source and installed plugin names, then install the requested
   plugins. Use `adg plugins add  --all
   ` unless I list specific plugins or components below.
4. Connect the installed plugins to  with
   `adg plugins link --target  `. Let ADG manage runtime
   projections; do not manually edit or copy files into agent-specific plugin
   directories.
5. Verify the setup with `adg plugins list ` and
   `adg plugins status --target  `. Report the commands you
   ran, the installed plugin names, and any remaining drift or errors.

Requested plugins/components (optional): 

For example, replace ` with global, with --global, and with codex` for a personal Codex setup available in every project.

---

Works with existing ecosystems

ADG is not a new plugin format you have to migrate to. Any repo that already ships .claude-plugin/ or .codex-plugin/ manifests is ingested as-is: on the way in, add discovers each native manifest and reverse-adapts it into a canonical .agents/.plugin.json (the inverse of adapt), then ADG manages and re-projects it like any first-party plugin. No fork, no edits upstream.

The two examples below are real, popular repositories — neither is ADG-native.

Example 1 — anthropics/knowledge-work-plugins (a category monorepo)

A marketplace monorepo where each top-level category (engineering/, marketing/, legal/, …) is its own plugin with a .claude-plugin/plugin.json and a skills/ tree. Pull the whole thing, or sparse-checkout just the categories you want:

# whole marketplace into the global store
adg plugins add anthropics/knowledge-work-plugins --ref main --global

# or fetch only one category from the large monorepo
adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global

# each category's .claude-plugin manifest is reverse-adapted on import,
# then projected back onto the runtimes you use
adg plugins link --target claude --global   # → ~/.claude/skills/:
adg plugins link --target codex  --global   # native, zero-copy
adg plugins list --global

Example 2 — obra/superpowers (a single multi-runtime plugin)

A single skills plugin that already ships .claude-plugin/, .codex-plugin/ and a skills/ library. Because the native manifests are already present, ADG simply adopts it — discovery picks up the existing manifest, records provenance and a content hash in the lock, and from then on it updates like any ADG plugin:

adg plugins add obra/superpowers --ref main --global

# now under management — same lifecycle as a first-party plugin
adg plugins list --global
adg plugins update --global
adg plugins link --target claude --global

> Both repos are pulled by owner/repo shorthand over a shallow clone (sparse > checkout when --sparse is given). Provenance — {type:"github",repo,ref,path} > — plus a sha256 integrity hash land in .plugin-lock.json, so the install is > reproducible regardless of which ecosystem the plugin originally came from. See > [Importing existing inventory (via add)](#importing-existing-inventory-via-add) > for the discovery and reverse-adaptation details.

---

Concepts (common)

These apply the same whether you run a released build or the source tree.

Layout

plugins/                       reference plugins + a generated marketplace
├── .plugin-lock.json          lock file (generated)
├── marketplace.json           marketplace listing (generated)
├── asc/                       strict plugin (explicit skills)
└── github-cr/                 non-strict plugin (auto-scanned skills)

schemas/                       JSON Schemas for the three ADG file formats
src/                           CLI library (manifest, hash, adapters, lock, ...)
bin/adg.ts                     CLI entry point
test/                          node:test suite

A single plugin directory:

asc/
├── .agents/.plugin.json       universal manifest (source of truth)
├── .claude-plugin/plugin.json generated by `adg plugins adapt`
├── .codex-plugin/plugin.json  generated by `adg plugins adapt`
├── skills//SKILL.md
├── agents/  commands/  hooks/  apps/  .mcp.json
└── README.md

File formats

| File | Schema | Role | |------|--------|------| | .agents/.plugin.json | [adg-plugin.schema.json](schemas/adg-plugin.schema.json) (adg.plugin/v1) | Universal manifest — source of truth | | .plugin-lock.json | [plugin-lock.schema.json](schemas/plugin-lock.schema.json) (version: 3) | Control plane — ADG's authoritative state | | marketplace.json | [marketplace.schema.json](schemas/marketplace.schema.json) | Export — de-facto catalog for Codex |

The split is deliberate:

• Lock (control plane, ADG-owned). Carries provenance (origin, a

discriminated source union: {type:"local",path} / {type:"github",repo,ref?,path?} / {type:"git",url,ref?,path?}), sha256 content integrity, resolved version, and dependencies. Every control operation — list, update, link, collision detection, dependency resolution — keys off the lock. Installing a same-named plugin from a different origin is rejected as a collision.

• Marketplace (export, runtime-owned shape). Written in the de-facto shape

Codex consumes ({ name, source: { source, path }, policy, category }, no ADG-specific schema). ADG never reads it as authority — it is regenerated from the plugin directories. Integrity/version/provenance deliberately do not appear here; they live in the lock.

strict: true exposes only the manifest's declared skills; strict: false auto-scans the skills/ directory (Claude "skill-bundle" form). The Codex manifest always emits an explicit skills array.

---

Commands (common)

The command surface is identical in both modes — only the launcher differs:

| Mode | Launcher | Setup | |------|----------|-------| | Released build | adg … | install the package (see [Install and quick start](#install-and-quick-start)) | | From source (debug) | node bin/adg.ts … | clone + npm install (see [Developing from source](#developing-from-source)) |

The examples below use the released adg launcher. When running from source, replace adg with node bin/adg.ts — everything else is the same.

# scaffold a new plugin under ./plugins/
adg plugins init my-plugin

# generate runtime manifests (claude | codex | all)
adg plugins adapt plugins/my-plugin --target all

# validate manifest + referenced paths
adg plugins validate plugins/my-plugin

# add from a local dir: copy, adapt, hash, update lock + marketplace
adg plugins add plugins/my-plugin --project        # /.agents/plugins
adg plugins add plugins/my-plugin --global         # ~/.agents/plugins
adg plugins add plugins/asc --dir plugins          # explicit target dir

# add from GitHub (shorthand, @ref, or full URL); --path selects a monorepo subdir
adg plugins add owner/repo --dir plugins
adg plugins add owner/repo@v0.1.0 --path plugins/asc --dir plugins
adg plugins add https://github.com/owner/repo.git --ref main --dir plugins
adg plugins add plugins/asc --dir plugins --no-deps   # skip transitive deps

# add existing native plugins — Codex/Claude manifests are reverse-adapted into
# .agents/.plugin.json automatically during discovery (no separate `import` verb)
adg plugins add owner/repo --ref main --sparse .agents/plugins --sparse plugins --global
adg plugins add ./some/local/repo --dir plugins
adg plugins import-skills ~/.agents/skills --as asc --prefix asc- --dir plugins

# project installed plugins into a runtime's discovery path (store stays the source of truth)
adg plugins link   --target codex --global          # enable in one agent (regenerate .codex-plugin)
adg plugins link   --target claude --global         # symlink into ~/.claude/skills/
adg plugins unlink --target antigravity asc         # disable in one agent only (supports agent-only residuals)
adg plugins unlink --target all asc                 # disable in all agents
adg plugins disable --global asc                    # persistently disable everywhere; keep store payload
adg plugins enable --global asc                     # restore from the store in every compatible agent
adg plugins sync   --target antigravity asc         # reconcile one agent to the store (clears residual)
adg plugins sync   --target all --global            # reconcile all agents to the store in one go
adg plugins marketplace sync owner/repo --target all     # same, scoped to a whole source across all agents

# diagnose & maintain
adg plugins status --target antigravity    # live-diff store vs agent (isolates global plugins if project is uninitialized)
adg plugins update --dir plugins           # re-fetch remote sources; rescan local ones in place
adg plugins list --dir plugins             # list locked plugins
adg plugins migrate --dir plugins          # upgrade legacy locks and move flat installs

Two layers, with the store as the system of record. add / remove control the payload; enable / disable persist whether a stored plugin should be projected to any agent. Agents are projections of that desired state: link / unlink remain temporary per-agent controls, while sync restores the store state. remove deletes from the store and every agent; disable keeps the payload, source, version, and marketplace entry so updates and later re-enabling remain available.

Disabled plugins stay in their existing on-disk paths. Their lock entry records state: "disabled"; Codex and Claude installations are removed and Antigravity's discovery manifest/projection is cleared. update may refresh a disabled plugin's payload but never activates it. list groups enabled and disabled entries, and status distinguishes intentional disablement from runtime drift.

For the local-directory-source flow into Claude's registry/cache, see [docs/local-plugin-registration.md](docs/local-plugin-registration.md).

On-disk layout

Plugins are grouped on disk by the source they came from. Remote installs nest under a per-marketplace bucket; local installs stay flat:

.agents/plugins/
├── .plugin-lock.json
├── marketplace.json
├── my-local-plugin/              ← local: flat
└── owner__repo/                  ← remote: owner/repo, "/" flattened to "__"
    ├── asc/
    └── github-cr/

The plugin name stays the unique key across the lock, marketplace.json, and the Claude symlink bridge — nesting is organizational only, so two sources still can't both install a plugin of the same name. marketplace.json's source.path tracks the real on-disk path (e.g. ./owner__repo/asc), keeping the Codex export accurate. Run adg plugins migrate once to lift an older flat store into this layout.

Skills domain

adg skills (add/use/remove/list/find/update/init) is a vendored fork of vercel-labs/skills under [vendor/skills/](vendor/skills/) — adg skills forwards all args to it. Run adg skills --help for its full usage.

> License. Upstream skills is MIT (declared in its README and > package.json). The vendored copy retains a reconstructed > [LICENSE](vendor/skills/LICENSE) (MIT + attribution) and the upstream > third-party notices; see [vendor/skills/PROVENANCE.md](vendor/skills/PROVENANCE.md). > GitHub's API shows license: null only because upstream ships no standalone > LICENSE file. The 6 runtime dependencies in package.json exist solely for > this vendored CLI; ADG's own plugins code remains dependency-free.

Install scopes

• --project (default) → /.agents/plugins
• --global → ~/.agents/plugins, honoring ADG_PLUGINS_HOME, then

XDG_STATE_HOME/.agents/plugins

• --dir → an explicit plugins directory

Safety: ADG only ever reads and writes the plugins/ subtree of a scope. The sibling ~/.agents/AGENTS.md and ~/.agents/skills/ are never touched.

Sources & dependencies

add accepts a local path or a GitHub source (owner/repo, owner/repo@ref, or a github.com URL). GitHub sources are shallow-cloned to a temp dir (with cone-mode sparse checkout when --sparse is given); the lock records the `orig

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RbBtSn0w
• Source: RbBtSn0w/adg
• License: MIT

Install and usage instructions live in the source repository linked above.