创建插件

创建自定义插件，用技能、智能体、钩子和 MCP 服务器扩展 Claude Code。

插件让你能用自定义功能扩展 Claude Code，并可以在多个项目和团队之间共享。本指南介绍如何用技能、智能体、钩子和 MCP 服务器创建你自己的插件。

想安装现有插件？请参阅发现并安装插件。完整技术规范请参阅插件参考文档。

何时使用插件而不是独立配置

Claude Code 支持两种添加自定义技能、智能体和钩子的方式：

在以下情况使用独立配置：

• 你正在为单个项目定制 Claude Code
• 该配置是个人的，不需要共享
• 你在打包之前先对技能或钩子进行实验
• 你想用像 /hello 或 /deploy 这样的简短技能名称

在以下情况使用插件：

• 你想与团队或社区分享某个功能
• 你需要在多个项目中使用相同的技能/智能体
• 你想为你的扩展做版本控制并方便更新
• 你要通过某个市场分发
• 你能接受像 /my-plugin:hello 这样带命名空间的技能（命名空间可防止插件之间的冲突）

快速开始

本快速开始教程将带你创建一个带自定义技能的插件。你会创建一个清单（定义你插件的配置文件），添加一个技能，并用 --plugin-dir 标志在本地测试它。

前提条件

• Claude Code 已安装并完成身份验证

创建你的第一个插件

mkdir my-first-plugin

mkdir my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

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

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

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

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

你已经成功创建并测试了一个包含以下关键组件的插件：

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

在你的技能目录中开发插件

除了每次启动都传入 --plugin-dir，你还可以把一个插件保存在你的技能目录中，让 Claude Code 自动加载它。claude plugin init 可以为你搭建一个：

claude plugin init my-tool

这会创建 ~/.claude/skills/my-tool/，其中包含一个 .claude-plugin/plugin.json 清单和一个初始的 SKILL.md。下次会话中，它会以 my-tool@skills-dir 的形式加载，无需市场或安装步骤。

关于自动加载规则、个人范围与项目范围、工作区信任要求，以及如何更新或移除它，请参阅技能目录插件。

插件结构概览

你已经创建了一个带技能的插件，但插件可以包含更多内容：自定义智能体、钩子、MCP 服务器、LSP 服务器和后台监视器。

一个只提供一个技能的插件，可以直接将 SKILL.md 放在插件根目录，而不必创建 skills/ 目录。Claude Code 会把它作为单个技能加载，并使用 frontmatter 中的 name 字段作为调用名称。对于可能扩展到多个技能的插件，请使用 skills/ 布局。

开发更复杂的插件

一旦你熟悉了基本插件，就可以创建更复杂的扩展。

为你的插件添加 Skills

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

在你的插件根目录添加一个 skills/ 目录，其中包含带 SKILL.md 文件的 Skill 文件夹：

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

每个 SKILL.md 都包含 YAML frontmatter 和指令。请包含一个 description，让 Claude 知道何时使用该技能：

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

安装该插件后，运行 /reload-plugins 加载这些 Skills。关于包括渐进式披露和工具限制的完整 Skill 编写指南，请参阅Agent Skills。

为你的插件添加 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": "Application error log"
  }
]

command 的每一行 stdout 输出，都会在会话期间以通知的形式传递给 Claude。关于包括 when 触发器和变量替换的完整模式，请参阅监视器。

随你的插件附带默认设置

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

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

{
  "agent": "security-reviewer"
}

以下示例激活了该插件 agents/ 目录中定义的 security-reviewer 智能体。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 即可应用更新而无需重启。这会重新加载插件、技能、智能体、钩子、插件 MCP 服务器和插件 LSP 服务器。测试你的插件组件：

• 用 /plugin-name:skill-name 试试你的技能
• 检查智能体是否出现在 /context 的 Custom Agents 下，或用其限定名称 @-提及它
• 验证钩子是否按预期工作

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

要测试一个已经打包为 .zip 归档、并托管在某个网址上的插件（例如某个 CI 构建产物），请改用 --plugin-url。Claude Code 会在启动时获取该归档，并只为该次会话加载它。如果获取失败或该归档无效，Claude Code 会报告一个插件加载错误，并在没有它的情况下启动。与任何插件来源一样，同样的信任考量也适用：只把这个标志指向你控制或信任的归档。

要加载多个插件，为每个网址重复该标志：

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

或将以空格分隔的多个网址作为一个带引号的参数传入：

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

调试插件问题

如果你的插件没有按预期工作：

1. 检查结构：确保你的目录位于插件根目录，而不是在 .claude-plugin/ 内部
2. 单独测试各个组件：分别检查每个技能、智能体和钩子
3. 使用校验和调试工具：关于 CLI 命令和排查技巧，请参阅调试与开发工具

分享你的插件

当你的插件准备好分享时：

1. 添加文档：包含一份带安装和使用说明的 README.md
2. 选择一种版本管理策略：决定是设置一个显式的 version，还是依赖 git commit SHA。请参阅版本管理
3. 创建或使用一个市场：通过插件市场分发以供安装
4. 与他人一起测试：在更广泛分发之前，让团队成员测试该插件

一旦你的插件进入某个市场，其他人就可以按照发现并安装插件中的说明安装它。要让某个插件只在你的团队内部使用，请将该市场托管在一个私有仓库中。

将你的插件提交到社区市场

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

• claude-plugins-official：由 Anthropic 维护的一组精选插件。你第一次交互式启动 Claude Code 时会自动注册。在这次首次启动之前运行的非交互式脚本，必须用 claude plugin marketplace add anthropics/claude-plugins-official 显式添加它。
• claude-community：第三方提交经审核后落地的公开社区市场。用户用 /plugin marketplace add anthropics/claude-plugins-community 添加它，并以 @claude-community 的形式从中安装。

要将你的插件提交给社区市场审核，可使用以下应用内表单之一：

• claude.ai：claude.ai/admin-settings/directory/submissions/plugins/new
• Console：platform.claude.com/plugins/submit

claude.ai 表单要求组织为 Team 或 Enterprise，并具有目录管理权限；组织的 Owner 默认拥有此权限。不属于 Team 或 Enterprise 组织的个人作者可以改用 Console 表单。

提交前请在本地运行 claude plugin validate。审核流水线会对每次提交运行相同的检查，并附带自动化安全筛查。

审核通过的插件会锁定在 anthropics/claude-plugins-community 目录中的一个特定 commit SHA 上，当你向仓库推送新提交时，CI 会自动更新这个锁定点。这个公开目录每晚从审核流水线同步一次，因此审核通过与你的插件出现在 marketplace.json 中之间可能存在延迟。要查看你的插件是否已可安装，请在社区目录中搜索其名称。

官方市场 claude-plugins-official 是单独精选的。Anthropic 会自行决定收录哪些插件。没有申请流程，提交表单也不会把插件添加到官方市场。

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

将现有配置转换为插件

如果你已经在 .claude/ 目录中有技能或钩子，可以将它们转换为插件，方便共享和分发。

迁移步骤

mkdir -p my-plugin/.claude-plugin

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

mkdir my-plugin/hooks

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

迁移时会发生什么变化

后续步骤

既然你已经理解了 Claude Code 的插件系统，以下是针对不同目标的建议路径：

对于插件用户

• 发现并安装插件：浏览市场并安装插件
• 配置团队市场：为你的团队搭建仓库级插件

对于插件开发者

• 创建并分发市场：打包并分享你的插件
• 插件参考文档：完整的技术规范
• 深入了解具体的插件组件：
  • 技能：技能开发详情
  • 子智能体：智能体配置与能力
  • 钩子：事件处理与自动化
  • MCP：外部工具集成