developing-claude-code-plugins

---

name: developing-claude-code-plugins description: "Build, test, and distribute Claude Code plugins with slash commands, agents, skills, hooks, MCP servers, and LSP servers. MUST be loaded when creating, reviewing, debugging, or distributing plugins. Use PROACTIVELY when user mentions plugins, extensions, marketplaces, or wants to add custom commands/agents to Claude Code."

<essential_principles>

How Claude Code Plugins Work

Plugins extend Claude Code with reusable functionality: custom slash commands, agents, skills, hooks, MCP servers, and LSP servers. Unlike standalone .claude/ configurations, plugins are namespaced, versioned, and distributable through marketplaces.

1. Plugin Structure Is Sacred

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # ONLY manifest here (required)
├── commands/                 # Slash commands (plugin root)
├── agents/                   # Subagent definitions (plugin root)
├── skills/                   # Agent Skills (plugin root)
├── hooks/
│   └── hooks.json           # Event handlers (plugin root)
├── .mcp.json                # MCP server configs (plugin root)
└── .lsp.json                # LSP server configs (plugin root)

CRITICAL: Never put commands/, agents/, skills/, or hooks/ inside .claude-plugin/. Only plugin.json goes there.

2. Namespacing Prevents Conflicts

Plugin commands use format /plugin-name:command-name. The name field in plugin.json becomes the namespace prefix. Choose names carefully - they're public-facing.

3. Use ${CLAUDE_PLUGIN_ROOT} for Paths

All paths in hooks, MCP servers, and scripts must use ${CLAUDE_PLUGIN_ROOT} to reference plugin files. Plugins are copied to a cache directory, so relative paths like ../ won't work.

4. Test with --plugin-dir During Development

claude --plugin-dir ./my-plugin

This loads your plugin without installation. Restart Claude Code after changes.

</essential_principles>

1. Create a new plugin
2. Add a component (command, agent, skill, hook, MCP, LSP)
3. Test or debug a plugin
4. Create a marketplace for distribution
5. Something else

Wait for response before proceeding.

After reading the workflow, follow it exactly.

<verification_loop>

After Every Change

1. Validate plugin structure:

claude plugin validate ./my-plugin

2. Test plugin loads:

claude --plugin-dir ./my-plugin

3. Verify components appear:

• Commands: /help shows plugin commands
• Agents: /agents lists plugin agents
• MCP: /mcp shows server status

Report to user:

• "Plugin validates: ✓"
• "Commands registered: X"
• "Ready for testing" </verification_loop>

<reference_index>

Domain Knowledge

All in references/:

Structure: plugin-structure.md Components: commands.md, agents.md, skills.md, hooks.md, mcp-lsp.md Distribution: marketplace.md Issues: troubleshooting.md </reference_index>

<workflows_index>

Workflows

All in workflows/:

Workflow	Purpose
create-plugin.md	Create new plugin from scratch
add-component.md	Add command, agent, skill, hook, MCP, or LSP
test-debug-plugin.md	Test locally and fix issues
create-marketplace.md	Create and host plugin marketplace
</workflows_index>