name: plugin-structure 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": "插件名称"
}

名称要求：

使用kebab-case格式（小写字母加连字符）
必须在已安装的插件中唯一
不能有空格或特殊字符
示例：code-review-assistant、test-runner、api-docs

组件路径配置

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

{
  "name": "插件名称",
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/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": {
    "server-name": {
      "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"

文件命名约定

组件文件

命令：使用kebab-case .md文件

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

代理：使用描述角色的kebab-case .md文件

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

技能：使用kebab-case目录名

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

支持文件

脚本：使用带有适当扩展名的描述性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

自动发现机制

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中的版本
优雅地弃用：在移除前明确标记旧组件
记录破坏性更改：注意影响现有用户的更改
彻底测试：验证更改后所有组件都能工作

常见模式

最小插件

没有依赖的单个命令：

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

功能齐全的插件

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

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

技能聚焦的插件

仅提供技能的插件：

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

故障排除

组件未加载：

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

路径解析错误：

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

自动发现不工作：

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

插件之间的冲突：

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

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

插件结构指南Skill plugin-structure

Claude Code插件结构

概述

目录结构

插件清单（plugin.json）

必需字段

推荐的元数据

组件路径配置

组件组织

命令

代理

技能

钩子

MCP服务器

可移植路径引用

${CLAUDE_PLUGIN_ROOT}

路径解析规则

文件命名约定

组件文件

支持文件

自动发现机制

最佳实践

组织

命名

可移植性

维护

常见模式

最小插件

功能齐全的插件

技能聚焦的插件

故障排除