Build Plugin

Phase 1: Analyze

Decide what goes in the bundle before you build the folder.

1. Inventory the tools. List every skill, hook, agent, and MCP server the plugin should carry. A plugin can hold any mix; each type sits in its own place in the layout (see assemble.md).
2. Draw the boundary. One plugin is one coherent unit that updates together. If two groups of tools serve different audiences or version on different clocks, that is two plugins.
3. Name it. Kebab-case, distinct, describes the bundle not one tool inside it. The name becomes the skill namespace (/my-plugin:skill) and the marketplace entry key.
4. Note what already exists loose. Tools sitting in ~/.claude/skills, ~/.claude/agents, or a personal settings.json will move into the plugin and the loose originals get deleted, so you do not run duplicates (assemble.md covers this).

Deliverable: the plugin name plus a list of what it will contain. Confirm with the user before assembling.

Phase 2: Assemble

Read references/assemble.md. Build the folder to the layout, write the manifest, then test locally.

1. Create the plugin dir. Only plugin.json goes inside .claude-plugin/; skills/, agents/, hooks/hooks.json, and .mcp.json sit at the plugin ROOT.
2. Write .claude-plugin/plugin.json with name, description, version, author.
3. Move the inventoried tools in and delete the loose originals.
4. Validate, then load-test. claude plugin validate . checks the manifest and layout with no login. claude plugin details <name> lists the skills, hooks, and servers it discovered, also login-free. claude --plugin-dir ./my-plugin (it also accepts a .zip) loads it into a live session so you can invoke a tool; that one needs you logged in.

For a "Just me" bundle this is the last substantive phase: it is loaded, it works, stop.

Phase 3: Ship

Only for team or public. Read references/marketplace.md, and references/team-enablement.md for the auto-enable path. Branch on the git-host answer.

1. Create the marketplace repo, or reuse an existing one. Add .claude-plugin/marketplace.json at its root with name, owner, and a plugins[] entry for this plugin.
2. Set the entry source by host: relative "./path" if the plugin lives in the same repo, {source:"github", repo:"owner/repo"} for GitHub, or {source:"url", url:"https://...git"} for GitLab, Bitbucket, or self-hosted. There is no gitlab source type.
3. Choose public vs private to match the audience. A private repo keeps a team plugin internal; a public repo is installable by anyone who knows it, running arbitrary code with the user's privileges, so make that choice deliberately.
4. Confirm the install path a colleague runs: /plugin marketplace add owner/repo (GitHub shorthand) or the full https://...git URL for any other host, then /plugin install name@marketplace.

Phase 4: Maintain

Read references/maintain.md. Branch lightly; the mechanics are the same across hosts.

1. Updates. Users pull new versions with /plugin marketplace update or at startup.
2. Version boundary. Bump version in plugin.json so users get a clean update boundary; omit it and Claude Code treats every commit SHA as a new version.
3. Ownership. One maintainer per plugin. Fixes land via merge request, since the source is a git repo.
4. Org controls (team/public, admin job). Force-install, an allowlist (strictKnownMarketplaces), or a denylist (blockedMarketplaces) live in a managed-settings file, set by an admin, not per user (team-enablement.md).

Done criteria

• The plugin validates (claude plugin validate) and its tools show up (claude plugin details); loading it via claude --plugin-dir in a session invokes at least one.
• It is on a marketplace repo the resolved audience can reach, public or private matching that audience (or, for "Just me", it is loaded locally and there is no marketplace).
• The user can name exactly how a colleague installs it, two-command or one-click, matching the audience answer.