# Build a plugin

> Bundle your skills, hooks, and standards into one plugin, put it on a shelf, and let your whole team install it in one click

_20 min · intermediate · track: workbench · id: share-with-your-team_

> **Team:** 
>
> A colleague watches you run something you built and asks how to get it. You
> send a folder and a paragraph of instructions, and it still does not work on
> their machine. Handing a tool over should take one command.

Everything you built in this track works, and it works for exactly one person. A colleague who hits the problem you solved last month starts where you started and builds the whole thing again. Even you cannot carry your setup to the next repo without copying folders by hand.

A plugin closes both gaps, and a marketplace is the shelf you put it on.

Look at what you have to bundle. A [memory-consolidation skill](/course/context-engineering). [Hooks](/course/automating-with-hooks) that run without you watching. [Eval loops](/course/eval-loops) that prove the tools still work. The [guidelines file](/course/teach-it-your-taste) that tells all of them what good looks like to you. Maybe an [MCP server](/course/build-your-own-mcp) too.

That guidelines file is the one worth noticing. Handing over a tool gives a colleague what it does. Handing over your standards gives them the judgment you built up while using it.

A skill runs this whole process with you. `/build-plugin` ships inside TechWolf's `tool-build-kit`, from the [connector course](/course/build-your-own-mcp). Install it and follow along.

```
/plugin marketplace add techwolf-ai/ai-first-toolkit
/plugin install tool-build-kit@techwolf-ai-first
```

## What a plugin actually is

**A plugin is one folder that bundles every kind of tool you built behind one name, so installing it installs all of them.** Inside, each kind of tool sits in a folder Claude Code already knows to look in. One small file, the manifest at `.claude-plugin/plugin.json`, gives the plugin its name, description, and version.

| Folder | What it holds |
|---|---|
| `skills/` | the skills you wrote |
| `agents/` | your subagent definitions |
| `hooks/hooks.json` | the event handlers from this track |
| `.mcp.json` | your MCP server |

A plugin is shareable, versioned, and works in every project. Its skills take the plugin name as a prefix, so your summary skill becomes `/my-plugin:summary`. Two teammates can both ship a summary skill without clashing.

## Build the plugin

**A plugin is a unit your team installs whole, so decide what belongs together before you move a single file.** Give each job its own plugin. A deploy helper and a meeting-prep kit are two plugins, even though you built both.

Then give it a name and a one-line description. The name is what every skill inherits, and the description is what teammates read before installing.

The build itself is mostly moving your existing tools into the right folders, and you can hand that job to Claude Code. It gathers what sits in `.claude/` into one plugin folder and writes the manifest.

Test it before anyone else touches it. `claude --plugin-dir ./my-plugin` loads the plugin for one session without installing it. Leave the loose originals in `.claude/` alone, and clear them out once the plugin is really installed.

> **Warning:** 
>
> **Watch out for the path that only exists on your laptop.** Installing
> copies the plugin into a cache on the other machine, so an `.mcp.json` pointing
> at `/Users/you/projects/weather/server.py` fails for every colleague. Point
> inside the plugin, with `${CLAUDE_PLUGIN_ROOT}` or relative paths. Any runtime
> your server needs has to exist over there too, so name them in a README. Never
> bake an API key into the bundle. It arrives through each installer's own
> environment variables.

Loading clean on your own machine is the easy check. A plugin adds one your other tools never needed: it works on a machine that is not yours. Nothing else catches a hardcoded path.

## Put it on a shelf and ship it

**A marketplace is a git repo with one small list file (`.claude-plugin/marketplace.json`) that names your plugins and says where each one lives.** You do not build a server or sign up for anything. Any repo with that file is a shelf, and one repo can hold many plugins.

One choice to make deliberately: public or private.

- **A public repo means anyone who knows its name can install from it.** Good for a tool you want to give away. Whatever you push after that lands on every machine that installed it.
- **A private repo keeps the tool internal.** Teammates need repo access, handled by their normal git login. The right default for anything company-specific.

Private costs a team nothing. Installing from a private repo works exactly like a public one.

The trust runs both ways. A teammate who installs your plugin agrees to run your hooks with their permissions. You agree to the same when you add someone else's marketplace. So read what a public plugin does before installing it.

A colleague adds the shelf and installs from it with two commands.

```
/plugin marketplace add your-org/your-repo
/plugin install your-plugin@your-marketplace
```

The name after the `@` comes from the `name` field in your list file, and the repo name has nothing to do with it. At the top of this course you installed `tool-build-kit@techwolf-ai-first` from a repo called `techwolf-ai/ai-first-toolkit`.

> **Note:** 
>
> Not on GitHub? GitLab, Bitbucket, and self-hosted servers work the same way.
> Point at the full repo URL (`https://gitlab.com/your-team/plugins.git`). The
> short `owner/repo` handle is a GitHub shortcut.

## Keeping it running

**Once your plugin lives in a marketplace, shipping a change to everyone is a version bump and a push.** The maintainer edits the tool, raises the `version` in the manifest, and pushes.

Teammates do not magically get it. A team's own marketplace does not auto-update by default, and only Anthropic's official ones do. A colleague picks up your change by running `/plugin marketplace update`, or by switching auto-update on once. Until then they run your old version, so say something when you ship a fix.

That push reaches every machine that installed the plugin, so run your [eval loops](/course/eval-loops) first and only bump the version once they pass.

Give each plugin one named maintainer, so a bug report has somewhere to go.

## Turn it on for your whole team

**Put the shelf in the repo itself, and anyone who opens the project gets offered your plugin, on any plan.** List your marketplace once in the repo's shared `.claude/settings.json` and commit it. The shelf goes under `extraKnownMarketplaces`, the plugins you want under `enabledPlugins`.

A colleague who opens that folder and trusts it then gets prompted to install. Claude Code asks first, so nobody gets code they did not agree to. A new hire gets that offer the day they clone the repo.

An admin with control over managed settings can go further, force-installing an approved plugin on everyone or restricting which marketplaces people may add.

You can now hand someone a working tool and have it run on their machine. Ship anything you build from here the same way.

## Hands-on

Watch Claude Code assemble the plugin step by step this time. Next time, let `/build-plugin` do it all.

1. Pick a tool or two you built earlier: a skill, a hook, or your MCP server. Start small.

2. Ask Claude Code: "Turn the tools in my .claude folder into a plugin. Make the plugin folder, move them into it, and show me the structure before changing anything." Read what it proposes, then let it build.

3. Test it with `claude --plugin-dir ./your-plugin` and run the skill by its full name (`/your-plugin:skill-name`). If it answers, the bundle works.

4. Create a git repository for your marketplace. New to git? See [Version control](/course/version-control).

5. Put your plugin folder in that repo. Ask Claude Code: "Add the marketplace list file at `.claude-plugin/marketplace.json` so it lists my plugin, with me as owner." Note the `name` it gave the marketplace. Teammates type that after the `@`.

6. Commit and push to your git host.

7. From a clean project, run `/plugin marketplace add <your-repo>`, then `/plugin install <plugin>@<marketplace>`. If the skill runs, you have shipped a tool your team can use.

8. Install it where you actually work, then ask one teammate to install it too. Once it loads for both of you, delete the loose originals in that project's `.claude/` folder.

9. Now ship an update. Add something small to the plugin: a second skill, or a tweak to one already in there.

10. Run your eval checks first, because this push reaches everyone who installed it. When they pass, bump the `version` in the manifest at `.claude-plugin/plugin.json`, then commit and push.

11. From the project where you installed it, run `/plugin marketplace update`. Your added skill shows up.

## Reflect

- Which of the tools you built would a colleague actually install, and which one only ever made sense on your machine? Keeping the second kind loose in `.claude/` is fine.
- If you pushed a broken version tonight, who would find out first, you or them? If the answer is them, your evals are not running before the push.

Once you mark this course complete, the Workbench track is done and you can claim the track certificate.

## Recommended reading

- [Create plugins](https://code.claude.com/docs/en/plugins) (Anthropic): the folder layout and what a plugin can bundle.
- [Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) (Anthropic): how a git repo becomes a shelf.
- [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) (Anthropic): the colleague's side, and the repo settings that prompt a team to install.
- [build-plugin skill](https://github.com/techwolf-ai/ai-first-toolkit/tree/main/plugins/tool-build-kit) (TechWolf): the skill this course mirrors.