---
id: sm-plugin-structure
name: "plugin-structure"
url: https://skills.yangsir.net/skill/sm-plugin-structure
author: anthropics
domain: ai-software-architecture-engineering
tags: ["plugin-architecture", "extensibility", "api-design", "modularity", "ai-frameworks"]
install_count: 404
rating: 4.20 (20 reviews)
github: https://github.com/anthropics/claude-code
---

# plugin-structure

> 专注于AI工程插件结构设计，利用Claude Code等代理式编码工具，在终端环境中构建可扩展插件。

**Stats**: 404 installs · 4.2/5 (20 reviews)

## Before / After 对比

### 优化插件结构，提升Claude Code理解力

## Readme

# 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}`

- 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
└── 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:

- **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables

- **Commands**: Scans `commands/` directory for `.md` files

- **Agents**: Scans `agents/` directory for `.md` files

- **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`

- **Hooks**: Loads configuration from `hooks/hooks.json` or manifest

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

- 

**Logical grouping**: Group related components together

Put test-related commands, agents, and skills together

- Create subdirectories in `scripts/` for different purposes

- 

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

- 

**Documentation**: Include README files

Plugin root: Overall purpose and usage

- Component directories: Specific guidance

- Script directories: Usage and requirements

### Naming

- 

**Consistency**: Use consistent naming across components

If command is `test-runner`, name related agent `test-runner-agent`

- Match skill directory names to their purpose

- 

**Clarity**: Use descriptive names that indicate purpose

Good: `api-integration-testing/`, `code-quality-checker.md`

- Avoid: `utils/`, `misc.md`, `temp.sh`

- 

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

- **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths

- **Test on multiple systems**: Verify on macOS, Linux, Windows

- **Document dependencies**: List required tools and versions

- **Avoid system-specific features**: Use portable bash/Python constructs

### Maintenance

- **Version consistently**: Update version in plugin.json for releases

- **Deprecate gracefully**: Mark old components clearly before removal

- **Document breaking changes**: Note changes affecting existing users

- **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.
Weekly Installs0Repository[anthropics/claude-code](https://github.com/anthropics/claude-code)GitHub Stars79.3KFirst SeenJan 1, 1970Security Audits[Gen Agent Trust HubPass](/anthropics/claude-code/plugin-structure/security/agent-trust-hub)[SocketPass](/anthropics/claude-code/plugin-structure/security/socket)[SnykPass](/anthropics/claude-code/plugin-structure/security/snyk)

---
*Source: https://skills.yangsir.net/skill/sm-plugin-structure*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-plugin-structure/markdown*