plugin-structure

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}

Directory Structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── hooks/
│   └── hooks.json           # Event handler configuration
└── scripts/                 # Helper scripts and utilities

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)

Located at .claude-plugin/plugin.json.

Required Fields

{
  "name": "plugin-name"
}

Name must be kebab-case, unique across installed plugins, no spaces or special characters.

Recommended Metadata

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": { "name": "Author Name" },
  "license": "MIT",
  "keywords": ["testing", "automation"]
}

Version follows semver (MAJOR.MINOR.PATCH). Keywords aid plugin discovery.