<essential_principles> 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

code

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

bash

claude --plugin-dir ./my-plugin

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

</essential_principles>

<intake> **What would you like to do?**

•Create a new plugin
•Add a component (command, agent, skill, hook, MCP, LSP)
•Test or debug a plugin
•Create a marketplace for distribution
•Something else

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "new", "create", "build", "start", "plugin" | `workflows/create-plugin.md` | | 2, "add", "component", "command", "agent", "skill", "hook", "mcp", "lsp" | `workflows/add-component.md` | | 3, "test", "debug", "fix", "error", "not working", "broken" | `workflows/test-debug-plugin.md` | | 4, "marketplace", "distribute", "share", "publish" | `workflows/create-marketplace.md` | | 5, other | Clarify intent, then route to appropriate workflow |

After reading the workflow, follow it exactly. </routing>

<verification_loop> After Every Change:

•Validate plugin structure:

bash

claude plugin validate ./my-plugin

•Test plugin loads:

bash

claude --plugin-dir ./my-plugin

•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> 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> 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>

<success_criteria> A well-built plugin:

•Has valid plugin.json manifest in .claude-plugin/
•Components are in correct directories (commands/, agents/, skills/, hooks/)
•All paths use ${CLAUDE_PLUGIN_ROOT} variable
•Passes claude plugin validate
•Loads correctly with --plugin-dir
•Commands appear in /help output </success_criteria>