创建插件

插件（Plugin）是可打包分发的 Claude Code 扩展，包含 skills、agents、hooks、MCP 服务器等组件。本文从零讲解创建插件的完整流程：编写 plugin.json 清单、添加第一个 skill、用 --plugin-dir 本地测试、调试常见问题，以及将现有 .claude/ 配置迁移为可分发的插件。与独立配置（.claude/）相比，插件适合团队共享、多项目复用和市场发布。

想要安装已有插件？请查看发现并安装插件。完整技术规范请参阅插件技术参考。

插件 vs 独立配置

方式	技能名称格式	适合场景
独立（.claude/ 目录）	/hello	个人工作流、项目定制、快速实验
插件（含 .claude-plugin/plugin.json 的目录）	/plugin-name:hello	团队共享、社区分发、版本化发布、跨项目复用

使用独立配置的场景：

• 为单个项目定制 Claude Code
• 配置是个人的，无需共享
• 在打包前实验技能或钩子
• 需要简短的技能名称如 /hello 或 /deploy

使用插件的场景：

• 想与团队或社区共享功能
• 需要在多个项目中使用相同的技能/代理
• 需要版本控制和便捷更新
• 通过市场分发
• 可以接受命名空间化的技能名称如 /my-plugin:hello

建议先在 .claude/ 中用独立配置快速迭代，准备共享时再转换为插件。

快速入门

前提条件

• Claude Code 已安装并认证
• Claude Code 版本 1.0.33 或更高（运行 claude --version 查看）

创建第一个插件

步骤 1：创建插件目录

mkdir my-first-plugin

步骤 2：创建插件清单

mkdir my-first-plugin/.claude-plugin

创建 my-first-plugin/.claude-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "description": "学习基础知识的问候插件",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}

字段	用途
name	唯一标识符和技能命名空间（技能以此为前缀）
description	在插件管理器中显示
version	使用语义化版本追踪发布
author	可选，用于归属

步骤 3：添加技能

mkdir -p my-first-plugin/skills/hello

创建 my-first-plugin/skills/hello/SKILL.md：

---
description: 用友好的消息问候用户
disable-model-invocation: true
---

热情地问候用户，询问今天能为他们做什么。

步骤 4：测试插件

claude --plugin-dir ./my-first-plugin

在 Claude Code 中尝试：

/my-first-plugin:hello

步骤 5：添加技能参数

更新 SKILL.md：

---
description: 用个性化消息问候用户
---

热情地问候名为 "$ARGUMENTS" 的用户，询问今天能为他们做什么。让问候个性化且鼓励人心。

运行 /reload-plugins 后测试：

/my-first-plugin:hello Alex

插件结构概览

目录	位置	用途
.claude-plugin/	插件根目录	包含 plugin.json 清单
commands/	插件根目录	Markdown 格式的技能文件
agents/	插件根目录	自定义代理定义
skills/	插件根目录	包含 SKILL.md 的代理技能
hooks/	插件根目录	hooks.json 中的事件处理器
.mcp.json	插件根目录	MCP 服务器配置
.lsp.json	插件根目录	代码智能 LSP 服务器配置
settings.json	插件根目录	插件启用时应用的默认设置

常见错误：不要把 commands/、agents/、skills/ 或 hooks/ 放在 .claude-plugin/ 目录内。只有 plugin.json 放在 .claude-plugin/ 内，其他所有目录必须在插件根目录级别。

开发更复杂的插件

添加 LSP 服务器

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

包含默认设置

{
  "agent": "security-reviewer"
}

本地测试

# 加载单个插件
claude --plugin-dir ./my-plugin

# 同时加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

当 --plugin-dir 插件与已安装的市场插件同名时，本地版本优先，便于在不卸载的情况下测试变更。

修改后运行 /reload-plugins 即时生效，无需重启。

调试问题

1. 检查结构：确保目录在插件根目录，而非在 .claude-plugin/ 内
2. 逐个测试组件：单独检查每个命令、代理和钩子
3. 使用调试工具：运行 claude --debug 查看加载详情

从现有配置转换为插件

步骤 1：创建插件结构

mkdir -p my-plugin/.claude-plugin

创建 my-plugin/.claude-plugin/plugin.json：

{
  "name": "my-plugin",
  "description": "从独立配置迁移",
  "version": "1.0.0"
}

步骤 2：复制现有文件

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/  # 如有
cp -r .claude/skills my-plugin/  # 如有

步骤 3：迁移钩子

创建 my-plugin/hooks/hooks.json，将 hooks 对象从 .claude/settings.json 复制过来：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

迁移前后对比：

独立（.claude/）	插件
仅在一个项目中可用	可通过市场共享
文件在 .claude/commands/	文件在 plugin-name/commands/
钩子在 settings.json	钩子在 hooks/hooks.json
必须手动复制才能共享	通过 /plugin install 安装

提交插件到官方市场

使用应用内提交表单：

• Claude.ai：claude.ai/settings/plugins/submit
• Console：platform.claude.com/plugins/submit

本地测试插件

基本测试方法

# 加载单个插件
claude --plugin-dir ./my-plugin

# 同时加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

当 --plugin-dir 插件与已安装的市场插件同名时，本地版本优先，便于在不卸载的情况下测试变更。

修改后运行 /reload-plugins 即时生效，无需重启。

验证插件结构

# 验证插件 JSON、frontmatter 和 hooks 配置
claude plugin validate .

也可在 Claude Code 内运行 /plugin validate .。

测试各类组件

测试 Skills：

/my-plugin:skill-name          # 调用 skill
/my-plugin:skill-name argument # 带参数调用

查看注册的代理：

/agents

检查 Hooks 是否触发：

运行 claude --debug，查看 hook 事件是否被正确触发和执行。

调试问题

1. 检查结构：确保 commands/、agents/、skills/、hooks/ 在插件根目录，而非 .claude-plugin/ 内
2. 验证清单：运行 claude plugin validate . 检查 JSON 语法和 schema 错误
3. 逐个测试组件：单独检查每个命令、代理和 hook
4. 使用调试模式：运行 claude --debug 查看加载详情和错误消息

---

相关资源

• 发现并安装插件：浏览市场并安装插件
• 插件市场创建：为团队设置和分发市场
• 插件技术参考：完整技术规范
• 技能：技能开发详情
• 子代理：代理配置和能力
• Hooks：事件处理和自动化
• MCP：外部工具集成

---

常见问题

Q: 插件和直接放在 .claude/ 目录的配置有什么实质区别？

最大区别是分发能力。.claude/ 配置只在当前项目可用，不能打包给他人用。插件是独立目录，可以推到 GitHub、发布到市场、通过 /plugin install 一键安装，支持版本管理和自动更新。代价是 skill 名称变成带命名空间的形式（如 /my-plugin:hello）。日常工作流建议先在 .claude/ 里快速迭代，准备共享时再转换为插件。

Q: --plugin-dir 和正式安装的插件有什么不同？

--plugin-dir 是开发模式：直接从指定目录加载，不复制到缓存，修改后 /reload-plugins 即可生效，会话结束后插件不保留。正式安装（通过市场）会把插件复制到 ~/.claude/plugins/cache，每次启动自动加载，支持版本管理和自动更新。开发阶段用 --plugin-dir，发布后通过市场安装。

Q: 官方市场对插件有什么要求，提交后多久审核？

官方市场要求插件名使用 kebab-case、有清晰的 description、无恶意代码。提交地址：claude.ai/settings/plugins/submit 或 platform.claude.com/plugins/submit。审核时间视情况而定，Anthropic 会对功能和安全性进行人工审核。