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": "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
└── 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
└── refactorer.md

File format:

---
description: Agent role and expertise
capabilities:
  - Specific task 1
  - Specific task 2
---

Detailed agent instructions and knowledge...

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:

skills/
├── api-testing/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── test-runner.py
│   └── references/
│       └── api-spec.md
└── database-migrations/
    ├── SKILL.md
    └── examples/
        └── migration-template.sql

SKILL.md format:

---
name: Skill Name
description: When to use this skill
version: 1.0.0
---

Skill instructions and guidance...

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:

hooks/
├── hooks.json           # Hook configuration
└── scripts/
    ├── validate.sh      # Hook script
    └── check-style.sh   # Hook script

Configuration format:

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
      "timeout": 30
    }]
  }]
}

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:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

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:

{
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}

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

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"

In component files (commands, agents, skills):

Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py

In executed scripts:

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

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:

my-plugin/
├── .claude-plugin/
│   └── plugin.json    # Just name field
└── commands/
    └── hello.md       # Single command

Full-Featured Plugin

Complete plugin with all component types:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # User-facing commands
├── agents/            # Specialized subagents
├── skills/            # Auto-activating skills
├── hooks/             # Event handlers
│   ├── hooks.json
│   └── scripts/
├── .mcp.json          # External integrations
└── scripts/           # Shared utilities

Skill-Focused Plugin

Plugin providing only skills:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

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.