创建插件

Plugins 让你能够使用自定义功能扩展 Claude Code，这些功能可以在项目和团队中共享。本指南涵盖如何使用 skills、agents、hooks 和 MCP servers 创建自己的插件。想要安装现有插件？请参阅发现和安装插件。有关完整的技术规范，请参阅插件参考。

何时使用插件与独立配置

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

方法	Skill 名称	最适合
独立（`.claude/` 目录）	`/hello`	个人工作流、项目特定的自定义、快速实验
插件（包含 skills、agents、hooks 或 `.claude-plugin/plugin.json` 清单的自包含目录）	`/plugin-name:hello`	与团队成员共享、分发到社区、版本化发布、跨项目重用

从 .claude/ 中的独立配置开始进行快速迭代，然后在准备好共享时转换为插件。

快速开始

本快速开始将引导你创建一个带有自定义 skill 的插件。你将创建一个清单（定义插件的配置文件）、添加一个 skill，并使用 --plugin-dir 标志在本地测试它。

前置条件

Claude Code 已安装并已认证

创建你的第一个插件

创建插件目录

每个插件都位于其自己的目录中，包含你的 skills、agents 或 hooks，可选地与 .claude-plugin/plugin.json 清单一起。该位置对于本快速开始并不重要，因为你将在测试步骤中使用 --plugin-dir 指向 Claude Code 该目录。在任何方便的地方创建它，例如临时文件夹或项目目录：

mkdir my-first-plugin

其余步骤从父目录运行，并引用相对于它的路径，如 my-first-plugin/...。

创建插件清单

位于 .claude-plugin/plugin.json 的清单文件定义了你的插件的身份：其名称、描述和版本。Claude Code 使用此元数据在插件管理器中显示你的插件。在你的插件文件夹内创建 .claude-plugin 目录：

mkdir my-first-plugin/.claude-plugin

然后使用以下内容创建 my-first-plugin/.claude-plugin/plugin.json：

my-first-plugin/.claude-plugin/plugin.json

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

字段	目的
`name`	唯一标识符和 skill 命名空间。Skills 以此为前缀（例如 `/my-first-plugin:hello`）。
`description`	在浏览或安装插件时在插件管理器中显示。
`version`	可选。如果设置，用户仅在你更新此字段时接收更新，除了 `command` 源或就地加载的插件；请参阅版本管理。如果省略，版本来自版本管理中的下一个源。
`author`	可选。有助于归属。

有关 homepage、repository 和 license 等其他字段，请参阅完整清单架构。

添加 skill

Skills 位于 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：

my-first-plugin/skills/hello/SKILL.md

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

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

测试你的插件

使用 --plugin-dir 标志运行 Claude Code 以加载你的插件：

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

Claude Code 启动后，尝试你的新 skill：

/my-first-plugin:hello

你将看到 Claude 用问候语回应。运行 /help 并打开自定义命令选项卡以查看你的 skill 在插件命名空间下列出。

为什么要命名空间？ 插件 skills 总是命名空间化的（如 /my-first-plugin:hello），以防止多个插件具有相同名称的 skills 时发生冲突。要更改命名空间前缀，请更新 plugin.json 中的 name 字段。

添加 skill 参数

通过接受用户输入使你的 skill 动态化。$ARGUMENTS 占位符捕获用户在 skill 名称后提供的任何文本。更新你的 SKILL.md 文件：

my-first-plugin/skills/hello/SKILL.md

---
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.

运行 /reload-plugins 以获取更改。然后尝试使用你的名字的 skill：

/my-first-plugin:hello Alex

Claude 将按名字问候你。有关向 skills 传递参数的更多信息，请参阅 Skills。

--plugin-dir 标志对开发和测试很有用。当你准备好与他人共享你的插件时，请参阅创建和分发插件市场。

在你的 skills 目录中开发插件

与其在每次启动时传递 --plugin-dir，你可以在你的 skills 目录中保留一个插件，并让 Claude Code 自动加载它。claude plugin init 会为你搭建一个：

claude plugin init my-tool

这会创建 ~/.claude/skills/my-tool/，其中包含 .claude-plugin/plugin.json 清单和一个启动器 SKILL.md。在下一个会话中，它会作为 my-tool@skills-dir 加载，无需市场或安装步骤。有关自动加载规则、个人与项目范围、工作区信任要求以及如何更新或删除一个，请参阅 Skills-directory plugins。

插件结构概览

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

常见错误：不要将 commands/、agents/、skills/ 或 hooks/ 放在 .claude-plugin/ 目录内。只有 plugin.json 应该在 .claude-plugin/ 内。所有其他目录必须在插件根级别。插件根是单个插件自己的目录，例如来自快速开始的 my-first-plugin/。它永远不是 ~/.claude/。例如，Claude Code 不会读取放在 ~/.claude/.mcp.json 的 .mcp.json。

目录	位置	目的
`.claude-plugin/`	插件根	包含 `plugin.json` 清单（如果组件使用默认位置，则可选）
`skills/`	插件根	Skills 作为 `<name>/SKILL.md` 目录
`commands/`	插件根	Skills 作为平面 Markdown 文件。为新插件使用 `skills/`
`agents/`	插件根	自定义 agent 定义
`hooks/`	插件根	`hooks.json` 中的事件处理程序
`.mcp.json`	插件根	MCP server 配置
`.lsp.json`	插件根	用于代码智能的 LSP server 配置
`monitors/`	插件根	`monitors.json` 中的后台监视器配置
`bin/`	插件根	在启用插件时添加到 Bash tool 的 `PATH` 的可执行文件。你不能在通过 claude.ai 组织设置分发的插件中包含此目录
`settings.json`	插件根	启用插件时应用的默认设置

恰好包含一个 skill 的插件可以直接在插件根目录放置 SKILL.md，而不是创建 skills/ 目录。Claude Code 会将其作为单个 skill 加载，并使用 frontmatter 中的 name 字段作为调用名称。对于可能增长到多个 skill 的插件，请使用 skills/ 布局。

开发更复杂的插件

一旦你对基本插件感到满意，你可以创建更复杂的扩展。

向你的插件添加 Skills

插件可以包含 Agent Skills 以扩展 Claude 的功能。Skills 是模型调用的：Claude 根据任务上下文自动使用它们。在你的插件根目录添加一个 skills/ 目录，其中包含包含 SKILL.md 文件的 Skill 文件夹：

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

每个 SKILL.md 包含 YAML frontmatter 和说明。包含一个 description，以便 Claude 知道何时使用该 skill：

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

安装插件后，检查安装摘要：如果它报告 Run /reload-plugins to activate.，请参阅 Apply plugin changes without restarting 以在当前会话中加载 Skills。有关完整的 Skill 编写指南，包括渐进式披露和工具限制，请参阅 Agent Skills。

向你的插件添加 LSP servers

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

LSP（Language Server Protocol）插件为 Claude 提供实时代码智能。如果你需要支持没有官方 LSP 插件的语言，你可以通过向你的插件添加 .lsp.json 文件来创建自己的：

.lsp.json

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

安装你的插件的用户必须在其机器上安装语言服务器二进制文件。要确认服务器启动，使用启用的插件启动 Claude Code 并检查 /plugin Errors 标签：启动失败的语言服务器会出现在那里，例如当二进制文件未安装时显示 Executable not found in $PATH。具有无效配置的条目会被跳过；运行 claude --debug 以查看原因。有关完整的 LSP 配置选项，请参阅 LSP servers。

向你的插件添加后台监视器

后台监视器让你的插件在后台监视日志、文件或外部状态，并在事件到达时通知 Claude。Claude Code 在插件处于活动状态时自动启动每个监视器，因此你无需指示 Claude 启动监视。在插件根目录添加一个 monitors/monitors.json 文件，其中包含监视器条目数组：

monitors/monitors.json

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

来自 command 的每个 stdout 行在会话期间作为通知传递给 Claude。有关完整的架构，包括 when 触发器和变量替换，请参阅 Monitors。

使用你的插件提供默认设置

插件可以在插件根目录包含一个 settings.json 文件，以在启用插件时应用默认配置。目前仅支持 agent 和 subagentStatusLine 键。设置 agent 激活插件的自定义 agents 之一作为主线程，应用其系统提示、工具限制和模型。这让插件在启用时通过改变 Claude Code 的默认行为方式。

settings.json

{
  "agent": "security-reviewer"
}

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

组织复杂的插件

对于具有许多组件的插件，按功能组织你的目录结构。有关完整的目录布局和组织模式，请参阅 Plugin directory structure。

在本地测试你的插件

使用 --plugin-dir 标志在开发期间测试插件。这会直接加载你的插件，无需安装。

claude --plugin-dir ./my-plugin

该标志也接受插件目录的 .zip 存档。

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

当 --plugin-dir 插件与已安装的市场插件同名时，本地副本在该会话中优先。这让你可以测试已安装的插件的更改，而无需先卸载它。由托管设置强制启用或强制禁用的插件是唯一的例外：--plugin-dir 无法覆盖这些。当你对插件进行更改时，运行 /reload-plugins 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers；在没有交互式终端的会话中，插件 MCP server 更改等待你的下一个会话。测试你的插件组件：

使用 /plugin-name:skill-name 尝试你的 skills
检查 agents 是否出现在 /context 中的 Custom Agents 下，或通过其作用域名称 @-mention 其中一个
触发每个 hook 匹配的事件，例如要求 Claude 编辑文件以进行 PostToolUse hook，并确认其效果。Claude Code 在调试日志中记录哪些 hooks 匹配、它们的退出代码和它们的输出

你可以通过多次指定标志来一次加载多个插件：

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

要测试一个插件及其依赖的插件，请参阅 Test a plugin and its dependency locally。

使用 --plugin-dir 尝试插件会告诉你它可以工作。要找出 Claude 实际上多久会使用它一次并获得正确的结果，请使用 claude plugin eval 针对一组测试提示运行它。每个提示会在加载和不加载插件的情况下运行多次，因此你可以看到插件的贡献并在你更改它或新模型发布时捕获回归。要从一个地方加载多个插件，请传递一个包含它们的文件夹，例如 --plugin-dir ./plugins。加载一个插件文件夹需要 Claude Code v2.1.265 或更高版本。Claude Code 读取文件夹的顶级以决定哪些插件加载，在交互式会话中，它也会监视文件夹以查找后续更改：

加载的内容：如果文件夹的顶级没有清单或插件组件，Claude Code 会将其视为插件文件夹。每个具有 .claude-plugin/plugin.json 清单的直接子文件夹作为单独的插件加载。Claude Code 跳过文件夹中的所有其他内容而不报告错误，包括没有清单的插件。
交互式会话期间的更改：你添加的子文件夹在其清单就位后作为新插件加载，当你删除子文件夹时，其插件卸载。Claude Code 为每个更改在会话中打印一行。如果在对话中间应用更改会使提示缓存失效，Claude Code 会保留它，该行说要运行 /reload-plugins 以应用它。

要测试已打包为 .zip 存档并托管在 URL 上的插件（例如 CI 构建工件），请改用 --plugin-url。Claude Code 在启动时获取存档并仅为该会话加载它。如果 Claude Code 无法获取存档或存档无效，它会在没有插件的情况下启动并记录一个插件加载错误，你可以在 /plugin 管理器的 Errors 标签中查看。与任何插件源相同的信任考虑适用：仅将此标志指向你控制或信任的存档。要加载多个插件，请为每个 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 命令和故障排除技术，请参阅 Debugging and development tools

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

添加文档：包含一个 README.md，其中包含安装和使用说明
选择版本控制策略：决定是设置显式 version 还是依赖 version management 中描述的回退。
创建或使用市场：通过 plugin marketplaces 分发以供安装
与他人测试：在更广泛分发之前让团队成员测试插件

一旦你的插件在市场中，其他人可以使用 Discover and install plugins 中的说明安装它。要将插件保持在你的团队内部，请在 private repository 中托管市场。

向社区市场提交你的插件

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

claude-plugins-official：由 Anthropic 维护的精选插件集。在你首次以交互方式启动 Claude Code 时自动注册。如果你在该首次交互启动之前运行 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 组织和目录管理访问权限；组织所有者默认具有此访问权限。不属于 Team 或 Enterprise 组织的个人作者可以改用 Console 表单。在提交之前，在本地运行 claude plugin validate ./your-plugin，将 ./your-plugin 替换为你的插件目录的路径。审查管道对每个提交运行相同的检查，以及自动安全筛选。当验证通过时，Claude Code 打印 ✔ Validation passed，或如果有警告则打印 ✔ Validation passed with warnings。警告不会导致验证失败；添加 --strict 以将它们视为错误。批准的插件被固定到 anthropics/claude-plugins-community 目录中的特定提交 SHA，当你向你的存储库推送新提交时，CI 会自动提升该固定。公共目录每晚从审查管道同步，因此批准和你的插件出现在 marketplace.json 中之间可能会有延迟。要检查你的插件是否已可安装，请在社区目录中搜索其名称。官方市场 claude-plugins-official 是单独策划的。Anthropic 自行决定包含哪些插件。没有申请流程，提交表单不会将插件添加到官方市场。如果 Anthropic 在官方市场中列出你的插件，你的 CLI 可以提示 Claude Code 用户安装它。请参阅 Recommend your plugin from your CLI。

将现有配置转换为插件

如果你已经在 .claude/ 目录中有 skills 或 hooks，你可以将它们转换为插件，以便更轻松地共享和分发。

迁移步骤

创建插件结构

在你的项目根目录中创建一个新的插件目录，与现有的 .claude/ 文件夹并排放置，以便下一步中的相对 cp 路径能够解析：

mkdir -p my-plugin/.claude-plugin

在 my-plugin/.claude-plugin/plugin.json 处创建清单文件：

my-plugin/.claude-plugin/plugin.json

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

复制你现有的文件

将你拥有的每个配置目录复制到插件根目录。你可能没有全部三个：如果一个目录不存在，cp 会打印 No such file or directory 并且不复制任何内容，所以跳过该命令或忽略错误。

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

你的插件现在包含了你在 .claude/ 下拥有的目录的副本。运行 ls my-plugin 来确认：你应该看到你复制的每个目录。

迁移 hooks

如果你在设置中有 hooks，请创建一个 hooks 目录：

mkdir my-plugin/hooks

使用你的 hooks 配置创建 my-plugin/hooks/hooks.json。从你的 .claude/settings.json 或 settings.local.json 复制 hooks 对象，因为格式相同。命令在 stdin 上接收 hook 输入作为 JSON，所以使用 jq 提取文件路径：

my-plugin/hooks/hooks.json

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

测试每个组件：运行你的命令、检查 agents 是否出现在 /context 中，并触发每个 hook 匹配的事件以确认其效果。Claude Code 在调试日志中记录了哪些 hooks 匹配以及它们如何退出。

迁移时的变化

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

迁移后，从 .claude/ 中删除原始文件以避免重复。项目和用户 .claude/agents/ 定义会覆盖同名的插件 agents，因此插件版本仅在删除原始文件后才会生效。Plugin skills 被命名为 /plugin-name:skill-name，所以原始的 /skill-name 和插件副本都保持可用，而不是其中一个覆盖另一个。

后续步骤

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

对于插件用户

发现和安装插件：浏览市场并安装插件
配置团队市场：为你的团队设置存储库级别的插件

对于插件开发者

使用 evals 测试插件：测量你的插件改变了什么并在 CI 中进行门控
创建和分发市场：打包和共享你的插件
插件参考：完整的技术规范
深入了解特定的插件组件：
- Skills：skill 开发详情
- Subagents：agent 配置和功能
- Hooks：事件处理和自动化
- MCP：外部工具集成

代理和并行工作

MCP

技能

插件

制品库

自动化

指南

故障排除

何时使用插件与独立配置

快速开始

前置条件

创建你的第一个插件

在你的 skills 目录中开发插件

插件结构概览

开发更复杂的插件

向你的插件添加 Skills

向你的插件添加 LSP servers

向你的插件添加后台监视器

使用你的插件提供默认设置

组织复杂的插件

在本地测试你的插件

调试插件问题

向社区市场提交你的插件

将现有配置转换为插件

迁移步骤

迁移时的变化

后续步骤

对于插件用户

对于插件开发者

​何时使用插件与独立配置

​快速开始

​前置条件

​创建你的第一个插件

​在你的 skills 目录中开发插件

​插件结构概览

​开发更复杂的插件

​向你的插件添加 Skills

​向你的插件添加 LSP servers

​向你的插件添加后台监视器

​使用你的插件提供默认设置

​组织复杂的插件

​在本地测试你的插件

​调试插件问题

​共享你的插件

​向社区市场提交你的插件

​将现有配置转换为插件

​迁移步骤

​迁移时的变化

​后续步骤

​对于插件用户

​对于插件开发者

何时使用插件与独立配置

快速开始

前置条件

创建你的第一个插件

在你的 skills 目录中开发插件

插件结构概览

开发更复杂的插件

向你的插件添加 Skills

向你的插件添加 LSP servers

向你的插件添加后台监视器

使用你的插件提供默认设置

组织复杂的插件

在本地测试你的插件

调试插件问题

共享你的插件

向社区市场提交你的插件

将现有配置转换为插件

迁移步骤

迁移时的变化

后续步骤

对于插件用户

对于插件开发者