This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin director

Plugin Structure for Claude Code Overview Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well organized, maintainable plugins that integrate seamlessly with Claude Code. Key concepts: Conventional directory layout for automatic discovery Manifest driven configuration in .claude plugin/plugin.json Component based organization (commands, agents, skills, hooks) Portable path references using ${CLAUDE PLUGIN ROOT} Explicit vs. auto discovered component loading Directory Structure Every Claude Code plugin follows this organizational pattern: Critical rules: 1. Manifest location : The plugin.json manifest MUST be in .claude plugin/ directory 2. Component locations : All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside .claude plugin/ 3. Optional components : Only create directories for components the plugin actually uses 4. Naming convention : Use kebab case for all directory and file names Plugin Manifest (plugin.json) The manifest defines plugin metadata and configuration. Located at .claude plugin/plugin.json : Required Fields Name requirements: Use kebab case format (lowercase with hyphens) Must be unique across installed plugins No spaces or special characters Example: code review assistant , test runner , api docs Recommended Metadata Version format : Follow semantic versioning (MAJOR.MINOR.PATCH) Keywords : Use for plugin discovery and categorization Component Path Configuration Specify custom paths for components (supplements default directories): Important : Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load. Path rules: Must be relative to plugin root Must start with ./ Cannot use absolute paths Support arrays for multiple locations Component Organization Commands Location : commands/ directory Format : Markdown files with YAML frontmatter Auto discovery : All .md files in commands/ load automatically Example structure : File format : Usage : Commands integrate as native slash commands in Claude Code Agents Location : agents/ directory Format : Markdown files with YAML frontmatter Auto discovery : All .md files in agents/ load automatically Example structure : File format : Usage : Users can invoke agents manually, or Claude Code selects them automatically based on task context Skills Location : skills/ directory with subdirectories per skill Format : Each skill in its own directory with SKILL.md file Auto discovery : All SKILL.md files in skill subdirectories load automatically Example structure : SKILL.md format : Supporting files : Skills can include scripts, references, examples, or assets in subdirectories Usage : Claude Code autonomously activates skills based on task context matching the description Hooks Location : hooks/hooks.json or inline in plugin.json Format : JSON configuration defining event handlers Registration : Hooks register automatically when plugin enables Example structure : Configuration format : Available events : PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification Usage : Hooks execute automatically in response to Claude Code events MCP Servers Location : .mcp.json at plugin root or inline in plugin.json Format : JSON configuration for MCP server definitions Auto start : Servers start automatically when plugin enables Example format : Usage : MCP servers integrate seamlessly with Claude Code's tool system Portable Path References ${CLAUDE PLUGIN ROOT} Use ${CLAUDE PLUGIN ROOT} environment variable for all intra plugin path references: Why it matters : Plugins install in different locations depending on: User installation method (marketplace, local, npm) Operating system conventions User preferences Where to use it : Hook command paths MCP server command arguments Script execution references Resource file paths Never use : Hardcoded absolute paths ( /Users/name/plugins/... ) Relative paths from working directory ( ./scripts/... in commands) Home directory shortcuts ( ~/plugins/... ) Path Resolution Rules In manifest JSON fields (hooks, MCP servers): In component files (commands, agents, skills): In executed scripts : File Naming Conventions Component Files Commands : Use kebab case .md files code review.md → /code review run tests.md → /run tests api docs.md → /api docs Agents : Use kebab case .md files describing role test generator.md code reviewer.md performance analyzer.md Skills : Use kebab case directory names api testing/ database migrations/ error handling/ Supporting Files Scripts : Use descriptive kebab case names with appropriate extensions validate input.sh generate report.py process data.js Documentation : Use kebab case markdown files api reference.md migration guide.md best practices.md Configuration : Use standard names hooks.json .mcp.json plugin.json Auto Discovery Mechanism Claude Code automatically discovers and loads components: 1. Plugin manifest : Reads .claude plugin/plugin.json when plugin enables 2. Commands : Scans commands/ directory for .md files 3. Agents : Scans agents/ directory for .md files 4. Skills : Scans skills/ for subdirectories containing SKILL.md 5. Hooks : Loads configuration from hooks/hooks.json or manifest 6. MCP servers : Loads configuration from .mcp.json or manifest Discovery timing : Plugin installation: Components register with Claude Code Plugin enable: Components become available for use No restart required: Changes take effect on next Claude Code session Override behavior : Custom paths in plugin.json supplement (not replace) default directories Best Practices Organization 1. Logical grouping : Group related components together Put test related commands, agents, and skills together Create subdirectories in scripts/ for different purposes 2. Minimal manifest : Keep plugin.json lean Only specify custom paths when necessary Rely on auto discovery for standard layouts Use inline configuration only for simple cases 3. Documentation : Include README files Plugin root: Overall purpose and usage Component directories: Specific guidance Script directories: Usage and requirements Naming 1. Consistency : Use consistent naming across components If command is test runner , name related agent test runner agent Match skill directory names to their purpose 2. Clarity : Use descriptive names that indicate purpose Good: api integration testing/ , code quality checker.md Avoid: utils/ , misc.md , temp.sh 3. Length : Balance brevity with clarity Commands: 2 3 words ( review pr , run ci ) Agents: Describe role clearly ( code reviewer , test generator ) Skills: Topic focused ( error handling , api design ) Portability 1. Always use ${CLAUDE PLUGIN ROOT} : Never hardcode paths 2. Test on multiple systems : Verify on macOS, Linux, Windows 3. Document dependencies : List required tools and versions 4. Avoid system specific features : Use portable bash/Python constructs Maintenance 1. Version consistently : Update version in plugin.json for releases 2. Deprecate gracefully : Mark old components clearly before removal 3. Document breaking changes : Note changes affecting existing users 4. Test thoroughly : Verify all components work after changes Common Patterns Minimal Plugin Single command with no dependencies: Full Featured Plugin Complete plugin with all component types: Skill Focused Plugin Plugin providing only skills: Troubleshooting Component not loading : Verify file is in correct directory with correct extension Check YAML frontmatter syntax (commands, agents, skills) Ensure skill has SKILL.md (not README.md or other name) Confirm plugin is enabled in Claude Code settings Path resolution errors : Replace all hardcoded paths with ${CLAUDE PLUGIN ROOT} Verify paths are relative and start with ./ in manifest Check that referenced files exist at specified paths Test with echo $CLAUDE PLUGIN ROOT in hook scripts Auto discovery not working : Confirm directories are at plugin root (not in .claude plugin/ ) Check file naming follows conventions (kebab case, correct extensions) Verify custom paths in manifest are correct Restart Claude Code to reload plugin configuration Conflicts between plugins : Use unique, descriptive component names Namespace commands with plugin name if needed Document potential conflicts in plugin README Consider command prefixes for related functionality For detailed examples and advanced patterns, see files in references/ and examples/ directories.

plugin-structure