大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 
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/ # 技能目录（可选，封装可复用的功能逻辑） │ └── 
  
    
    
      / # 单个技能目录（如project-init） │ ├── SKILL.md # 技能主文件（必需，定义技能触发条件、逻辑） │ ├── scripts/ # 辅助脚本目录（可选，存放技能依赖的脚本） │ └── references/ # 参考文档目录（可选） ├── commands/ # 斜杠命令目录（可选，定义可直接调用的命令） │ └── 
     
       .md # 单个命令文件（如project-new.md） ├── agents/ # 智能体目录（可选，定义专用智能体角色） │ └── 
      
        .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": "" # 联系邮箱（可选） }, "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": "" }, "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 } ] } ] } }

常用钩子类型：

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

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个技能或命令），熟悉开发流程后再逐步扩展功能，同时参考成熟插件的实现方式，提升插件的实用性和兼容性。