--- name: create-update-claude-plugin description: > Use this skill when creating, updating, debugging, validating, or publishing Claude Code plugins and mods — scaffolding `.claude-plugin/plugin.json`, authoring skills, commands, subagents, hooks, MCP/LSP servers, monitors, themes, output styles, and `bin/` executables, writing a mods hooks module (`register`, `ui.render`, `$` API), declaring dependencies and release tags, running `claude plugin validate`, `claude plugin test`, `claude plugin eval`, and `--plugin-dir` sessions, or migrating a standalone `.claude/` setup into a distributable plugin. Trigger on "Claude Code plugin", "plugin manifest", "plugin.json", "mods", "hooks module", "plugin marketplace", "plugin eval", "plugin validate", or packaging workflows for distribution. license: MIT compatibility: claude-code, codex, chatgpt, hermes, opencode, copilot, antigravity allowed-tools: bash, read, write, edit metadata: audience: developers workflow: plugin-development --- # Claude Code Plugin Development A plugin is a directory that Claude Code loads as one unit. It can hold skills, commands, subagents, hooks, a hooks module (a "mod"), MCP servers, LSP servers, monitors, output styles, themes, executables, default settings, and an eval suite. Most plugins come from a marketplace; you can also load one straight from disk with `--plugin-dir`. ## Pick the right extension point Before scaffolding, confirm the component matches the job. Choosing wrong produces a plugin that loads but never fires. | Need | Component | Why | |------|-----------|-----| | Instructions Claude should load when relevant | **Skill** | Model-invoked by description, or user-invoked by command | | A rule that must hold every time (block edits, format on write) | **Hook** | Fires on lifecycle events regardless of what the model reads | | External system's tools/data | **MCP server** | Gives Claude new tools | | Diagnostics and code navigation | **LSP server** | Language-aware tooling | | A pane, a band above the prompt, a custom command, or taking over a tool call | **Mod** | Runs JS/TS inside Claude Code | | A background process streaming notifications | **Monitor** | Long-lived shell command, stdout becomes notifications | | A CLI tool Claude can call by name | **`bin/`** | Added to the Bash tool's `PATH` | | Reusable prose that isn't always-on context | **Skill**, never `CLAUDE.md` | A plugin-root `CLAUDE.md` is not loaded | ## Plugin structure Only `plugin.json` goes inside `.claude-plugin/`. Every component lives at the plugin root. ```text my-plugin/ ├── .claude-plugin/ │ ├── plugin.json # manifest — required │ └── types/ # PluginState declarations for mods ├── skills//SKILL.md # or one SKILL.md at the root ├── commands/ # legacy flat .md commands ├── agents/ # one .md per subagent; subfolders allowed ├── hooks/ │ ├── hooks.json # settings hooks, and/or a "modules" key │ └── register.js # mods entry point (only if "modules" is set) ├── .mcp.json # MCP servers ├── .lsp.json # LSP servers ├── monitors/monitors.json # background monitors ├── output-styles/.md ├── themes/.json ├── bin/ # executables, appended after the user's PATH ├── settings.json # only `agent` and `subagentStatusLine` apply ├── scripts/ # helper scripts called by hooks/MCP ├── evals/ # eval suite └── package.json # Node deps (auto-installed when lockfile present) ``` > **Hard rule:** component directories placed inside `.claude-plugin/` never load. The plugin root is the directory you pass to `--plugin-dir`, not `~/.claude/`. ## Workflow: create a plugin 1. **Scaffold.** Either `claude plugin init --with skills` (writes `~/.claude/skills//`, loads next session as `@skills-dir`) or `mkdir -p /.claude-plugin`. 2. **Write the manifest.** `name` is required; it prefixes every skill and agent. Add `version` as soon as anyone installs it — the version is the cache key, so edits without a bump never reach installed copies. 3. **Add components.** Add only the directories you use. Register anything with a runtime cost (hooks, MCP servers, monitors) deliberately: they run in every session where the plugin is enabled. 4. **Validate.** `claude plugin validate ./ --strict` checks the manifest and the frontmatter of every skill, agent, and command. It does **not** read `.lsp.json`. 5. **Run it.** `claude --plugin-dir ./`. Skills run as `/:`; agents appear as `:`; hooks fire from session start. 6. **Iterate.** Run `/reload-plugins` after editing any component. A hooks module loaded via `--plugin-dir` also hot-reloads when you save. 7. **Share.** Add it to a marketplace, or hand over the directory or a `.zip`. ## Workflow: update an existing plugin 1. **Inspect.** `claude plugin list` shows installed plugins and load errors; `/plugin` → **Installed** lists the components Claude Code found, and **Errors** shows what failed. 2. **Change files.** Keep relative paths in the manifest (`./...`). Editing an installed plugin's cache has no effect — develop against the source with `--plugin-dir`. 3. **Bump `version`.** Installed copies update only when the version changes. 4. **Re-validate and test.** `claude plugin validate ./ --strict`, then `claude plugin test` for a mod and `claude plugin eval ./` for behavior regressions. 5. **Tag the release** if other plugins depend on yours: `claude plugin tag --push` writes `--v`. ## Workflow: convert an existing `.claude/` setup 1. Create `/.claude-plugin/plugin.json` beside `.claude/`. 2. Copy `commands/`, `agents/`, and `skills/` into the plugin root (skip any you don't have). 3. Move the `hooks` object from `.claude/settings.json` into `/hooks/hooks.json`, unchanged in shape. 4. Validate, then load with `--plugin-dir` and check each component under its new name. 5. Only after verifying, delete the originals. Skills and agents don't collide because the plugin copies carry the `:` prefix — hooks have no prefix, so a hook left in both places runs twice. ## Gotchas that break plugins - **Wrong directory.** `skills/`, `agents/`, `hooks/` inside `.claude-plugin/` load nothing. - **Unbumped version.** Installed copies are cached per version; edits silently don't apply. - **Root `SKILL.md` with no `name`.** A marketplace install names the skill after its cache directory. Set `name` in the frontmatter. - **`CLAUDE.md` at the plugin root.** Never loaded. Write a skill, or a hook if the rule must always apply. - **`bin/` shadowing.** Plugin `bin/` comes *after* the user's `PATH`, so you can't override `git` or `ls`. claude.ai and Cowork refuse a plugin with a top-level `bin/`. - **`${user_config.*}` in monitors.** Monitors never receive user config, and a monitor that references it doesn't start. Use exec-form `args` or read `CLAUDE_PLUGIN_OPTION_`. - **Unquoted `${CLAUDE_PLUGIN_ROOT}`.** In shell-form `command`, wrap it in double quotes so the expanded path stays one word. - **Assuming `.lsp.json` is validated.** It isn't. One invalid entry makes Claude Code skip the whole file at load time. - **Two enabled plugins with the same `name`.** One of them registers its hooks and the other's are dropped. - **Context cost.** Every skill and agent name plus description sits in context on every turn of every session where the plugin is enabled. Keep descriptions tight and let unused plugins be disabled. ## Reference triggers Load a reference only when the task needs its detail. | Reference | Load when | File | |-----------|-----------|------| | Manifest schema | Writing `plugin.json`, `userConfig`, channels, dependencies, settings precedence, path variables | `references/manifest-schema.md` | | Components | Authoring skills, commands, subagents, or `hooks/hooks.json` | `references/components-guide.md` | | Integrations | MCP, LSP, monitors, `bin/`, themes, output styles, default settings | `references/integrations-guide.md` | | Mods | Writing a hooks module, `ui.render` drawings, `$` API, mod tests, mod troubleshooting | `references/mods-guide.md` | | Evals | Writing cases and graders, mocks, CI gating, reading results | `references/evals-guide.md` | | CLI & release | Loading layers, local dev loop, marketplaces, versioning, migration, debugging, dependency resolution | `references/cli-and-tools.md` | | Upstream docs | Checking exact upstream wording, a field name, or a page the digest does not cover | `references/docs/` (32 pages) | `references/docs/` holds the unmodified Claude Code plugin pages (32 files), each starting with ``. Load them when this digest and the live docs disagree; refresh before changing a rule that a page overrides. ## Scripts Bundled Node-only checks (run from this skill's directory): ```bash # Scaffold a plugin directory node scripts/scaffold_plugin.ts ./my-plugin --name my-plugin \ --with-skill --with-command --with-hooks --with-mcp # Structure: manifest, paths, skills/agents/commands, hooks, settings node scripts/validate_plugin_structure.ts ./my-plugin # MCP: .mcp.json, manifest mcpServers, channels, ${user_config.*} refs node scripts/validate_plugin_mcp.ts ./my-plugin ``` These complement `claude plugin validate`; the CLI remains authoritative for frontmatter and marketplace rules. ## Validation checklist - [ ] `.claude-plugin/plugin.json` is valid JSON with a kebab-case `name` (no spaces, not starting with `claude-`). - [ ] No component directory sits inside `.claude-plugin/`. - [ ] Every custom manifest path is relative and starts with `./`. - [ ] A root-level `SKILL.md` sets `name` in its frontmatter. - [ ] Skills that must not auto-trigger set `disable-model-invocation: true`. - [ ] Hook and monitor scripts are executable and have valid shebangs. - [ ] Shell-form hook commands double-quote `${CLAUDE_PLUGIN_ROOT}`; exec-form uses `args`. - [ ] `${user_config.*}` appears only where it is substituted (skill/agent text, MCP/LSP config), never in a monitor. - [ ] State written at runtime goes to `${CLAUDE_PLUGIN_DATA}`, never `${CLAUDE_PLUGIN_ROOT}`. - [ ] `.lsp.json` was reviewed by hand, since `validate` skips it. - [ ] `claude plugin validate --strict` passes, and the skill/agent frontmatter was checked. - [ ] A `--plugin-dir` session ran every component under its namespaced name.