Packaging so a new machine is one install away

The setup that only exists on one laptop

So you already have a setup — /goals command forcing the agent to declare its intent before starting work on a feature, /review command which the team actually uses, maybe even a commit hook that doesn't let you do some things; all of it in your home directory. But this setup is far from perfect, there are four problems with it:

• if you get a new machine — you'll need to recreate it based on memory and will forget about sth

• if a teammate tries to /review — you'll zip it for them but won't send them the fix of a bug you've found later

• if you have a second repo — you'll clone your home directory there, from now on two versions of the setup will evolve in separate places

• and whenever somebody asks which version everyone is on — you'll have no answer, because nothing is versioned

So it's not that you're missing a tool. Every harness has a way to install a custom bundle from a git remote (except one, but even in that case it can read a directory which you can version using git). It's just that you already have a setup on the machine in front of you.

Dotfiles territory, you might say — there's a symlink script that does it

I'd say — for one person, for some time. And then it stops working at four different levels:

• versions — you can't say "we're on 0.3", you can't revert to yesterday's version, you don't know if the bug somebody found is in their version of your symlink script

• paths — every harness expects a bundle in a different place and the differences actually matter (one requires the manifest at the plugin root level, another one can't find it unless it's in a dot-directory), so for each tool you need to create a new branch in the script

• scope — symlinks are binary, most of the harnesses come with an option to set up the install scope so a bundle is enabled on one project and disabled everywhere else (you'll need this as soon as you have a skill that's needed in one repo and not needed in others)

• the clone (which is what makes all the difference) — in order to set up your symlink script you need to run it, but if somebody clones your repo they don't run it; they clone and start the agent and there's nothing

So we can change the goal, from installing sth to installing nothing. One install is good, zero installs is available — and it's the same amount of work.

Three nouns, and only three

Let's start by setting up the vocabulary, because there are three terms which almost every tool uses and they're nearly identical once you line them up:

• component — a single thing that does sth (skill directory with SKILL.md, an agent, a hook config, MCP server entry or LSP server entry)

• plugin — a folder of components with a manifest in which you list and version them; it's what people install

• marketplace — a file with the catalogue of plugins with their locations; it's what people subscribe to

In theory you can distribute a plugin without a marketplace but I recommend having one anyway, even for a single plugin. Because installing directly from a repo path is being deprecated — look, the Copilot CLI 1.0.77 already prints Direct plugin installs (repos, URLs, local paths) are deprecated. Only plugin@marketplace installs will be supported in a future release. when you do it. The catalogue file is about fifteen lines long, and it's the difference between sth you can hand somebody and sth you have to explain to them.

The repo

So let's create a repo with a nested directory inside (for the plugin) and put a marketplace file there which will point to it. I'll show you the marketplace file (which we're going to create today as part of this lesson), and also the manifest for the plugin itself:

team-kit/
├── .claude-plugin/
│   └── marketplace.json          # the catalog: which plugins live here
└── plugins/
    └── team-kit/
        ├── .claude-plugin/
        │   └── plugin.json       # the plugin's own manifest
        ├── plugin.json           # the same content again, at the root
        └── skills/
            └── goals/
                └── SKILL.md      # the skill you already wrote

{
  "name": "team-kit",
  "owner": { "name": "Acme Engineering" },
  "metadata": {
    "description": "Acme's shared agent setup: one install on a new machine.",
    "version": "0.1.0"
  },
  "plugins": [
    {
      "name": "team-kit",
      "source": "./plugins/team-kit",
      "description": "The skills, agents and hooks our team expects on every machine."
    }
  ]
}

{
  "name": "team-kit",
  "version": "0.1.0",
  "description": "The skills, agents and hooks our team expects on every machine.",
  "author": { "name": "Acme Engineering" }
}

The thing is, Claude Code 2.1.220 doesn't like it when a plugin has its manifest only at the root level — it says No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json — and Antigravity CLI 1.1.9 doesn't like it when the manifest isn't at the root level, it says missing plugin.json. Neither of them checks where the other one looks, and both are fine with the same file content, so we just duplicate six lines and that's the cheapest way to make it work. Copy one into the other in whatever check you already run, so they can never get out of sync.

One repo for multiple harnesses, seriously

Worth knowing before you decide how much to build, because it's less work than you might think.

Claude Code and Codex read the same catalogue file. I pointed Codex CLI 0.146.0 at the repo above — untouched, nothing renamed — and it resolved that repo's .claude-plugin/marketplace.json, printed the path it had resolved, and installed from it. Copilot CLI installs the same plugin directory too, and .claude-plugin/plugin.json is one of the locations it looks for a manifest in.

If you need a different manifest or a different way to install a bundle — there are a few more harnesses:

• Cursor, which looks for .cursor-plugin/

• Gemini CLI, which doesn't have any plugins at all but extensions instead, with a separate manifest and a separate command to install

• and one which doesn't even come with a way to install a bundle, it can just read directories

The variant below has the shape for whichever one you're on.

What not to put in it

Once you can install sth, you can distribute it. So the standards are higher:

• don't include your credentials in hook scripts, MCP server entries or env defaults — bundles might end up on machines you don't control

• don't put absolute paths from your own machine in there (sth like /Users/you/work/scripts/lint.sh is the most common reason why a bundle stops working for anyone but its author)

• don't add all your experiments to it — keep them in your home directory

The last one has a measurable cost and not just a tidiness argument. claude plugin details prints a projected token bill for what you're shipping; for the single-skill plugin above it reported Always-on: ~25 tok added to every session, with the skill itself around 30 tokens always-on and another 40 per activation. Those numbers are estimates and the tool says so — but look at what the always-on half actually is: the part it adds to every session whether or not the skill ever fires. So 40 skills nobody uses is not free.

Check it actually landed

Packaging fails quietly. If you put the manifest in a wrong place nothing breaks — your bundle just isn't there, and you find it out when a teammate says they can't see the skill on their machine. So run your harness's list command immediately after installing and check that the specific component is in the output, not just the plugin. And then put the validator in CI, so that a broken manifest fails on the branch instead of on somebody's laptop.

Just beware though that Claude Code 2.1.220 validates the marketplace file without validating the plugins it points at. I removed the plugin's entire .claude-plugin directory, ran claude plugin validate . --strict against the marketplace, and it still came back Validation passed. So add a validation step for every plugin path as well, otherwise CI will keep telling you the repo is fine while it ships nothing.

Versioning, and the update nobody gets

If you can install sth — you should version it. The version field in the manifest is not decorative; increment it with every change and tag the commit, so that later when somebody comes to you and says "the deploy skill doesn't work on my machine" you can ask them which version they have and point at a specific commit. Without it you're looking at the last five edits and guessing which one they're on.

Then decide, on purpose, whether installs float or pin. If they float, everyone gets your fix with their next update — and everyone also gets the results of the bad afternoon you had. If you pin to a tag or a ref, it's you who decides when the team moves. For a small team I'd float it but tag anyway, so there's always a known-good ref to send sb back to. If there's a compliance story, pin.

Either way it's on you now. A bundle nobody updates quietly rots, and "install once" turns into "install once, in March".

The version that needs no install at all

Claude Code, Codex and Copilot each have a settings file that can name a marketplace and an enabled plugin declaratively. Commit it to the repo and the clone does the installing — nobody types a command.

And you don't even need to author it. Installing the plugin at project scope made Claude Code write the project's own .claude/settings.json, and this is the shape it produced, with the local source directory standing in for the remote you'd really point at:

{
  "extraKnownMarketplaces": {
    "team-kit": {
      "source": { "source": "directory", "path": "/Users/you/src/team-kit" }
    }
  },
  "enabledPlugins": { "team-kit@team-kit": true }
}

So replace that path with the actual remote, commit the file, and every new team member's clone is supposed to come with the team's skills already in it. That's the finish line worth aiming at, and the reason to package rather than to keep a good symlink script. But before you commit it — think about:

• what if they don't want your bundle? A marketplace entry in a shared repo is a way of saying "trust me", so make sure it's as reviewable as everything else in the tree

• what if they have different preferences? Those are personal and belong in their own settings, which is exactly what the separate scopes are for

When this is over-engineering

One skill, one machine, one repo — a directory is the right answer there and a manifest is just ceremony.

The line isn't size, it's copies: the moment the same procedure exists in two places, one of them is already stale and you just haven't found out yet.

So once it's on a second machine, or for a second person, or in a second repo — package it. Until then, keep writing skills.