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:

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
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

**Critical rules:**

**Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory
**Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`
**Optional components**: Only create directories for components the plugin actually uses
**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": "plugin-name"
}

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

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin-name",
  "license": "MIT",
  "keywords": ["testing", "automation", "ci-cd"]
}

**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):

{
  "name": "plugin-name",
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

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

commands/
├── review.md        # /review command
├── test.md          # /test command
└── deplo

<!-- truncated -->

Plugin Structure for Claude Code

Page Outline

Source Content