从零开发Claude Code插件（Plugin）完整指南

Claude Code插件是扩展其功能的核心方式，可封装可复用的技能（Skills）、智能体（Agents）、命令（Commands）等资源，实现跨项目、跨团队的功能共享，适用于标准化工作流程落地、团队协作效率提升等场景。本文结合成熟插件参考案例，从零讲解Claude Code插件的开发、配置、测试与扩展，帮助开发者快速上手插件开发。

一、插件开发前提与核心定位

1.1 开发前提

• 已安装并认证Claude Code，版本需为1.0.33及以上（可通过claude --version命令检查），确保支持/plugin相关命令。

• 了解基础的JSON配置、Markdown语法，熟悉命令行操作，若需开发复杂技能可掌握简单的脚本编写。

• 参考成熟插件实现（如Superpowers Plugin），遵循Claude Code插件的官方规范，避免兼容性问题。

1.2 插件核心定位

Claude Code支持两种自定义扩展方式，插件与独立配置（.claude/目录）的区别如下，开发者可根据需求选择合适的方式：

• 独立配置：适用于个人工作流程、项目特定定制、快速实验，技能名称简短（如/hello），无需打包分享。

• 插件：适用于团队/社区共享、跨项目复用、版本化发布，需通过命名空间区分技能（如/plugin-name:hello），可避免插件间冲突，支持市场分发。

建议先通过独立配置快速迭代功能，功能稳定后再封装为插件，便于分享和维护。

二、插件标准目录结构（必看）

一个规范的Claude Code插件需遵循固定的目录结构，确保插件能被Claude Code正确识别和加载，核心目录如下（所有目录/文件均为小写，采用kebab-case命名规范）：

plugin-demo/  # 插件根目录（名称采用kebab-case，如project-helper-plugin）
├── .claude-plugin/  # 插件核心配置目录（必需）
│   ├── plugin.json   # 插件清单（必需，定义插件基本信息、资源路径）
│   └── marketplace.json  # 市场元数据（可选，用于插件市场分发）
├── skills/          # 技能目录（可选，封装可复用的功能逻辑）
│   └── <skill-name>/  # 单个技能目录（如project-init）
│       ├── SKILL.md  # 技能主文件（必需，定义技能触发条件、逻辑）
│       ├── scripts/  # 辅助脚本目录（可选，存放技能依赖的脚本）
│       └── references/  # 参考文档目录（可选）
├── commands/        # 斜杠命令目录（可选，定义可直接调用的命令）
│   └── <command-name>.md  # 单个命令文件（如project-new.md）
├── agents/          # 智能体目录（可选，定义专用智能体角色）
│   └── <agent-name>.md  # 单个智能体文件（如code-reviewer.md）
├── hooks/           # 钩子配置目录（可选，定义触发时机与执行逻辑）
│   ├── hooks.json   # 钩子配置文件
│   └── run-hook.cmd # 钩子执行脚本（可选）
├── scripts/         # 公共脚本目录（可选，存放插件共用脚本）
└── README.md        # 插件说明文档（可选，说明安装、使用方法）

说明：.claude-plugin目录和plugin.json是插件的核心，缺少则无法被Claude Code识别；其他目录根据插件功能按需创建。

三、核心配置文件开发（重点）

插件的核心配置集中在.plugin.json和marketplace.json，其中plugin.json为必需文件，marketplace.json仅用于插件市场分发，以下是详细配置规范。

3.1 插件清单：plugin.json（必需）

该文件定义插件的基本信息、资源路径、版本等，Claude Code通过该文件识别插件的功能和资源，标准配置如下（可根据插件功能增减字段）：

{
  "name": "plugin-demo",  # 插件名称（kebab-case，唯一标识）
  "version": "1.0.0",     # 版本号（遵循语义化版本，如1.0.0）
  "description": "通用插件示例 - 包含项目初始化、代码审查等技能与命令",  # 插件描述
  "author": {
    "name": "Dev Team",   # 作者/团队名称
    "email": "dev@example.com"  # 联系邮箱（可选）
  },
  "homepage": "https://github.com/xxx/plugin-demo",  # 插件主页（可选，如GitHub地址）
  "repository": "https://github.com/xxx/plugin-demo",  # 代码仓库地址（可选）
  "license": "MIT",       # 开源协议（可选，常用MIT）
  "keywords": [           # 关键词（可选，便于市场搜索）
    "project-init",
    "code-review",
    "devops"
  ],
  "skills": ["./skills/"],  # 技能目录路径（支持目录或单个文件路径）
  "commands": ["./commands/"],  # 命令目录路径（支持目录或单个文件路径）
  "agents": ["./agents/"]  # 智能体目录路径（需显式指定路径）
}

关键说明：

• name字段必须唯一，避免与现有插件重名，采用kebab-case命名（小写字母+连字符）。

• skills、commands可指定目录（如./skills/），自动加载目录下所有技能/命令；agents需显式指定路径，避免加载异常。

• 无需在plugin.json中声明hooks目录，Claude Code会自动识别hooks.json文件。

3.2 市场元数据：marketplace.json（可选）

若需将插件发布到Claude Code插件市场，需配置该文件，定义插件市场相关信息，标准配置如下：

{
  "name": "plugin-demo-marketplace",  # 插件市场名称
  "description": "插件市场示例，用于分发通用插件",  # 市场描述
  "owner": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
  "plugins": [
    {
      "name": "plugin-demo",
      "description": "通用插件示例 - 包含项目初始化、代码审查等技能与命令",
      "version": "1.0.0",
      "source": "./",  # 插件相对于市场目录的路径（./表示当前目录）
      "author": {
        "name": "Dev Team"
      }
    }
  ]
}

四、核心功能模块开发

插件的核心功能由技能（Skills）、命令（Commands）、智能体（Agents）、钩子（Hooks）组成，开发者可根据插件需求，选择性开发对应模块，以下是各模块的开发规范和示例。

4.1 技能开发（skills/）

技能是插件的核心功能单元，可实现特定的工作流程（如项目初始化、代码审查、调试等），每个技能对应一个独立目录，核心文件为SKILL.md。

4.1.1 技能目录结构

skills/
└── project-init/  # 技能名称（kebab-case）
    ├── SKILL.md   # 必需：技能主配置与逻辑文件
    ├── scripts/   # 可选：辅助脚本（如初始化脚本）
    └── references/ # 可选：参考文档（如初始化规范）

4.1.2 SKILL.md标准格式

SKILL.md定义技能的触发条件、核心逻辑、使用规范，采用Markdown格式，标准模板如下：

---
name: project-init  # 技能名称（kebab-case，与目录名一致）
description: "Use when 需要初始化新的开发项目，包括项目结构创建、依赖安装等场景"  # 触发条件描述
---

# 项目初始化技能（project-init）

## Overview
快速初始化开发项目，自动创建标准项目结构、安装依赖，生成基础配置文件，减少手动操作。

## When to Use
- 新建开发项目，需要统一项目结构时
- 团队协作中，需要标准化项目初始化流程时
- 快速搭建测试项目，提升开发效率时

## Core Pattern
1. 询问用户项目类型（如前端、后端、全栈）和技术栈（如Vue、SpringBoot）；
2. 根据用户选择，创建对应的项目目录结构；
3. 自动安装项目依赖，生成基础配置文件（如package.json、config.js）；
4. 提示用户项目初始化完成，并给出后续操作建议。

## Quick Reference
- 触发方式：/use skill project-init
- 依赖环境：Node.js（前端项目）、JDK（后端项目）
- 执行时长：10-30秒（取决于依赖安装速度）

## Common Mistakes
1. 未安装对应技术栈的环境（如未安装Node.js，导致前端项目依赖安装失败）；
2. 项目目录已存在，未提前删除，导致目录创建失败；
3. 网络异常，导致依赖安装中断。

关键说明：开头的YAML配置（---之间的内容）是必需的，用于定义技能名称和触发条件，Claude Code会根据description字段自动触发技能。

4.2 命令开发（commands/）

命令是可直接通过斜杠（/）调用的功能，适用于简单、高频的操作（如新建项目、运行流水线），每个命令对应一个.md文件。

4.2.1 命令标准格式

---
description: "新建开发项目，支持前端、后端、全栈三种类型"  # 命令描述
---

# 新建项目命令（project-new）

## 执行说明
通过该命令可快速新建开发项目，自动匹配对应技术栈的项目结构，无需手动创建目录。

## 使用方式
1. 在Claude Code聊天窗口输入命令：/project-new
2. 按照提示，选择项目类型（前端/后端/全栈）和技术栈；
3. 输入项目名称（kebab-case格式），确认后即可完成项目创建。

## 示例
输入：/project-new
提示：请选择项目类型（1.前端 2.后端 3.全栈）
输入：1
提示：请选择前端技术栈（1.Vue 2.React 3.Angular）
输入：1
提示：请输入项目名称（kebab-case）
输入：vue-demo
结果：项目vue-demo创建完成，目录结构已生成，依赖已自动安装。

## 注意事项
- 项目名称必须采用kebab-case格式（小写字母+连字符），避免特殊字符；
- 若当前目录已存在同名项目，会提示用户是否覆盖；
- 后端项目需提前安装对应JDK版本，否则会创建失败。

关键说明：命令的触发词为文件名（不含.md后缀），如project-new.md对应的触发词为/project-new，无需额外配置。

4.3 智能体开发（agents/）

智能体用于定义特定角色的工作流程（如架构师、代码审查员），可被技能或命令调用，每个智能体对应一个.md文件，标准格式如下：

# 代码审查智能体（code-reviewer）

## 角色定义和职责描述
作为代码审查智能体，负责检查代码的规范性、可读性、安全性，提出合理的优化建议，确保代码质量符合团队标准。

## Expertise
- 熟悉多种编程语言（Java、JavaScript、Python等）的编码规范；
- 能识别常见的代码漏洞（如SQL注入、跨站脚本）；
- 掌握代码重构技巧，能提出简洁、高效的优化方案；
- 了解团队编码规范，确保审查结果符合团队要求。

## Workflow
1. 接收用户提交的代码片段或文件路径；
2. 检查代码规范性（命名、缩进、注释等）；
3. 分析代码安全性，识别潜在漏洞；
4. 评估代码可读性和可维护性，提出重构建议；
5. 整理审查结果，按严重程度分类（ critical / warning / info ）；
6. 给出具体的修改建议，协助用户优化代码。

## Constraints
1. 仅审查用户提交的代码片段或指定文件，不主动获取未提交的代码；
2. 审查结果仅为建议，不直接修改用户代码；
3. 对于不熟悉的技术栈，会明确告知用户，避免给出错误建议；
4. 严格遵循团队编码规范，不随意否定合理的编码方式。

调用方式：在技能或命令中通过@agent-name引用，如@code-reviewer，即可触发该智能体执行对应工作。

4.4 钩子开发（hooks/）

钩子用于定义特定时机触发的操作（如会话启动时加载上下文、工具执行前检查权限），核心文件为hooks.json，标准配置如下：

{
  "hooks": {
    "SessionStart": [  # 钩子类型：会话启动时触发
      {
        "matcher": "startup|clear|compact",  # 触发匹配规则（多个触发词用|分隔）
        "hooks": [
          {
            "type": "command",  # 钩子类型（command：执行命令）
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",  # 执行的命令
            "async": false  # 是否异步执行（false：同步执行，执行完成后再继续）
          }
        ]
      }
    ],
    "PreToolUse": [  # 钩子类型：工具执行前触发
      {
        "matcher": "*",  # 匹配所有工具执行
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" pre-tool-check",
            "async": false
          }
        ]
      }
    ]
  }
}

常用钩子类型：

钩子类型	触发时机	用途
SessionStart	会话启动时	加载插件上下文、初始化环境
PreToolUse	工具执行前	权限检查、参数校验
PostToolUse	工具执行后	结果验证、日志记录

五、插件安装与测试

插件开发完成后，需进行本地安装和测试，确保功能正常、配置无误，以下是详细步骤。

5.1 本地安装

# 1. 进入插件根目录（plugin-demo）
cd plugin-demo

# 2. 本地安装插件（Claude Code会识别.plugin.json文件）
claude plugin install ./

# 3. 验证插件安装是否成功
claude plugin list

若安装成功，会在插件列表中看到当前开发的插件（如plugin-demo）。

5.2 插件验证

# 验证插件配置文件的合法性
claude plugin validate .claude-plugin/plugin.json

若配置无误，会提示"Validation passed"；若存在配置错误，会明确指出错误位置（如字段缺失、格式错误），需根据提示修改。

5.3 功能测试

测试核心功能，确保技能、命令、智能体、钩子能正常工作：

• 命令测试：在Claude Code聊天窗口输入命令（如/project-new），检查是否能正常执行。

• 技能测试：输入触发技能的场景（如"帮我初始化一个前端项目"），检查技能是否自动触发，执行结果是否符合预期。

• 智能体测试：在技能中引用智能体（如@code-reviewer），检查智能体是否能正常执行对应工作。

• 钩子测试：启动会话、执行工具，检查钩子是否在对应时机触发，执行结果是否正确。

六、插件扩展与维护

插件开发完成后，可根据需求添加新功能、更新版本，以下是扩展和维护的核心操作。

6.1 添加新技能

1. 在skills/目录下创建新的技能目录（kebab-case命名，如code-debug）。

2. 按照SKILL.md标准格式，编写技能的配置和逻辑。

3. 若skills路径配置为目录（如./skills/），无需修改plugin.json；若为单个文件路径，需更新plugin.json中的skills字段。

4. 重新安装插件，测试新技能功能。

6.2 添加新命令

1. 在commands/目录下创建新的命令文件（kebab-case命名，如code-debug.md）。

2. 按照命令标准格式，编写命令的执行说明和使用方式。

3. 重新安装插件，在Claude Code中输入对应命令（如/code-debug），测试功能。

6.3 添加新智能体

1. 在agents/目录下创建新的智能体文件（kebab-case命名，如debug-agent.md）。

2. 按照智能体标准格式，编写角色定义、工作流程和约束条件。

3. 在技能或命令中通过@agent-name引用该智能体，测试是否能正常调用。

6.4 插件版本更新

当插件功能更新后，需修改plugin.json中的version字段（遵循语义化版本，如1.0.1），然后重新安装插件，即可完成版本更新。若插件已发布到市场，需同步更新marketplace.json中的版本信息。

七、插件开发规范（必遵循）

遵循规范可确保插件的兼容性、可读性和可维护性，避免出现加载失败、功能冲突等问题。

7.1 命名规范

• 插件名、技能名、命令名、智能体名、目录名均采用kebab-case格式（小写字母+连字符），如plugin-demo、project-init。

• 文件名避免使用特殊字符（如@、#、空格），确保跨平台兼容性。

7.2 文件路径规范

• plugin.json中，agents字段必须使用显式文件路径（可指定目录或单个文件）。

• skills和commands字段可使用目录路径，自动加载目录下所有相关文件。

• hooks目录无需在plugin.json中声明，Claude Code会自动识别。

7.3 兼容性规范

• 插件配置遵循Claude Code官方schema，不添加自定义字段，避免加载失败。

• 技能、命令的触发条件描述清晰，避免与其他插件的技能冲突。

• 脚本文件需考虑跨平台兼容性（如Windows使用.cmd，Linux/Mac使用.sh）。

八、参考资料与常见问题

8.1 参考资料

• Superpowers Plugin：https://github.com/obra/superpowers（成熟插件案例，可参考其目录结构和功能实现）。

• Claude Code官方文档：https://code.claude.com/docs/en/discover-and-install-plugins（插件开发官方规范）。

8.2 常见问题

• 问题1：插件安装失败，提示"link dead"？ 解决：检查插件根目录是否存在.plugin.json文件，配置是否正确；若引用了外部仓库地址，检查地址是否有效、网络是否正常。

• 问题2：技能无法自动触发？ 解决：检查SKILL.md开头的description字段，确保触发条件描述清晰，符合Claude Code的识别规则；重新安装插件，清除会话缓存后重试。

• 问题3：命令调用无响应？ 解决：检查命令文件名是否为kebab-case格式，是否存在拼写错误；检查命令文件中的description字段是否填写，重新安装插件。

• 问题4：钩子不触发？ 解决：检查hooks.json的配置格式是否正确，钩子类型是否符合Claude Code的支持范围；确保钩子脚本路径正确，具有可执行权限。

九、总结

Claude Code插件开发的核心是遵循官方规范，搭建标准的目录结构，正确配置plugin.json文件，再根据需求开发技能、命令、智能体和钩子模块。开发完成后，通过本地安装和测试验证功能，最后可根据需求发布到插件市场，实现跨团队、跨项目的功能共享。

建议开发者从简单的插件入手（如仅包含1-2个技能或命令），熟悉开发流程后再逐步扩展功能，同时参考成熟插件的实现方式，提升插件的实用性和兼容性。