⚡

plugin-structureSkill plugin-structure

这个技能是关于Claude Code插件结构的理解和组织，帮助开发者创建和维护具有标准化目录布局、自动发现组件、清单配置和可移植路径的插件。它涵盖了命令、代理、技能和钩子的设置，提升插件开发效率和可维护性。关键词包括：Claude插件、技能结构、自动加载、目录规范、AI插件开发。

AI智能体 0 次安装 0 次浏览 更新于 3/16/2026

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

Claude Code插件结构

概述

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

关键概念：

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

目录结构

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

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

关键规则：

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

名称要求：

  • 使用烤肉串式格式（小写加连字符）
  • 必须在已安装的插件中唯一
  • 无空格或特殊字符
  • 示例：code-review-assistant、test-runner、api-docs

推荐元数据

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "插件目的的简要说明",
  "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"]
}

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

组件路径配置

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

{
  "name": "plugin-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: command-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"

文件命名约定

组件文件

命令：使用烤肉串式.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自动发现并加载组件：

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

发现时机：

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

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

最佳实践

组织

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

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

  2. 最小清单：保持plugin.json简洁

    • 仅在必要时指定自定义路径
    • 依赖自动发现处理标准布局
    • 仅对简单情况使用内联配置

  3. 文档：包含README文件

    • 插件根目录：整体目的和用法
    • 组件目录：具体指导
    • 脚本目录：用法和需求

命名

  1. 一致性：在组件间使用一致的命名

    • 如果命令是test-runner，命名相关代理为test-runner-agent
    • 匹配技能目录名与其目的

  2. 清晰度：使用指示目的的描述性名称

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

  3. 长度：平衡简洁与清晰

    • 命令：2-3词（review-pr、run-ci）
    • 代理：清楚描述角色（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    # 仅名称字段
└── 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/内）
  • 检查文件命名遵循约定（烤肉串式、正确扩展名）
  • 验证清单中的自定义路径正确
  • 重启Claude Code以重新加载插件配置

插件间冲突：

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

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