Packaging skills into a plugin

It didn't take long until skills became a key element in our agentic development workflow. At that moment a skill stopped being "that SKILL.md I keep in one project" and became something we want on every machine, for every teammate, without copy-pasting a folder around. That's the point where you package it into a plugin.

A plugin is a container: it bundles one or more skills plus optionally commands, agents, hooks, and MCP servers into a single installable unit with a manifest. Skills are the "what to do", plugins are the "how you get it onto someone else's machine".

Our first approach: using git submodules

Our first approach was through centralizing all our skills in a separate Git repo and share it between projects by using git submodules. That approach worked but felt more like a hack than a final solution.

The better approach: wrap it in a plugin

A plugin is just a directory with a manifest and a conventional layout:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── commands/                 # optional
├── agents/                   # optional
├── hooks/
│   └── hooks.json            # optional
└── .mcp.json                 # optional

Remark: the manifest has to live in .claude-plugin/, but every component directory (skills/, commands/, agents/, hooks/) has to sit at the plugin root, not nested inside .claude-plugin/. Mix those up and auto-discovery silently fails.

Step 1: move the skill into skills/

If you already have a skill folder, move it as-is under skills/:

api-testing-plugin/
└── skills/
    └── api-testing/
        ├── SKILL.md
        ├── scripts/
        │   └── test-runner.py
        └── references/
            └── api-spec.md

Claude Code scans skills/ for any subdirectory containing a SKILL.md and loads it automatically. Nothing about the skill's frontmatter or content needs to change.

Step 2: write the manifest

At minimum, plugin.json just needs a name:

{
  "name": "api-testing-plugin"
}

But it's worth filling in a bit more so people know what they installed:

{
  "name": "api-testing-plugin",
  "version": "1.0.0",
  "description": "Skills for API testing and contract validation",
  "author": {
    "name": "Bart Wullems"
  },
  "license": "MIT"
}

Name must be kebab-case, unique, no spaces.

Step 3: reference files with ${CLAUDE_PLUGIN_ROOT}

If any script or hook inside your plugin needs to point at another file in the plugin, never hardcode the path. Plugins install in different locations depending on how the user installed them (marketplace, local, npm). Use the environment variable instead:

#!/bin/bash
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

Same rule applies inside hooks.json or .mcp.json:

{
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh"
}

Tip: if you're only shipping skills and nothing else, you can skip commands/, agents/, hooks/, and .mcp.json entirely — only create the directories your plugin actually uses.

Step 4: bundling more than one skill

Nothing stops a single plugin from carrying several related skills. That's the whole point of packaging in the first place:

api-testing-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── api-testing/
    │   └── SKILL.md
    └── database-migrations/
        └── SKILL.md

Each one is registered as <plugin-name>:<skill-name>, so naming collisions across plugins aren't a concern.

Installing the plugin

Once the folder structure and manifest are in place, there are a few ways to get the plugin loaded, depending on where you are in the process.

Quick local test: --plugin-dir

For a fast sanity check while you're still iterating, point Claude Code at the folder directly, no install step needed:

claude --plugin-dir ./api-testing-plugin

That loads it for the session only. Good for "does this even work" before you commit to anything.

The real thing: install from a marketplace

For anything you want to share with a team or reinstall on another machine, publish it through a plugin marketplace, then:

claude plugin install api-testing-plugin@my-plugins

By default that installs at user scope — available to you across every project. Add --scope project to write it into .claude/settings.json instead, so it's shared with anyone who clones the repo:

claude plugin install api-testing-plugin@my-plugins --scope project

Publishing to a marketplace

Installing from a local folder or ~/.claude/skills/ covers you and maybe your immediate team. To make the plugin something anyone can add with a one-liner — /plugin install my-plugin@my-plugins — you need a marketplace.

A marketplace is nothing exotic: it's a git repository with one extra file, .claude-plugin/marketplace.json, that lists where your plugins live. It doesn't have to contain the plugins itself — it just points at them.

Step 1: create the marketplace file

At the root of a (new or existing) repository:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── api-testing-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── api-testing/
                └── SKILL.md

{
  "name": "my-plugins",
  "owner": {
    "name": "Bart Wullems"
  },
  "plugins": [
    {
      "name": "api-testing-plugin",
      "source": "./plugins/api-testing-plugin",
      "description": "Skills for API testing and contract validation"
    }
  ]
}

Remark: source here is relative to the marketplace root (where .claude-plugin/ sits), not to marketplace.json itself. Don't reach outside that root with ../ — Claude Code refuses it, and copied plugins can't pull in files that live outside their own directory anyway.

If the plugin already lives in its own repo, point at that instead of nesting it inside the marketplace repo:

{
  "name": "api-testing-plugin",
  "source": {
    "source": "github",
    "repo": "wullemsb/api-testing-plugin"
  },
  "description": "Skills for API testing and contract validation"
}

Step 2: validate before you push

claude plugin validate .

Run this from the marketplace root. It checks marketplace.json syntax, flags duplicate plugin names, and validates that plugin's own plugin.json and SKILL.md frontmatter too. Cheaper to catch a typo here than after someone else tries to install it.

Step 3: push and share

Any git host works, but GitHub is the easiest path — version control and issue tracking come for free. Push the repo, then anyone adds it with:

/plugin marketplace add https://github.com/wullemsb/my-marketplace.git

or, for a non-GitHub host:

/plugin marketplace add https://gitlab.com/wullemsb/my-marketplace.git

From there, installing a specific plugin is the same command from the previous section:

/plugin install api-testing-plugin@my-plugins

Tip: if you want your whole team to get the marketplace automatically the moment they trust the project folder — no separate /plugin marketplace add step, add it to .claude/settings.json in the project repo under extraKnownMarketplaces, optionally with enabledPlugins to turn specific plugins on by default.

Keeping it updated

Push a new commit, bump version in plugin.json if you set one there, and users pick it up with:

/plugin marketplace update

Remark: if you never set version at all, Claude Code just tracks the resolved git commit. Every push is an update automatically. That's the simpler default for an internal or fast-moving plugin; pin a version once you want updates to be deliberate.

Once installed, Claude Code discovers the skills the moment the plugin is enabled, no restart required.

That's it! One folder, one manifest, and a skill that used to live in a single project is now something you install anywhere.

More information

• Claude Code plugin structure reference: https://code.claude.com/docs/en/plugins-reference
• Anthropic's official plugin-structure skill: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md
• Plugin installation scopes and CLI commands: https://code.claude.com/docs/en/plugins-reference#plugin-installation-scopes