developing-claude-code-pluginsSafety --Repository ShareFavorite skill

<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

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> 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/:

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