plugin-structure

Claude Code 插件结构

概述

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

关键概念：

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

目录结构

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

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

重要规则：

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

插件清单（plugin.json）

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

必填字段

{
  "name": "plugin-name"
}

名称要求：

• 使用 kebab-case 格式（小写字母，以连字符分隔）
• 在已安装的插件中必须唯一
• 不得包含空格或特殊字符
• 示例：code-review-assistant、test-runner、api-docs

推荐元数据

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin-name",
  "license": "MIT",
  "keywords": ["testing", "automation", "ci-cd"]
}

版本格式：遵循语义化版本规范（MAJOR.MINOR.PATCH） 关键词：用于插件发现和分类

组件路径配置

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

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

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

路径规则：

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

组件组织

命令

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

结构示例：

commands/
├── review.md        # /review command
├── test.md          # /test command
└── deploy.md        # /deploy command

文件格式：

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

Command implementation instructions...

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

Agent

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

结构示例：

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

文件格式：

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

Detailed agent instructions and knowledge...

用法：用户可以手动调用 Agent，也可以由 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: Skill Name
description: When to use this skill
version: 1.0.0
---

Skill instructions and guidance...

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

用法：Claude Code 会根据任务上下文与描述的匹配情况自主启用技能

钩子

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

结构示例：

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

配置格式：

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

重要原因：插件的安装位置各不相同，取决于：

• 用户的安装方式（marketplace、本地、npm）
• 操作系统惯例
• 用户偏好

使用位置：

• Hook 命令路径
• MCP 服务命令参数
• 脚本执行引用
• 资源文件路径

切勿使用：

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

路径解析规则

在清单 JSON 字段中（hooks、MCP 服务）：

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

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

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

在执行的脚本中：

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
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

Agent：使用描述角色的 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 会自动发现并加载组件：

1. 插件清单：插件启用时读取 .claude-plugin/plugin.json
2. 命令：扫描 commands/ 目录中的 .md 文件
3. Agent：扫描 agents/ 目录中的 .md 文件
4. 技能：扫描 skills/ 中包含 SKILL.md 的子目录
5. Hooks：从 hooks/hooks.json 或清单加载配置
6. MCP 服务：从 .mcp.json 或清单加载配置

发现时机：

• 插件安装：组件向 Claude Code 注册
• 插件启用：组件可供使用
• 无需重启：更改会在下次 Claude Code 会话时生效

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

最佳实践

组织结构

1. 逻辑分组：将相关组件放在一起

   • 将与测试相关的命令、Agent 和技能放在一起
   • 在 scripts/ 中为不同用途创建子目录

2. 精简清单：保持 plugin.json 简洁

   • 仅在必要时指定自定义路径
   • 标准布局依赖自动发现
   • 仅在简单场景中使用内联配置

3. 文档：包含 README 文件

   • 插件根目录：整体用途和用法
   • 组件目录：具体指南
   • 脚本目录：用法和要求

命名

1. 一致性：在各组件中采用一致的命名

   • 如果命令名为 test-runner，则将相关 Agent 命名为 test-runner-agent
   • 技能目录名应与其用途相符

2. 清晰度：使用能表明用途的描述性名称

   • 推荐：api-integration-testing/、code-quality-checker.md
   • 避免：utils/、misc.md、temp.sh

3. 长度：兼顾简洁与清晰

   • 命令：2–3 个词（review-pr、run-ci）
   • Agent：清楚描述角色（code-reviewer、test-generator）
   • 技能：聚焦主题（error-handling、api-design）

可移植性

1. 始终使用 ${CLAUDE_PLUGIN_ROOT}：切勿硬编码路径
2. 在多种系统上测试：验证 macOS、Linux 和 Windows 上的表现
3. 记录依赖项：列出所需工具和版本
4. 避免系统特定功能：使用可移植的 bash/Python 语法

维护

1. 统一版本号：发布时更新 plugin.json 中的版本号
2. 平稳弃用：在移除旧组件前明确标记
3. 记录不兼容变更：注明影响现有用户的变更
4. 彻底测试：变更后验证所有组件均可正常工作

常见模式

最简插件

不含依赖项的单个命令：

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

功能完整的插件

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

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
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

故障排除

组件未加载：

• 确认文件位于正确目录中，且扩展名正确
• 检查 YAML frontmatter 语法（命令、Agent、技能）
• 确保技能包含 SKILL.md（而不是 README.md 或其他名称）
• 确认已在 Claude Code 设置中启用插件

路径解析错误：

• 将所有硬编码路径替换为 ${CLAUDE_PLUGIN_ROOT}
• 确认路径为相对路径，且在清单中以 ./ 开头
• 检查引用的文件是否位于指定路径
• 在钩子脚本中使用 echo $CLAUDE_PLUGIN_ROOT 进行测试

自动发现未生效：

• 确认目录位于插件根目录（而不是 .claude-plugin/ 中）
• 检查文件命名是否符合规范（kebab-case，扩展名正确）
• 确认清单中的自定义路径正确
• 重启 Claude Code 以重新加载插件配置

插件之间存在冲突：

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

---

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