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:

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": "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": "[email protected]",
    "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
└── deploy.md        # /deploy command

File format:

---
name: command-name
description: Command description
---

Command implementation instructions...

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:

agents/
├── code-reviewer.md
├── test-generator.md

…