Plugin Creator
Scaffold a well-formed Claude Code plugin with exactly the components the user wants -- no more, no less. A plugin is a self-contained directory with a manifest (.claude-plugin/plugin.json) plus any of: skills, agents, hooks, MCP servers, LSP servers, bin executables, output styles, default settings. This tool generates the correct structure, writes a valid manifest, adds a marketplace entry when requested, and explains how to test locally with --plugin-dir.
Core Principles
| Principle | Meaning |
|---|---|
| Manifest is optional, but recommended | If omitted, the directory name becomes the plugin name and components auto-discover at default locations. Provide one whenever metadata, versioning, or custom paths matter. |
| Default locations first | Prefer skills/, agents/, hooks/hooks.json, .mcp.json, .lsp.json at plugin root. Only override paths in plugin.json when there is a real reason. |
Components live at the root, not in .claude-plugin/ | Only plugin.json belongs inside .claude-plugin/. Everything else (skills/, agents/, etc.) is at the plugin root. This is the single most common mistake. |
Use ${CLAUDE_PLUGIN_ROOT} for every plugin-internal path | Absolute paths break when the plugin is cached. ${CLAUDE_PLUGIN_ROOT} resolves to the installed plugin directory at runtime. Use ${CLAUDE_PLUGIN_DATA} for state that must survive updates. |
| Namespacing is automatic | Plugin skills are always invoked as /plugin-name:skill-name. Names are derived from the name field in plugin.json (or directory name if no manifest). |
| Semantic versioning in one place | Set version in plugin.json OR in the marketplace entry -- not both. When present in both, plugin.json wins. |
Workflow
This skill uses guided phases -- each phase is a separate file loaded one at a time. Every phase ends with a gate where you must wait for user confirmation before proceeding. Do not skip phases or merge them.
If the user aborts at any phase, discard progress and exit without writing a partial plugin.
| Phase | File | What it covers |
|---|---|---|
| 1 | Plugin Identity | Name, description, version, author, optional metadata |
| 2 | Component Selection | Which component types to include (skills, agents, hooks, etc.) |
| 3 | Component Details | Per-component sub-questionnaires (skills, agents, hooks, MCP, LSP, bin, styles, settings) |
| 4 | Distribution | Standalone, new marketplace, or add to existing marketplace |
| 5 | Write Files | Validate, confirm, write all files to disk |
| 6 | Test Instructions | Test commands, reload, validation, next steps |
Start by loading Phase 1. After the user confirms each phase, load the next. Never load multiple phases at once. Never skip a phase.
Rules & Guardrails
- Never put components inside
.claude-plugin/. Onlyplugin.jsonlives there. - Never use absolute paths in
plugin.json, hooks, or MCP configs. All plugin-internal paths must start with./or use${CLAUDE_PLUGIN_ROOT}. - Never reference files outside the plugin directory via
../-- the plugin cache will not copy them. Symlinks are preserved, so use those if cross-plugin sharing is truly needed. - Never set
hooks,mcpServers, orpermissionModeon a plugin-shipped agent -- these are blocked for security. - Never set both
versioninplugin.jsonand in the marketplace entry. Pick one authoritative location. - Always bump the version when the plugin content changes. The Claude Code cache uses the version to decide whether to update. Forgetting this is why users do not see plugin updates.
- Reject reserved marketplace names (
claude-code-marketplace,anthropic-marketplace, etc. -- full list in references/marketplace-manifest.md). - Validate JSON before writing. A corrupt
plugin.jsonbreaks the plugin silently in some cases and loudly in others -- both waste the user's time.
Quick Reference: Minimal Plugin
The smallest valid plugin is a directory with one SKILL.md:
my-plugin/
└── skills/
└── hello/
└── SKILL.mdNo plugin.json is required -- the directory name becomes the plugin name. Add a manifest only when you need metadata, versioning, or custom paths.
Reference Files
| Reference | Contents |
|---|---|
| plugin-manifest.md | Complete plugin.json schema: required + metadata + component path fields, userConfig, channels, path behavior rules, ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} usage. |
| marketplace-manifest.md | Complete marketplace.json schema: owner, plugins array, all source types (relative, github, url, git-subdir, npm), strict mode, reserved names. |
| component-templates.md | Ready-to-use templates for plugin.json, SKILL.md, agent files, hooks/hooks.json, .mcp.json, .lsp.json, settings.json, bin/ scripts, and output styles. |
| distribution.md | Hosting options (git hosts, local, URL, npm), semantic versioning, release workflow, auto-update behavior, team marketplace configuration via extraKnownMarketplaces. |
Integration with Other Skills
| Situation | Recommended Skill |
|---|---|
| Creating the actual skill content inside a plugin | skill-creator |
| Writing the agent body for a plugin-shipped agent | Check existing agent definitions in agents/ for patterns |
| Generating rules files to pair with a plugin | agentic-rules-writer |
| Writing tickets for plugin-related backlog items | ticket-writer |