plugin-structure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Structure for Claude Code

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

Claude Code 插件遵循标准化的目录结构，支持组件自动发现。了解此结构有助于创建组织良好、易于维护且能与Claude Code无缝集成的插件。

核心概念：

用于自动发现的约定式目录布局
位于
```
.claude-plugin/plugin.json
```
的清单驱动配置
基于组件的组织方式（命令、Agent、Skill、钩子）
使用
```
${CLAUDE_PLUGIN_ROOT}
```
的可移植路径引用
显式加载与自动发现组件的对比

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

每个Claude Code插件都遵循以下组织模式：

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # 必填：插件清单
├── commands/                 # 斜杠命令（.md文件）
├── agents/                   # 子Agent定义（.md文件）
├── skills/                   # Agent Skill（子目录）
│   └── skill-name/
│       └── SKILL.md         # 每个Skill必填
├── hooks/
│   └── hooks.json           # 事件处理器配置
├── .mcp.json                # MCP服务器定义
└── scripts/                 # 辅助脚本和工具

关键规则：

清单位置：
```
plugin.json
```
清单必须位于
```
.claude-plugin/
```
目录中
组件位置：所有组件目录（commands、agents、skills、hooks）必须位于插件根目录，不能嵌套在
```
.claude-plugin/
```
内
可选组件：仅为插件实际使用的组件创建目录
命名规范：所有目录和文件名使用kebab-case格式

Plugin Manifest (plugin.json)

插件清单（plugin.json）

The manifest defines plugin metadata and configuration. Located at

.claude-plugin/plugin.json

清单定义插件的元数据和配置，位于

.claude-plugin/plugin.json

：

Required Fields

必填字段

json

{
  "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

json

{
  "name": "plugin-name"
}

名称要求：

使用kebab-case格式（小写加连字符）
在已安装的插件中必须唯一
不能包含空格或特殊字符

示例：

code-review-assistant

、

test-runner

、

api-docs

Recommended Metadata

Component Path Configuration

组件路径配置

Specify custom paths for components (supplements default directories):

json

{
  "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

指定组件的自定义路径（补充默认目录）：

json

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

重要提示：自定义路径是对默认目录的补充，而非替代。默认目录和自定义路径中的组件都会被加载。

路径规则：

必须相对于插件根目录
必须以
```
./
```
开头
不能使用绝对路径
支持数组指定多个位置

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:

markdown

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

Command implementation instructions...

Usage: Commands integrate as native slash commands in Claude Code

位置：

commands/

目录格式：带YAML前置元数据的Markdown文件 自动发现：

commands/

中的所有

.md

文件会自动加载

示例结构：

commands/
├── review.md        # /review命令
├── test.md          # /test命令
└── deploy.md        # /deploy命令

文件格式：

markdown

---
name: command-name
description: 命令描述
---

命令实现说明...

用途：命令作为原生斜杠命令集成到Claude Code中

Agents

Agent

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:

markdown

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

位置：

agents/

目录格式：带YAML前置元数据的Markdown文件 自动发现：

agents/

中的所有

.md

文件会自动加载

示例结构：

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

文件格式：

markdown

---
description: Agent的角色和专长
capabilities:
  - 特定任务1
  - 特定任务2
---

详细的Agent说明和知识...

用途：用户可以手动调用Agent，或由Claude Code根据任务上下文自动选择

Skills

Skill

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:

markdown

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

位置：

skills/

目录，每个Skill对应一个子目录格式：每个Skill在独立目录中包含

SKILL.md

文件 自动发现：Skill子目录中的所有

SKILL.md

文件会自动加载

示例结构：

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

SKILL.md格式：

markdown

---
name: Skill名称
description: 何时使用此Skill
version: 1.0.0
---

Skill说明和指导...

支持文件：Skill可以在子目录中包含脚本、参考资料、示例或资源

用途：Claude Code会根据与描述匹配的任务上下文自动激活Skill

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:

json

{
  "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

位置：

hooks/hooks.json

或内联在

plugin.json

中格式：定义事件处理器的JSON配置注册：插件启用时钩子会自动注册

示例结构：

hooks/
├── hooks.json           # 钩子配置
└── scripts/
    ├── validate.sh      # 钩子脚本
    └── check-style.sh   # 钩子脚本

配置格式：

json

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

可用事件：PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification

用途：钩子会响应Claude Code事件自动执行

MCP Servers

MCP服务器

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:

json

{
  "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

位置：插件根目录的

.mcp.json

或内联在

plugin.json

中格式：MCP服务器定义的JSON配置 自动启动：插件启用时服务器会自动启动

示例格式：

json

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

用途：MCP服务器与Claude Code的工具系统无缝集成

Portable Path References

可移植路径引用

${CLAUDE_PLUGIN_ROOT}

Use

${CLAUDE_PLUGIN_ROOT}

environment variable for all intra-plugin path references:

json

{
  "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/...
```
)

所有插件内部路径引用使用

${CLAUDE_PLUGIN_ROOT}

环境变量：

json

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

重要性：插件的安装位置因以下因素而异：

用户安装方式（市场、本地、npm）
操作系统约定
用户偏好

使用场景：

钩子命令路径
MCP服务器命令参数
脚本执行引用
资源文件路径

禁止使用：

硬编码绝对路径（
```
/Users/name/plugins/...
```
）
相对于工作目录的路径（命令中的
```
./scripts/...
```
）
主目录快捷方式（
```
~/plugins/...
```
）

Path Resolution Rules

路径解析规则

In manifest JSON fields (hooks, MCP servers):

json

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

In component files (commands, agents, skills):

markdown

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

In executed scripts:

bash

#!/bin/bash

在清单JSON字段中（钩子、MCP服务器）：

json

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

在组件文件中（命令、Agent、Skill）：

markdown

参考脚本位置：${CLAUDE_PLUGIN_ROOT}/scripts/helper.py

在执行的脚本中：

bash

#!/bin/bash

${CLAUDE_PLUGIN_ROOT} available as environment variable

${CLAUDE_PLUGIN_ROOT}作为环境变量可用

source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

undefined

source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

undefined

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/
```

命令：使用kebab-case格式的

.md

文件

```
code-review.md
```
→
```
/code-review
```
命令
```
run-tests.md
```
→
```
/run-tests
```
命令
```
api-docs.md
```
→
```
/api-docs
```
命令

Agent：使用描述角色的kebab-case格式

.md

文件

```
test-generator.md
```
```
code-reviewer.md
```
```
performance-analyzer.md
```

Skill：使用kebab-case格式的目录名

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

脚本：使用描述性kebab-case名称和适当的扩展名

```
validate-input.sh
```
```
generate-report.py
```
```
process-data.js
```

文档：使用kebab-case格式的Markdown文件

```
api-reference.md
```
```
migration-guide.md
```
```
best-practices.md
```

配置：使用标准名称

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

Claude Code会自动发现并加载组件：

插件清单：插件启用时读取
```
.claude-plugin/plugin.json
```
命令：扫描
```
commands/
```
目录中的
```
.md
```
文件
Agent：扫描
```
agents/
```
目录中的
```
.md
```
文件
Skill：扫描
```
skills/
```
目录中包含
```
SKILL.md
```
的子目录
钩子：从
```
hooks/hooks.json
```
或清单加载配置
MCP服务器：从
```
.mcp.json
```
或清单加载配置

发现时机：

插件安装：组件向Claude Code注册
插件启用：组件变为可用状态
无需重启：更改在下次Claude Code会话中生效

覆盖行为：

plugin.json

中的自定义路径是对默认目录的补充（而非替代）

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

逻辑分组：将相关组件分组
- 把测试相关的命令、Agent和Skill放在一起
- 在
```
scripts/
```
  中为不同用途创建子目录
精简清单：保持
```
plugin.json
```
简洁
- 仅在必要时指定自定义路径
- 对于标准布局依赖自动发现
- 仅在简单情况下使用内联配置
文档：包含README文件
- 插件根目录：整体用途和使用方法
- 组件目录：特定指导
- 脚本目录：使用方法和要求

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

一致性：组件使用一致的命名
- 如果命令是
```
test-runner
```
  ，相关Agent命名为
```
test-runner-agent
```
- Skill目录名与其用途匹配
清晰性：使用能表明用途的描述性名称
- 推荐：
```
api-integration-testing/
```
  、
```
code-quality-checker.md
```
- 避免：
```
utils/
```
  、
```
misc.md
```
  、
```
temp.sh
```
长度：在简洁性和清晰性之间取得平衡
- 命令：2-3个词（
```
review-pr
```
  、
```
run-ci
```
  ）
- Agent：清晰描述角色（
```
code-reviewer
```
  、
```
test-generator
```
  ）
- Skill：聚焦主题（
```
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

始终使用${CLAUDE_PLUGIN_ROOT}：绝不硬编码路径
多系统测试：在macOS、Linux、Windows上验证
文档依赖：列出所需工具和版本
避免系统特定功能：使用可移植的bash/Python结构

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

版本一致性：发布时更新plugin.json中的版本
优雅弃用：在移除旧组件前清晰标记
文档破坏性变更：记录影响现有用户的变更
彻底测试：变更后验证所有组件正常工作

Common Patterns

常见模式

Minimal Plugin

最小化插件

Single command with no dependencies:

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

无依赖的单个命令：

my-plugin/
├── .claude-plugin/
│   └── plugin.json    # 仅包含名称字段
└── commands/
    └── hello.md       # 单个命令

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

包含所有组件类型的完整插件：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # 用户面向的命令
├── agents/            # 专业化子Agent
├── skills/            # 自动激活的Skill
├── hooks/             # 事件处理器
│   ├── hooks.json
│   └── scripts/
├── .mcp.json          # 外部集成
└── scripts/           # 共享工具

Skill-Focused Plugin

聚焦Skill的插件

Plugin providing only skills:

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

仅提供Skill的插件：

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.

组件未加载：

验证文件位于正确目录且扩展名正确
检查YAML前置元数据语法（命令、Agent、Skill）
确保Skill包含
```
SKILL.md
```
（而非
```
README.md
```
或其他名称）
确认插件在Claude Code设置中已启用

路径解析错误：

用
```
${CLAUDE_PLUGIN_ROOT}
```
替换所有硬编码路径
验证清单中的路径是相对路径且以
```
./
```
开头
检查引用的文件是否存在于指定路径
在钩子脚本中用
```
echo $CLAUDE_PLUGIN_ROOT
```
测试

自动发现不工作：

确认目录位于插件根目录（而非
```
.claude-plugin/
```
内）
检查文件命名是否遵循规范（kebab-case、正确扩展名）
验证清单中的自定义路径是否正确
重启Claude Code以重新加载插件配置

插件间冲突：

使用唯一、描述性的组件名称
必要时用插件名称作为命令命名空间
在插件README中记录潜在冲突
考虑为相关功能使用命令前缀

有关详细示例和高级模式，请参阅

references/

和

examples/

目录中的文件。

plugin-structure

Original

Translation

Plugin Structure for Claude Code

Claude Code 插件结构

Overview

概述

Directory Structure

目录结构

Plugin Manifest (plugin.json)

插件清单（plugin.json）

Required Fields

必填字段

Recommended Metadata

推荐元数据

Component Path Configuration

组件路径配置

Component Organization

组件组织

Commands

命令

Agents

Agent

Skills

Skill

Hooks

钩子

MCP Servers

MCP服务器

Portable Path References

可移植路径引用

${CLAUDE_PLUGIN_ROOT}

${CLAUDE_PLUGIN_ROOT}

Path Resolution Rules

路径解析规则

${CLAUDE_PLUGIN_ROOT} available as environment variable

${CLAUDE_PLUGIN_ROOT}作为环境变量可用

File Naming Conventions

文件命名规范

Component Files

组件文件

Supporting Files

支持文件

Auto-Discovery Mechanism

自动发现机制

Best Practices

最佳实践

Organization

组织

Naming

命名

Portability

可移植性

Maintenance

维护

Common Patterns

常见模式

Minimal Plugin

最小化插件

Full-Featured Plugin

全功能插件

Skill-Focused Plugin

聚焦Skill的插件

Troubleshooting

故障排除