文档索引

在此处获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

创建插件

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

插件允许你使用可在项目和团队之间共享的自定义功能扩展 Claude Code。本指南涵盖使用技能、代理、钩子和 MCP 服务器创建自己的插件。

想要安装现有插件？参见发现和安装插件。有关完整技术规范，请参阅插件参考。

何时使用插件与独立配置

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

使用独立配置当：

• 你正在为单个项目自定义 Claude Code
• 配置是个人的，不需要共享
• 你正在打包之前试验技能或钩子
• 你想要短技能名称如 /hello 或 /deploy

使用插件当：

• 你想要与团队或社区共享功能
• 你需要在多个项目中使用相同的技能/代理
• 你想要版本控制和易于更新的扩展
• 你正在通过市场分发
• 你可以接受命名空间技能如 /my-plugin:hello（命名空间防止插件之间的冲突）

快速入门

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

前提条件

• Claude Code 已安装并认证

创建你的第一个插件

1. 创建插件目录

   每个插件位于自己的目录中，包含清单和你的技能、代理或钩子。现在创建一个：

   mkdir my-first-plugin
   

2. 创建插件清单

   .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": "A greeting plugin to learn the basics",
     "version": "1.0.0",
     "author": {
       "name": "Your Name"
     }
   }
   

   字段	用途
   name	唯一标识符和技能命名空间。技能以此为前缀（例如 /my-first-plugin:hello）。
   description	在浏览或安装插件时在插件管理器中显示。
   version	可选。如果设置，用户仅在此字段更新时接收更新。如果省略且你的插件通过 git 分发，使用提交 SHA，每次提交算作新版本。参见版本管理。
   author	可选。有助于归属。

   有关 homepage、repository 和 license 等附加字段，请参阅完整清单模式。

3. 添加技能

   技能位于 skills/ 目录中。每个技能是包含 SKILL.md 文件的文件夹。文件夹名称成为技能名称，以前缀插件的命名空间（名为 my-first-plugin 的插件中的 hello/ 创建 /my-first-plugin:hello）。

   在插件文件夹中创建技能目录：

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

   然后创建 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.
   

4. 测试你的插件

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

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

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

   /my-first-plugin:hello
   

   你会看到 Claude 以问候语回应。运行 /help 查看你的技能列在插件命名空间下。

   ℹ️

   Note

   为什么需要命名空间？ 插件技能始终使用命名空间（如 /my-first-plugin:hello）以防止多个插件具有同名技能时发生冲突。

   要更改命名空间前缀，更新 plugin.json 中的 name 字段。

5. 添加技能参数

   通过接受用户输入使你的技能动态化。$ARGUMENTS 占位符捕获用户在技能名称后提供的任何文本。

   更新你的 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 获取更改，然后用你的名字尝试技能：

   /my-first-plugin:hello Alex
   

   Claude 会用你的名字问候你。有关向技能传递参数的更多信息，请参阅技能。

你已成功创建并测试了具有以下关键组件的插件：

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

插件结构概览

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

开发更复杂的插件

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

向插件添加技能

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

在插件根目录添加 skills/ 目录，其中包含 SKILL.md 文件的技能文件夹：

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 加载技能。有关完整的技能编写指导，包括渐进式披露和工具限制，请参阅代理技能。

向插件添加 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 尝试你的技能
• 检查代理是否出现在 /agents 中
• 验证钩子按预期工作

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"

调试插件问题

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

1. 检查结构：确保你的目录在插件根目录，而不是在 .claude-plugin/ 内
2. 单独测试组件：分别检查每个技能、代理和钩子
3. 使用验证和调试工具：参见调试和开发工具了解 CLI 命令和故障排除技术

共享你的插件

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

1. 添加文档：包含带有安装和使用说明的 README.md
2. 选择版本控制策略：决定是设置明确的 version 还是依赖 git 提交 SHA。参见版本管理
3. 创建或使用市场：通过插件市场分发安装
4. 与他人测试：在更广泛分发之前让团队成员测试插件

一旦你的插件进入市场，其他人可以使用发现和安装插件中的说明安装它。要保持插件对团队内部使用，在私有仓库中托管市场。

将插件提交到社区市场

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 目录中固定到特定提交 SHA，当你向仓库推送新提交时 CI 自动更新固定。公共目录每晚从审查管道同步，因此批准和你的插件出现在 marketplace.json 之间可能有延迟。要检查你的插件是否可安装，在社区目录中搜索其名称。

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

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

将现有配置转换为插件

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

迁移步骤

1. 创建插件结构

   创建新的插件目录：

   mkdir -p my-plugin/.claude-plugin
   

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

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

2. 复制现有文件

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

   # 复制命令
   cp -r .claude/commands my-plugin/
   
   # 复制代理（如果有）
   cp -r .claude/agents my-plugin/
   
   # 复制技能（如果有）
   cp -r .claude/skills my-plugin/
   

3. 迁移钩子

   如果你的设置中有钩子，创建钩子目录：

   mkdir my-plugin/hooks
   

   创建 my-plugin/hooks/hooks.json，包含你的钩子配置。从 .claude/settings.json 或 settings.local.json 复制 hooks 对象，因为格式相同。命令通过 stdin 接收 JSON 格式的钩子输入，因此使用 jq 提取文件路径：

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

4. 测试迁移后的插件

   加载插件以验证一切正常：

   claude --plugin-dir ./my-plugin
   

   测试每个组件：运行你的命令，检查代理是否出现在 /agents 中，验证钩子是否正确触发。

迁移时的变化

后续步骤

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

对于插件用户

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

对于插件开发者

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