Lesson 8.325 min · 5 cards · 8 exercises · 1 mission

Capstone: a plugin for the whole team

Package todo-api's skills, subagents and hooks as one plugin, fix the two snags of the move, test it, and ship it through a team marketplace.

This is the last lesson. Throughout the course you've built a complete toolkit for todo-api. This lesson packages it as one plugin, puts it in a team marketplace, and installs it in another repo with a single command. We did every step below for real, including two stumbling blocks you'll hit when moving from .claude/ to a plugin.

What you have

Collected from every level:

Item From lesson Goes in the plugin
The /add-endpoint skill 3.2 Yes
The pr-review skill with its red-flags.sh script 3.3 Yes
The reviewer, tester and debugger subagents 4.2, 4.3 Yes
Hooks that check syntax and block "done" while tests are red 6.2 Yes
Hooks that block rm -rf and writes to .env 6.3 Yes
The Read(./.env) deny rules 6.3 No: a plugin can't carry permission rules
The project's CLAUDE.md 2.1 No: inside a plugin it isn't loaded

The last two rows are the first thing worth remembering: a plugin carries capabilities (skills, agents, hooks, MCP), but not permission rules or project memory. Those still live in each repo.

From .claude/ to a plugin

The layout of the todo-api-toolkit plugin:

todo-api-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── add-endpoint/SKILL.md
│   └── pr-review/
│       ├── SKILL.md
│       └── scripts/red-flags.sh
├── agents/
│   ├── reviewer.md
│   ├── tester.md
│   └── debugger.md
├── hooks/
│   └── hooks.json
└── scripts/
    ├── block-rm.sh
    ├── protect-env.sh
    ├── check-js.sh
    └── tests-before-stop.sh

Only plugin.json goes inside .claude-plugin/; everything else sits at the plugin root. Put skills/ inside .claude-plugin/ and the skills won't load.

JSON
{
  "name": "todo-api-toolkit",
  "description": "Team toolkit for todo-api: skills, agents, safety and test hooks",
  "version": "1.0.0",
  "author": { "name": "todo-api team" }
}

name becomes the prefix for everything: /add-endpoint is now /todo-api-toolkit:add-endpoint, and the tester agent is now todo-api-toolkit:tester.

Hooks move over almost unchanged: copy the hooks block from .claude/settings.json into hooks/hooks.json, and only change the script paths from $CLAUDE_PROJECT_DIR/.claude/hooks/ to ${CLAUDE_PLUGIN_ROOT}/scripts/, wrapped in double quotes:

JSON
{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/block-rm.sh\"" }

Wherever the plugin is installed, ${CLAUDE_PLUGIN_ROOT} points there. Don't write data into that folder, because it changes with every version.

Two things to fix in the move

First: bundled files live outside the project. In lesson 3.3 the checklist sat in checklist.md next to SKILL.md. Running from the plugin, Claude was refused permission to read that file, because the plugin is installed outside the project folder. We tried injecting it with !`cat …` and allowing exactly that command, which was worse: Claude Code only allows cat inside the working directories, so the whole skill invocation was cancelled. The simplest fix: the checklist is five lines, so put it straight into SKILL.md. Bundled scripts still work fine through ${CLAUDE_SKILL_DIR}, because they are run, not read.

Second: the old copies in .claude/. If you don't delete them, the old skills and agents live alongside the prefixed ones, and hooks run twice (once from settings, once from the plugin). Confirm the plugin works, then delete the originals from .claude/.

One more note for agents: inside a plugin, an agent's permissionMode, hooks and mcpServers are ignored. Declare hooks and MCP at the plugin level.

Check before you ship

Three steps, all from the shell:

Terminal
claude plugin validate ./todo-api-toolkit
claude --plugin-dir ./todo-api-toolkit plugin details todo-api-toolkit
claude --plugin-dir ./todo-api-toolkit
  • validate checks the manifest and the frontmatter of every skill and agent. Ours: ✔ Validation passed.
  • plugin details lists the components and the cost: 2 skills, 3 agents, hooks on 3 events (hooks cost no context), about 232 tokens per session in total.
  • --plugin-dir opens a session with the plugin loaded but not installed, so you can try each piece.

In our tests, the plugin's hook blocked rm -rf despite an allow rule; /todo-api-toolkit:pr-review ran its script, went through each checklist item and flagged the console.log at src/routes/todos.js:8; and the todo-api-toolkit:tester agent reported 5/5 tests passing.

A marketplace for the team

Put the plugin in a marketplace repo, for example your-org/todo-team-plugins:

todo-team-plugins/
├── .claude-plugin/marketplace.json
└── plugins/todo-api-toolkit/   (the plugin folder above)
JSON
{
  "name": "todo-team-plugins",
  "owner": { "name": "todo-api team" },
  "plugins": [
    { "name": "todo-api-toolkit", "source": "./plugins/todo-api-toolkit",
      "description": "Skills, agents and hooks for working on todo-api" }
  ]
}

Run claude plugin validate ./todo-team-plugins, then push. Teammates install with:

/plugin marketplace add your-org/todo-team-plugins
/plugin install todo-api-toolkit@todo-team-plugins

To have a repo suggest it to newcomers, add this to that repo's .claude/settings.json:

JSON
{
  "extraKnownMarketplaces": {
    "todo-team-plugins": { "source": { "source": "github", "repo": "your-org/todo-team-plugins" } }
  },
  "enabledPlugins": { "todo-api-toolkit@todo-team-plugins": true },
  "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)", "Read(!.env.example)"] }
}

The marketplace is registered once they trust the folder, and the .env deny rules stay here because a plugin can't carry them. Each person still installs the plugin once on their own machine (lesson 8.2). To ship a new version: change the plugin, bump version, push. Third-party marketplaces don't auto-update by default, so remind the team to turn it on or run claude plugin update.

Closing the course

The CI workflow from lesson 8.1 can now use this very plugin: plugin_marketplaces pointing at the marketplace repo, plugins: "todo-api-toolkit@todo-team-plugins", and prompt: "/todo-api-toolkit:pr-review".

Looking back over the whole journey: you started by handing off a small bug and reading the diff (level 1); taught Claude about the project (level 2); turned procedures into commands and skills (level 3); split work across focused agents (level 4); connected GitHub through MCP with minimal access (level 5); set rules that run every time with hooks (level 6); took on bigger work safely with plans, rewind and long sessions (level 7); and finally ran unattended and packaged it all for the team (level 8).

The principle running through it all is a single one: Claude does more when you give it the right context, the right tools and the right limits. Whenever you catch yourself repeating something, ask: is this a fact (CLAUDE.md), a procedure (a skill), a side task (a subagent), a connection (MCP), or a rule that must always hold (a hook)? Then package it.

Practice lesson 8.3

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.