/plugin-creator

name: plugin-creator
description: >
  Build, validate, and distribute Claude Code plugins — the packaged form of
  skills, agents, hooks, MCP/LSP servers, monitors and `bin/` executables, with
  a `.claude-plugin/plugin.json` manifest and optionally a `marketplace.json`
  catalog. Use this whenever the user wants to make, package, ship, share, or
  publish an extension: "turn this into a plugin", "make this a Claude
  extension", "package my skills", "publish to a marketplace", "share this with
  my team", "convert .claude/ into a plugin", "plugin.json", "marketplace.json",
  "/plugin install". Also use when a plugin already exists and something is
  wrong with it — components not loading, skills not showing up, hooks not
  firing, `claude plugin validate` failing. Reach for this even when the user
  says "skill" but describes distribution (versioning, install, teammates,
  GitHub), because that is a plugin, not a bare skill.

plugin-creator — build and ship a Claude Code plugin

**In:** skills/agents/hooks you already have, or an idea for some. **Out:** a directory that `claude plugin validate` passes, that loads under `claude --plugin-dir`, and that a stranger can install.

A plugin is just a directory with a known shape. Almost everything that goes wrong is the shape being slightly off, and the CLI will tell you — so the whole job is: build the shape, run the validator, load it for real, fix what it says.

First decide: does this need to be a plugin at all?

| | Standalone `.claude/` | Plugin | |---|---|---| | Invocation | `/hello` | `/my-plugin:hello` | | For | one project, personal, experiments | sharing, versioning, reuse across projects |

If the user is customizing one repo for themselves, `.claude/skills/<name>/SKILL.md` is the whole answer and a plugin is packaging they will never use — say so and stop. Convert to a plugin when someone else has to install it.

Reach for `skill-creator` instead when the work is *authoring one skill's content* (what it says, how it triggers, evaluating it). This skill is about the container. They compose: write the skills with `skill-creator`, ship them with this.

The loop

Everything here is verifiable, so never hand-reason about whether a layout is right — run the command.

claude plugin init <name> --with skills agents hooks   # scaffold (optional)
python3 scripts/preflight.py ./<path>                  # layout + sources
claude plugin validate ./<path> --strict               # manifest JSON
claude --plugin-dir ./<path>                           # load it for real

1. **Scaffold or lay out the directories.** `claude plugin init <name>` writes a working skeleton to `~/.claude/skills/<name>/` — which auto-loads next session as `<name>@skills-dir` with no install step, so it is the fastest way to iterate. `--with skills agents hooks mcp lsp output-style channel` adds examples of each. For a plugin that lives in a repo instead, create the directories yourself (layout below) — `init` always targets the skills dir. 2. **Write the manifest**, if you need one. It is optional: with no manifest, components are auto-discovered from default locations and the name comes from the directory. Add one when you want metadata (version, author, license) or non-default component paths. 3. **`claude plugin validate`.** Wrong-typed fields are errors; unrecognized fields are warnings that still load. Use `--strict` before publishing so a typo'd key (`skill` for `skills`) fails instead of silently doing nothing. 4. **Load it: `claude --plugin-dir ./<path>`.** Confirm skills appear under `/help`, agents under `/context`, and that hooks actually fire.

**`validate` is a manifest linter, not a plugin checker — this is the part that catches people out.** Measured against the real CLI, all three of these pass with exit 0:

• components nested inside `.claude-plugin/` (the plugin loads nothing)
• a marketplace entry whose `source` path does not exist (every install breaks)
• any component file being missing, malformed, or empty

And a plugin with a root `SKILL.md` and no manifest **fails** validation (`No manifest found in directory`) even though it is valid at runtime. So a green `validate` means "the JSON is well-formed", nothing more.

`scripts/preflight.py` covers exactly that gap — nesting, unresolvable marketplace sources, missing `SKILL.md`, absent frontmatter, a manifest key shadowing its default directory, `bun` hooks, hardcoded paths. Run it *and* `validate`; they check disjoint things. Neither replaces loading the plugin, so never report a plugin as working on the strength of either alone. 5. **Iterate with `/reload-plugins`** rather than restarting — it picks up skills, agents, hooks, and plugin MCP/LSP servers. Monitors need a restart.

Use `claude plugin details <name>` to see the component inventory and projected token cost — the honest answer to "what does installing this actually cost the user's context", which is worth checking before you ship something large.

Layout

The one mistake worth memorizing: **only `plugin.json` goes inside `.claude-plugin/`.** Every other directory sits at the plugin root. Components nested under `.claude-plugin/` are silently not found — nothing errors, they just never appear, which reads like "my skill doesn't work" rather than "my directory is one level too deep".

my-plugin/
├── .claude-plugin/plugin.json   # manifest, and nothing else
├── skills/<name>/SKILL.md       # skills
├── agents/<name>.md             # subagents
├── hooks/hooks.json             # hooks
├── workflows/                   # workflow scripts
├── output-styles/ · themes/     # styles, colour themes
├── monitors/monitors.json       # background watchers
├── .mcp.json · .lsp.json        # MCP and LSP servers
├── bin/                         # executables added to Bash PATH
├── settings.json                # defaults (only `agent`, `subagentStatusLine`)
└── scripts/ · LICENSE · README.md