Plugin Architecture Guide
Provides standardized patterns and directory layouts for building modular and portable Claude Code plugins.
The source repository doesn't declare a license. Check its terms before reusing the code.
Key features
- Automated component discovery for commands, agents, and skills
- Manifest-driven configuration using the plugin.json specification
- Event-driven hook registration for terminal lifecycle management
- Portable path resolution using the ${CLAUDE_PLUGIN_ROOT} variable
- Standardized kebab-case naming conventions for file organization
Use cases
- Scaffolding a new Claude Code plugin from scratch with the correct directory tree
- Organizing complex agentic workflows into modular commands and skills
- Configuring MCP servers and hooks for deep integration with terminal events
FAQ
Where must the Claude Code plugin manifest be located?
The plugin manifest file must be named plugin.json and must be located inside a directory named .claude-plugin at the root of your plugin.
How does Claude Code handle component discovery?
Claude Code automatically scans specific root-level directories: commands/ for slash commands, agents/ for subagents, skills/ for specialized capabilities, and hooks/ for event handlers.
Why should I use ${CLAUDE_PLUGIN_ROOT} instead of relative paths?
Using the ${CLAUDE_PLUGIN_ROOT} environment variable ensures your plugin is portable and works correctly regardless of where the user installs it or which operating system they use.
Can I use custom directory names for my plugin components?
Yes, while Claude Code has default directories, you can define custom paths for commands, agents, hooks, and MCP servers within the plugin.json manifest.
Related skills
Plugin Skill Development
Provides standardized workflows and best practices for building, organizing, and optimizing specialized skills within Claude Code plugins.
Developer Tools142,11812 ptsPrompt Engineering
Creates, improves, and optimizes prompts for Claude using Anthropic's best practices for clarity, structure, and security.
Developer Tools5412 ptsPlugin Structure
Guides the creation and organization of Claude Code plugins following standard directory layouts, manifest configuration, and component best practices.
Developer Tools22912 pts