name: 插件结构 description: 当用户询问“创建插件”、“搭建插件”、“理解插件结构”、“组织插件组件”、“设置plugin.json”、“使用${CLAUDE_PLUGIN_ROOT}”、“添加命令/代理/技能/钩子”、“配置自动发现”，或需要关于插件目录布局、清单配置、组件组织、文件命名约定、或Claude Code插件架构最佳实践的指导时，应使用此技能。 version: 0.1.0

Claude Code插件结构

概述

Claude Code插件遵循标准化目录结构，具有自动组件发现。理解此结构可以创建组织良好、可维护的插件，与Claude Code无缝集成。

关键概念：

用于自动发现的常规目录布局
在.claude-plugin/plugin.json中的清单驱动配置
基于组件的组织（命令、代理、技能、钩子）
使用${CLAUDE_PLUGIN_ROOT}的可移植路径引用
显式与自动发现的组件加载

目录结构

每个Claude Code插件遵循此组织模式：

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

关键规则：

清单位置：plugin.json清单必须在.claude-plugin/目录中
组件位置：所有组件目录（commands、agents、skills、hooks）必须在插件根级别，而不是嵌套在.claude-plugin/内
可选组件：仅创建插件实际使用的组件目录
命名约定：对所有目录和文件名使用短横线命名法（kebab-case）

插件清单（plugin.json）

清单定义插件元数据和配置。位于.claude-plugin/plugin.json：

必需字段

{
  "name": "插件名称"
}

名称要求：

使用短横线命名法格式（小写字母加连字符）
必须在安装的插件中唯一
无空格或特殊字符
示例：code-review-assistant、test-runner、api-docs

组件路径配置

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

{
  "name": "插件名称",
  "commands": "./自定义命令",
  "agents": ["./代理", "./专用代理"],
  "hooks": "./配置/hooks.json",
  "mcpServers": "./.mcp.json"
}

重要：自定义路径补充默认值—它们不替换默认值。默认目录和自定义路径中的组件都将加载。

路径规则：

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

组件组织

命令

位置：commands/目录格式：带YAML前置元的Markdown文件 自动发现：commands/中所有.md文件自动加载

示例结构：

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

文件格式：

---
name: 命令名称
description: 命令描述
---

命令实现指令...

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

代理

位置：agents/目录格式：带YAML前置元的Markdown文件 自动发现：agents/中所有.md文件自动加载

示例结构：

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

文件格式：

---
description: 代理角色和专业领域
capabilities:
  - 具体任务1
  - 具体任务2
---

详细代理指令和知识...

使用：用户可以手动调用代理，或Claude Code基于任务上下文自动选择

技能

位置：skills/目录，每个技能有子目录格式：每个技能在自己的目录中有SKILL.md文件 自动发现：技能子目录中所有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格式：

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

技能指令和指导...

支持文件：技能可以包括脚本、参考、示例或子目录中的资产

使用：Claude Code基于任务上下文匹配描述自动激活技能

钩子

位置：hooks/hooks.json或内联在plugin.json中格式：定义事件处理器的JSON配置注册：插件启用时钩子自动注册

示例结构：

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

配置格式：

{
  "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服务器

位置：插件根目录的.mcp.json或内联在plugin.json中格式：MCP服务器定义的JSON配置 自动启动：插件启用时服务器自动启动

示例格式：

{
  "mcpServers": {
    "服务器名称": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

使用：MCP服务器无缝集成到Claude Code的工具系统中

可移植路径引用

${CLAUDE_PLUGIN_ROOT}

对所有插件内路径引用使用${CLAUDE_PLUGIN_ROOT}环境变量：

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

为什么重要：插件根据以下因素安装在不同位置：

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

在哪里使用：

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

切勿使用：

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

路径解析规则

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

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

在组件文件中（命令、代理、技能）：

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

在执行的脚本中：

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} 作为环境变量可用
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

文件命名约定

组件文件

命令：使用短横线命名法.md文件

code-review.md → /code-review
run-tests.md → /run-tests
api-docs.md → /api-docs

代理：使用短横线命名法.md文件描述角色

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

技能：使用短横线命名法目录名称

api-testing/
database-migrations/
error-handling/

支持文件

脚本：使用描述性短横线命名法名称，带适当扩展名

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

文档：使用短横线命名法Markdown文件

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

配置：使用标准名称

hooks.json
.mcp.json
plugin.json

自动发现机制

Claude Code自动发现和加载组件：

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

发现时机：

插件安装：组件注册到Claude Code
插件启用：组件可用
无需重启：更改在下个Claude Code会话生效

覆盖行为：plugin.json中的自定义路径补充（不替换）默认目录

最佳实践

组织

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

命名

一致性：跨组件使用一致的命名
- 如果命令是test-runner，命名相关代理test-runner-agent
- 匹配技能目录名称到其目的
清晰性：使用指示目的的描述性名称
- 好：api-integration-testing/、code-quality-checker.md
- 避免：utils/、misc.md、temp.sh
长度：平衡简洁与清晰
- 命令：2-3个词（review-pr、run-ci）
- 代理：清晰描述角色（code-reviewer、test-generator）
- 技能：主题聚焦（error-handling、api-design）

可移植性

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

维护

一致版本控制：为发布更新plugin.json中的版本
优雅弃用：在移除前明确标记旧组件
记录破坏性更改：注意影响现有用户的更改
彻底测试：验证更改后所有组件工作

常见模式

最小插件

单一命令，无依赖：

我的插件/
├── .claude-plugin/
│   └── plugin.json    # 仅名称字段
└── commands/
    └── hello.md       # 单一命令

全功能插件

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

我的插件/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # 面向用户的命令
├── agents/            # 专用子代理
├── skills/            # 自动激活技能
├── hooks/             # 事件处理器
│   ├── hooks.json
│   └── scripts/
├── .mcp.json          # 外部集成
└── scripts/           # 共享实用工具

技能聚焦插件

仅提供技能的插件：

我的插件/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── 技能一/
    │   └── SKILL.md
    └── 技能二/
        └── SKILL.md

故障排除

组件未加载：

验证文件在正确目录中，有正确扩展名
检查YAML前置元语法（命令、代理、技能）
确保技能有SKILL.md（不是README.md或其他名称）
确认插件在Claude Code设置中启用

路径解析错误：

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

自动发现不工作：

确认目录在插件根目录（不在.claude-plugin/内）
检查文件命名遵循约定（短横线命名法、正确扩展名）
验证清单中的自定义路径正确
重启Claude Code以重新加载插件配置

插件间冲突：

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

有关详细示例和高级模式，请参阅references/和examples/目录中的文件。

ClaudeCode插件结构构建技能Skill PluginStructure