Skip to main content

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

Labels:

Popular posts from this blog

Podman– Command execution failed with exit code 125

After updating WSL on one of the developer machines, Podman failed to work. When we took a look through Podman Desktop, we noticed that Podman had stopped running and returned the following error message: Error: Command execution failed with exit code 125 Here are the steps we tried to fix the issue: We started by running podman info to get some extra details on what could be wrong: >podman info OS: windows/amd64 provider: wsl version: 5.3.1 Cannot connect to Podman. Please verify your connection to the Linux system using `podman system connection list`, or try `podman machine init` and `podman machine start` to manage a new Linux VM Error: unable to connect to Podman socket: failed to connect: dial tcp 127.0.0.1:2655: connectex: No connection could be made because the target machine actively refused it. That makes sense as the podman VM was not running. Let’s check the VM: >podman machine list NAME         ...
Read more

Cache stampede: when our cache turned against us

While investigating some performance issues, we ran into an ASP.NET Core API that cached a fairly expensive aggregation query for 60 seconds. Under normal load, that was fine: one request rebuilds the cache, everyone else reads from it. Under peak load, dozens of requests would arrive in that same expiry window, all see a cache miss, and all fire the same expensive query in parallel. The database didn't like that. That was the moment when our caching layer stopped helping and started hurting. A burst of requests comes in at the same time, all miss the cache, and all go hammer the database or the downstream API at once. That's a cache stampede . The cache was supposed to protect our backend, and for a few hundred milliseconds it did the opposite. Why this happens IMemoryCache.GetOrCreate (and its async sibling) looks like it protects you, but it doesn't add any locking on its own. Look at the naive version: public async Task<Report> GetReportAsync(string key) ...
Read more

VS Code Planning mode

After the introduction of Plan mode in Visual Studio , it now also found its way into VS Code. Planning mode, or as I like to call it 'Hannibal mode', extends GitHub Copilot's Agent Mode capabilities to handle larger, multi-step coding tasks with a structured approach. Instead of jumping straight into code generation, Planning mode creates a detailed execution plan. If you want more details, have a look at my previous post . Putting plan mode into action VS Code takes a different approach compared to Visual Studio when using plan mode. Instead of a configuration setting that you can activate but have limited control over, planning is available as a separate chat mode/agent: I like this approach better than how Visual Studio does it as you have explicit control when plan mode is activated. Instead of immediately diving into execution, the plan agent creates a plan and asks some follow up questions: You can further edit the plan by clicking on ‘Open in Editor’: ...
Read more