From ai-toolkit-dev
Use when authoring, configuring, testing, or shipping a Claude Code plugin. Covers the `plugin.json` manifest (all fields including `lspServers`, `monitors`, `themes`, `outputStyles`, `userConfig`, `channels`, `dependencies`, `$schema`), naming conventions, plugin lifecycle and storage (`${CLAUDE_PLUGIN_ROOT}` vs `${CLAUDE_PLUGIN_DATA}`, scope union, hot-swap, GC, `--keep-data`), local testing with `--plugin-dir`, headless benchmarking, the `claude plugin` CLI, releases, troubleshooting, and per-capability authoring (agents, commands, hooks, MCP, bins, LSP, monitors, themes, output styles, channels). Triggers on "create plugin", "build a plugin", "scaffold plugin", "plugin manifest", "plugin.json", "${CLAUDE_PLUGIN_ROOT}", "${CLAUDE_PLUGIN_DATA}", "add a hook", "add a command", "add an agent", "add a skill to my plugin", "make a skill", "bundle MCP server", "add LSP", "plugin dependencies", "test my plugin locally", "plugin not loading".
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-toolkit-dev:plugin-devThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A **plugin** is a directory with a `.claude-plugin/plugin.json` manifest plus capability folders. Claude Code discovers components by convention; the manifest names the plugin and declares optional fields.
references/config/dependencies.mdreferences/config/manifest.mdreferences/config/naming.mdreferences/config/persistent-data.mdreferences/config/user-config.mdreferences/development-cycle/cli.mdreferences/development-cycle/lifecycle-and-storage.mdreferences/development-cycle/release.mdreferences/development-cycle/testing.mdreferences/development-cycle/troubleshooting.mdreferences/topics/agent-development/examples/agent-creation-prompt.mdreferences/topics/agent-development/examples/complete-agent-examples.mdreferences/topics/agent-development/references/agent-creation-system-prompt.mdreferences/topics/agent-development/references/system-prompt-design.mdreferences/topics/agent-development/references/triggering-examples.mdreferences/topics/agent-development/scripts/validate-agent.shreferences/topics/command-development/README.mdreferences/topics/command-development/examples/plugin-commands.mdreferences/topics/command-development/examples/simple-commands.mdreferences/topics/command-development/references/advanced-workflows.mdA plugin is a directory with a .claude-plugin/plugin.json manifest plus capability folders. Claude Code discovers components by convention; the manifest names the plugin and declares optional fields.
my-plugin/
└── .claude-plugin/
└── plugin.json
{
"name": "my-plugin",
"description": "What this plugin does"
}
That's enough to load via claude --plugin-dir ./my-plugin. Auto-discovered conventional layout adds capabilities:
my-plugin/
├── .claude-plugin/plugin.json
├── commands/ # slash commands (.md per command)
├── agents/ # subagents (.md per agent)
├── skills/ # skills (subdir per skill, with SKILL.md inside)
├── hooks/hooks.json # event handlers
├── bin/ # CLI scripts (auto-PATHed)
├── .mcp.json # MCP server defs
└── ...
| Variable | Lifetime | Use for |
|---|---|---|
${CLAUDE_PLUGIN_ROOT} | replaced on every plugin update | bundled assets that ship with the plugin |
${CLAUDE_PLUGIN_DATA} | survives plugin updates | mutable state, deps installs, caches |
Both substitute in skill / agent content, hook / monitor commands, and MCP / LSP configs; both are exported as env vars to subprocesses.
/reload-plugins picks up edits to skills, commands, agents, MCP, LSP. Hooks always require a full session restart. See references/development-cycle/lifecycle-and-storage.md for details.
The top-level skill-creator skill is the canonical entry point for skill authoring (description tuning, progressive disclosure, evals). This plugin-dev skill covers plugin-level concerns; for just writing a skill, use skill-creator instead.
| If the user wants to… | Read |
|---|---|
| Configure the plugin | references/config/ — manifest, deps, naming, settings, persistent data |
| Test, iterate on, debug, or ship | references/development-cycle/ — --plugin-dir, CLI, releases, troubleshooting, runtime mechanics |
| Author a specific capability | references/topics/ — agents, commands, hooks, MCP, bins, LSP, monitors, themes, channels |
references/config/| File | When to read |
|---|---|
config/manifest.md | Every plugin.json field, including modern ones, plus path-replacement vs additive semantics |
config/dependencies.md | The dependencies array — semver ranges, tag-based resolution, cross-marketplace deps, claude plugin prune |
config/naming.md | Naming conventions for plugins, skills, commands, agents, bins |
config/user-config.md | The userConfig field — schema (NOT JSON Schema), ${user_config.KEY} substitution, CLAUDE_PLUGIN_OPTION_<KEY> env vars |
config/persistent-data.md | Patterns for using ${CLAUDE_PLUGIN_DATA} — node_modules / venv, diff-on-SessionStart, version-bump migration |
references/development-cycle/| File | When to read |
|---|---|
development-cycle/lifecycle-and-storage.md | Foundational. Cache layout (~/.claude/plugins/cache/<mkt>/<plugin>/<version>/), data dir, scope union (Managed > Local > Project > User), hot-swap matrix, orphan-marking GC, .mcp.json merging |
development-cycle/testing.md | --plugin-dir for fast iteration, headless claude -p, A/B benchmarking |
development-cycle/cli.md | Full claude plugin CLI, the /plugin 4-tab UI (Discover / Installed / Marketplaces / Errors), built-in slash commands |
development-cycle/release.md | Cutting a release — claude plugin tag, version resolution, dogfood loop |
development-cycle/troubleshooting.md | Clean-install verification + failure-mode walkthroughs |
references/topics/ — per-capabilitySix are vendored verbatim from upstream claude-plugins-official (Apache 2.0, see the plugin's README § 2 for provenance). The rest are in-house.
| Topic | Source | When |
|---|---|---|
topics/plugin-structure/ | upstream | Big-picture plugin layout and discovery |
topics/agent-development/ | upstream | Authoring agents/*.md |
topics/command-development/ | upstream | Authoring commands/*.md |
topics/hook-development/ | upstream | Hook events, JSON I/O, prompt-based hooks |
topics/mcp-integration/ | upstream | Bundling MCP servers via .mcp.json |
topics/plugin-settings/ | upstream | Legacy .claude/<name>.local.md settings |
topics/bin-development/ | in-house | Authoring bin/ — wrappers, $PATH, env vars |
topics/lsp-integration/ | in-house | lspServers (extensionToLanguage, etc.) |
topics/monitor-development/ | in-house | monitors (when: always/on-skill-invoke:<x>) |
topics/theme-and-output-style/ | in-house | themes (base + overrides) and outputStyles |
topics/channel-development/ | in-house | channels — bind MCP servers to messaging surfaces |
topics/skill/ | redirect | Stub — go to the top-level skill-creator skill instead |
For a brand-new author, fastest path to a working mental model:
topics/plugin-structure/SKILL.md — directory layout + discovery (vendored upstream content)config/manifest.md — every plugin.json fielddevelopment-cycle/lifecycle-and-storage.md — what happens at runtimenpx claudepluginhub sidhanthapoddar99/sids-plugin-marketplace --plugin ai-toolkit-devProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.