Bundle your setup into a plugin

Everything you’ve built across this course works — and all of it is scattered across your .claude/ directory and your home config. The MCP servers for the database and the board. The ledger-needs-test.sh hook and its settings.json wiring. The PR-ritual skill from the skills chapter. A new engineer joining the payments team gets none of it. To bring them up to your setup, they’d have to copy files from four places and hope they got the wiring right. That’s the problem a plugin solves: it folds all of those pieces into one named, versioned, installable unit.

A plugin can bundle every extension type you’ve met — commands, skills, agents, hooks, and MCP servers — plus a few you haven’t. Install the plugin and you get the whole set at once; the database connection, the ledger gate, and the PR ritual arrive together, already wired.

The shape of a plugin

A plugin is a directory. One file is mandatory — the manifest at .claude-plugin/plugin.json — and everything else is convention: named directories at the plugin root that Claude Code knows to look in. The manifest is small:

payments-kit/.claude-plugin/plugin.json

{
  "name": "payments-kit",
  "description": "Database + Jira reach, the ledger-needs-test gate, and the PR ritual for the payments service",
  "version": "1.0.0"
}

The name becomes the plugin’s namespace — its skills install as /payments-kit:<skill>, which is why two plugins can ship a skill of the same name without colliding. The version matters for updates: bump it and your team gets the new release.

Around that manifest, you drop your existing pieces into the directories the plugin format expects. The mapping from your scattered .claude/ setup is almost mechanical:

payments-kit/
├── .claude-plugin/
│   └── plugin.json          # the manifest (the ONLY thing inside .claude-plugin/)
├── skills/
│   └── pr-ritual/
│       └── SKILL.md         # the PR-ritual skill, lifted as-is
├── hooks/
│   └── hooks.json           # the ledger gate's PreToolUse config
├── .mcp.json                # the db + jira server definitions
└── agents/                  # any subagents you want to ship

Two details save real grief here. First — and the docs flag this as the single most common mistake — only plugin.json goes inside .claude-plugin/. The skills/, hooks/, .mcp.json all sit at the plugin root, not under .claude-plugin/. Second, the hook config moves from your settings.json into a dedicated hooks/hooks.json, but the JSON itself is identical — the same PreToolUse block you wrote in the gate lesson, copied across unchanged. The full directory contract and manifest schema are on the plugins docs page.

Inside a plugin, refer to bundled files with ${CLAUDE_PLUGIN_ROOT} rather than $CLAUDE_PROJECT_DIR. When the gate hook lived in your repo it pointed at the project; as a shipped plugin it must point at wherever the plugin got installed, which ${CLAUDE_PLUGIN_ROOT} resolves to. It’s a one-line change to the hook command, and it’s what makes the gate portable to a machine that isn’t yours.

Test it before you ship it

You don’t have to publish anything to try the plugin — load it straight from disk with --plugin-dir:

claude --plugin-dir ./payments-kit

That session runs as if the plugin were installed: the database and Jira tools appear, the ledger hook arms, the PR ritual shows up under /payments-kit:pr-ritual. As you tweak the plugin, /reload-plugins picks up changes without a restart. This is the tightening loop — get the bundle behaving exactly like your hand-built setup before anyone else touches it.

What you’ve got now is the entire payments-service agent configuration as one folder — reach, gate, and ritual, manifested and versioned. It runs on your machine from a flag. The last step is making it run on your team’s machines from a single command, which is what a marketplace is for.