插件（Plugin）是可打包分发的 Claude Code 扩展，包含 skills、agents、hooks、MCP 服务器等组件。从创建 plugin.json 清单、编写 skill 开始，使用 claude --plugin-dir 本地测试，走通整个开发流程。与独立配置（.claude/）相比，插件支持团队共享、多项目复用和市场发布，但 skill 名称会带上命名空间前缀（如 /my-plugin:hello）。

Claude Code 插件创建全流程：从零开发到提交市场

创建自定义插件，用 skills、agents、hooks 和 MCP 服务器扩展 Claude Code。

插件让你以可跨项目和团队共享的方式扩展 Claude Code。本指南覆盖创建插件的完整流程：skills、agents、hooks 和 MCP 服务器。

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

插件 vs 独立配置：怎么选

Claude Code 支持两种方式添加自定义 skills、agents 和 hooks：

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

使用独立配置的场景：

只为单个项目定制 Claude Code
配置是个人使用，不需要共享
在打包前试验 skill 或 hook
想要简洁的 skill 名称，如 /hello 或 /deploy

使用插件的场景：

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

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

快速入门：5 分钟创建第一个插件

本快速入门带你创建一个带自定义 skill 的插件：创建清单（定义插件的配置文件）、添加 skill、用 --plugin-dir 标志本地测试。

前提条件

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

如果看不到 /plugin 命令，请更新 Claude Code 到最新版本。升级步骤见问题排查。

创建第一个插件

创建插件目录：每个插件独占一个目录，包含清单和你的 skills、agents 或 hooks。
```
mkdir my-first-plugin
```

创建插件清单：清单文件 .claude-plugin/plugin.json 定义插件的身份信息——名称、描述和版本。Claude Code 用这些元数据在插件管理器中展示你的插件。

在插件文件夹内创建 .claude-plugin 目录：

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`	唯一标识符和 skill 命名空间。skill 以此字段为前缀（例如 `/my-first-plugin:hello`）。
`description`	在插件管理器中浏览或安装时显示。
`version`	可选。如果设置，只有当你更新此字段时用户才会收到更新。如果省略且通过 git 分发插件，则使用 commit SHA，每次提交算一个新版本。见版本管理。
`author`	可选。用于归属。

更多字段（如 homepage、repository、license）见完整清单 schema。

添加 skill：skill 放在 skills/ 目录下。每个 skill 是一个文件夹，内含一个 SKILL.md 文件。文件夹名称就是 skill 名称，加上插件的命名空间前缀（名称 my-first-plugin 的插件中 hello/ 目录创建 /my-first-plugin:hello）。

在插件文件夹中创建 skill 目录：
```
mkdir -p my-first-plugin/skills/hello
```
然后创建 my-first-plugin/skills/hello/SKILL.md：
```
---
description: 用友好的消息问候用户
disable-model-invocation: true
---

热情地问候用户，询问今天能为他们做什么。
```
测试插件：用 --plugin-dir 标志运行 Claude Code，加载你的插件：
```
claude --plugin-dir ./my-first-plugin
```
Claude Code 启动后，试试你的新 skill：
```
/my-first-plugin:hello
```
Claude 会回复问候语。运行 /help 可以看到你的 skill 列在插件命名空间下。

为什么用命名空间？ 插件 skill 总是带命名空间（如 /my-first-plugin:hello），防止多个插件中有同名的 skill 冲突。要修改命名空间前缀，更新 plugin.json 中的 name 字段。
让 skill 接收参数：用 $ARGUMENTS 占位符捕获用户输入。更新 SKILL.md 文件：
```
---
description: 用个性化消息问候用户
---

# Hello Skill

热情地问候名为 "$ARGUMENTS" 的用户，询问今天能为他们做什么。让问候个性化且鼓励人心。
```
运行 /reload-plugins 让改动生效，然后用你的名字测试：
```
/my-first-plugin:hello Alex
```
Claude 会叫你的名字问候。更多 skill 传参说明见技能。

你已成功创建并测试了包含以下核心组件的插件：

插件清单（.claude-plugin/plugin.json）：描述插件元数据
技能目录（skills/）：包含自定义 skill
技能参数（$ARGUMENTS）：捕获用户输入实现动态行为

--plugin-dir 标志适合开发和测试。准备共享时，见创建并分发插件市场。

插件结构概览

你已创建了带 skill 的插件，但插件可以包含更多：自定义 agents、hooks、MCP 服务器、LSP 服务器和后台监视器。

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

目录/文件	位置	用途
`.claude-plugin/`	插件根目录	包含 `plugin.json` 清单（如果组件使用默认位置则可选）
`skills/`	插件根目录	skill，以 `<name>/SKILL.md` 目录形式存在
`commands/`	插件根目录	扁平 Markdown 文件形式的 skill。新插件请用 `skills/`
`agents/`	插件根目录	自定义 agent 定义
`hooks/`	插件根目录	`hooks.json` 中的事件处理器
`.mcp.json`	插件根目录	MCP 服务器配置
`.lsp.json`	插件根目录	用于代码智能的 LSP 服务器配置
`monitors/`	插件根目录	`monitors.json` 中的后台监视器配置
`bin/`	插件根目录	插件启用时加入 Bash 工具 `PATH` 的可执行文件
`settings.json`	插件根目录	插件启用时应用的设置默认值

下一步：准备添加更多功能？跳转到开发更复杂的插件添加 agents、hooks、MCP 服务器和 LSP 服务器。所有插件组件的完整技术规范见插件技术参考。

开发更复杂的插件

掌握基础插件后，可以创建更复杂的扩展。

为插件添加 Skills

插件可以包含Agent Skills来扩展 Claude 的能力。Skill 是模型调用的：Claude 根据任务上下文自动使用它们。

在插件根目录添加 skills/ 目录，里面放包含 SKILL.md 文件的 Skill 文件夹：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

每个 SKILL.md 包含 YAML frontmatter 和指令。description 字段让 Claude 知道何时使用该 skill：

---
description: 检查代码最佳实践和潜在问题。审查代码、检查 PR 或分析代码质量时使用。
---

审查代码时，检查以下方面：
1. 代码组织和结构
2. 错误处理
3. 安全问题
4. 测试覆盖率

安装插件后，运行 /reload-plugins 加载 Skill。完整 Skill 编写指南（包括渐进式披露和工具限制）见Agent Skills。

为插件添加 LSP 服务器

对于 TypeScript、Python、Rust 等常见语言，从官方市场安装预构建的 LSP 插件。仅在需要支持未覆盖的语言时才创建自定义 LSP 插件。

LSP（语言服务器协议）插件让 Claude 获得实时代码智能。如果需要支持没有官方 LSP 插件的语言，可以在插件中添加 .lsp.json 文件：

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

安装你插件的用户必须在机器上安装语言服务器二进制文件。

完整 LSP 配置选项见LSP 服务器。

为插件添加后台监视器

后台监视器让插件在后台监听日志、文件或外部状态，在事件到达时通知 Claude。插件激活时 Claude Code 会自动启动每个监视器，无需你让 Claude 开始监听。

在插件根目录添加 monitors/monitors.json 文件，包含一个监视器条目数组：

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "应用程序错误日志"
  }
]

command 的每个 stdout 行都会在会话期间作为通知传递给 Claude。完整 schema（包括 when 触发器和变量替换）见监视器。

为插件配置默认设置

插件可以在根目录包含 settings.json 文件，在启用时应用默认配置。目前只支持 agent 和 subagentStatusLine 键。

设置 agent 会激活插件中的一个自定义 agent作为主线程，应用其系统提示、工具限制和模型。这让插件在启用时改变 Claude Code 的默认行为。

{
  "agent": "security-reviewer"
}

这个例子激活插件 agents/ 目录中定义的 security-reviewer agent。settings.json 中的设置优先于 plugin.json 中声明的 settings。未知键会被静默忽略。

组织复杂插件

组件较多的插件可以根据功能组织目录结构。完整目录布局和组织模式见插件目录结构。

本地测试插件

开发阶段用 --plugin-dir 标志测试插件。它直接加载插件，无需安装。

claude --plugin-dir ./my-plugin

该标志也接受插件目录的 .zip 压缩包，需要 Claude Code v2.1.128 或更高版本。

claude --plugin-dir ./my-plugin.zip

当 --plugin-dir 插件与已安装的市场插件同名时，本地副本在该会话中优先。这样你无需卸载即可测试已有插件的变更。例外情况是强制启用或禁用设置的插件：--plugin-dir 无法覆盖这些设置。

修改插件后，运行 /reload-plugins 即可更新，无需重启。这会重载插件、skills、agents、hooks、插件 MCP 服务器和 LSP 服务器。测试插件组件：

用 /plugin-name:skill-name 测试 skill
在 /agents 中检查 agent 是否存在
验证 hook 是否按预期工作

可以同时加载多个插件，重复使用该标志：
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

要测试已打包为 .zip 压缩包并托管在 URL 上的插件（如 CI 构建产物），改用 --plugin-url。Claude Code 启动时获取压缩包，仅在当前会话加载。如果获取失败或压缩包无效，Claude Code 会报告插件加载错误，无此插件启动。与所有插件来源一样适用相同的信任考量：只将此标志指向你信任或你控制的压缩包。

加载多个插件时，为每个 URL 重复该标志：

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

或者将多个空格分隔的 URL 作为带引号的一个参数传递：

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

调试插件问题

如果插件不按预期工作：

检查结构：确保目录位于插件根目录，而非 .claude-plugin/ 内
逐个测试组件：单独检查每个 skill、agent 和 hook
使用验证和调试工具：CLI 命令和调试技巧见调试与开发工具

共享插件

插件准备好共享时：

添加文档：包含 README.md，写明安装和使用说明
选择版本策略：决定是否设置显式 version 还是依赖 git commit SHA。见版本管理
创建或使用市场：通过插件市场分发，方便安装
与他人测试：让团队成员在广泛分发前测试

插件上线市场后，其他人可以用发现并安装插件中的说明安装。要让插件仅供团队内部使用，将市场托管在私有仓库中。

提交插件到社区市场

Anthropic 维护两个 Claude Code 插件的公开市场：

claude-plugins-official：Anthropic 维护的策划精选集。每次 Claude Code 安装默认可用。
claude-community：公开社区市场，第三方提交审核后出现在这里。用户用 /plugin marketplace add anthropics/claude-plugins-community 添加，从其中安装时用 @claude-community。

要提交插件供社区市场审核，使用以下应用内表单之一：

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

提交前在本地运行 claude plugin validate。审核流水线对每个提交运行同样的检查，以及自动化安全筛查。

批准的插件会锁定到 anthropics/claude-plugins-community 目录中的特定 commit SHA，当你推送新提交到仓库时，CI 会自动更新锁定。公开目录每晚从审核流水线同步，因此批准和插件出现在 marketplace.json 之间可能有延迟。要检查插件是否可安装，在社区目录中搜索其名称。

官方市场 claude-plugins-official 单独策划。Anthropic 酌情决定包含哪些插件。没有申请流程，提交表单不会向官方市场添加插件。

如果 Anthropic 将你的插件列入官方市场，你的 CLI 可以提示 Claude Code 用户安装它。见从你的 CLI 推荐插件。

完整技术规范、调试技巧和分发策略见插件技术参考。

从独立配置转换为插件

如果 .claude/ 目录中已有 skills 或 hooks，可以转换为插件，方便共享和分发。

迁移步骤

创建新的插件目录和清单文件：

mkdir -p my-plugin/.claude-plugin

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

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

将现有配置复制到插件目录：

# 复制 commands
cp -r .claude/commands my-plugin/

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

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

如果设置中有 hooks，创建 hooks 目录：

mkdir my-plugin/hooks

创建 my-plugin/hooks/hooks.json 并复制 hooks 配置。格式与 .claude/settings.json 或 settings.local.json 中的 hooks 对象相同。命令从 stdin 接收 JSON 格式的 hook 输入，因此用 jq 提取文件路径：

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

加载插件验证一切正常：
```
claude --plugin-dir ./my-plugin
```
测试每个组件：运行 commands、检查 /agents 中 agent 是否出现、验证 hooks 是否正确触发。

迁移前后对比

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

迁移后，可以删除 .claude/ 中的原始文件以避免重复。加载时插件版本优先。

下一步

现在你理解了 Claude Code 的插件系统，以下是根据不同目标的建议路径：

面向插件用户

发现并安装插件：浏览市场并安装插件
配置团队市场：为团队设置仓库级插件

面向插件开发者

创建并分发市场：打包并共享插件
插件技术参考：完整技术规范
深入了解特定插件组件：
- Skills：技能开发详情
- 子代理：agent 配置和能力
- Hooks：事件处理和自动化
- MCP：外部工具集成

常见问题

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

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

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

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

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

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

Claude Code 插件创建全流程：从零开发到提交市场 #

插件 vs 独立配置：怎么选 #

快速入门：5 分钟创建第一个插件 #

前提条件 #

创建第一个插件 #

插件结构概览 #

开发更复杂的插件 #

为插件添加 Skills #

为插件添加 LSP 服务器 #

为插件添加后台监视器 #

为插件配置默认设置 #

组织复杂插件 #

本地测试插件 #

调试插件问题 #

共享插件 #

提交插件到社区市场 #

从独立配置转换为插件 #

迁移步骤 #

迁移前后对比 #

下一步 #

面向插件用户 #

面向插件开发者 #

常见问题 #

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

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

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