Plugin scaffolder

A Claude Code plugin is mostly layout discipline: the manifest goes in .claude-plugin/, every component directory goes at the plugin root, paths must use ${CLAUDE_PLUGIN_ROOT} to survive installation, and the marketplace entry has its own schema. This skill encodes that discipline — describe the plugin (or point at the .claude/ setup you want to package) and get a valid, testable scaffold.

When to use this skill

• You're starting a plugin and want the structure, manifest, and one working example of each component generated correctly the first time.
• You have customizations scattered across .claude/agents/, .claude/skills/, hooks, and an .mcp.json, and want them migrated into one installable package.
• You're setting up a team or personal marketplace repo and need the marketplace.json wired so /plugin install works.

When NOT to use this skill

• You're sharing a single procedure — one skill file needs no plugin around it.
• The customization is for exactly one repo and travels with it — checked-in .claude/ files already do that; packaging adds versioning overhead you don't need yet. See the plugins guide for the dividing line.

Instructions

1. Inventory what the plugin carries. From the description (or by reading the existing .claude/ directory), list the components: skills, agents, commands, hooks, MCP servers, LSP config. Confirm the plugin's name (kebab-case, unique — it becomes the namespace prefix users type, e.g. /my-plugin:release-notes).
2. Scaffold the layout exactly. Create .claude-plugin/plugin.json — only the manifest lives in that folder — and component directories at the plugin root: skills/<name>/SKILL.md, agents/*.md, commands/*.md, hooks/hooks.json, .mcp.json. Manifest gets name (required), plus version, description, author, and repository so marketplaces render it properly.
3. Write working samples, not lorem ipsum. Each requested component gets a minimal but real implementation derived from the user's description — a skill with actual instructions, a hook with a functioning script. Migrating existing files? Copy them in, then fix what packaging breaks (next step).
4. Make paths portable. Anything referencing files inside the plugin uses ${CLAUDE_PLUGIN_ROOT} (the install location changes and moves on update); anything writing caches or generated state uses ${CLAUDE_PLUGIN_DATA} (survives updates); anything touching the user's project uses ${CLAUDE_PROJECT_DIR}. Hardcoded relative paths are the #1 way plugins break after install.
5. Test, then validate. Run the local loop: claude --plugin-dir ./<plugin> to load it for a session, exercise each component (the namespaced command, the hook trigger, the MCP connection), iterate with /reload-plugins. Finish with claude plugin validate ./<plugin> --strict and fix every warning.
6. Wire distribution. Generate or update the marketplace.json (in this repo or the user's marketplace repo) with the plugin's entry and source. State the consumer install path explicitly: /plugin marketplace add <owner>/<repo> then /plugin install <name>@<marketplace> — and for teams, note the project-scope install that gives every clone the plugin after a trust prompt.

[!WARNING] A plugin executes on other people's machines: its hooks run shell commands and its MCP servers receive credentials. Don't bundle secrets (use env expansion), pin any third-party servers it pulls in, and keep the manifest's repository honest so consumers can read the source they're trusting.

[!TIP] Keep version discipline from day one — bump version on every behavioral change. Marketplaces surface it, and "which version are you on?" is the first debugging question you'll ask a teammate.

Output

A complete plugin directory that passes claude plugin validate --strict: manifest, all requested components implemented, portable path variables throughout, plus the marketplace.json entry and a short INSTALL note covering the marketplace-add, install, and local --plugin-dir test commands.