{/* TRANSLATED — 已翻译为中文 */} > ## 文档索引 > 在此处获取完整文档索引：https://code.claude.com/docs/llms.txt > 使用此文件发现所有可用页面，然后再进一步探索。 # 创建插件 > 创建自定义插件，使用技能、代理、钩子和 MCP 服务器扩展 Claude Code。 插件允许你使用可在项目和团队之间共享的自定义功能扩展 Claude Code。本指南涵盖使用技能、代理、钩子和 MCP 服务器创建自己的插件。 想要安装现有插件？参见[发现和安装插件](/en/discover-plugins)。有关完整技术规范，请参阅[插件参考](/en/plugins-reference)。 ## 何时使用插件与独立配置 Claude Code 支持两种添加自定义技能、代理和钩子的方式： | 方法 | 技能名称 | 最适合 | | :---------------------------------------------------------- | :-------------------- | :---------------------------------------------------------------------------------------------- | | **独立**（`.claude/` 目录） | `/hello` | 个人工作流、项目特定自定义、快速实验 | | **插件**（带 `.claude-plugin/plugin.json` 的目录） | `/plugin-name:hello` | 与队友共享、分发到社区、版本化发布、跨项目复用 | **使用独立配置当**： * 你正在为单个项目自定义 Claude Code * 配置是个人的，不需要共享 * 你正在打包之前试验技能或钩子 * 你想要短技能名称如 `/hello` 或 `/deploy` **使用插件当**： * 你想要与团队或社区共享功能 * 你需要在多个项目中使用相同的技能/代理 * 你想要版本控制和易于更新的扩展 * 你正在通过市场分发 * 你可以接受命名空间技能如 `/my-plugin:hello`（命名空间防止插件之间的冲突） 从 `.claude/` 中的独立配置开始快速迭代，然后在准备好共享时[转换为插件](#convert-existing-configurations-to-plugins)。 ## 快速入门 本快速入门引导你创建带有自定义技能的插件。你将创建清单（定义插件的配置文件）、添加技能，并使用 `--plugin-dir` 标志在本地测试。 ### 前提条件 * Claude Code [已安装并认证](/en/quickstart#step-1-install-claude-code) 如果你看不到 `/plugin` 命令，请将 Claude Code 更新到最新版本。参见[故障排除](/en/troubleshooting)了解升级说明。 ### 创建你的第一个插件 每个插件位于自己的目录中，包含清单和你的技能、代理或钩子。现在创建一个： ```bash theme={null} mkdir my-first-plugin ``` `.claude-plugin/plugin.json` 处的清单文件定义插件的身份：名称、描述和版本。Claude Code 使用此元数据在插件管理器中显示你的插件。 在插件文件夹内创建 `.claude-plugin` 目录： ```bash theme={null} mkdir my-first-plugin/.claude-plugin ``` 然后创建 `my-first-plugin/.claude-plugin/plugin.json`，内容如下： ```json my-first-plugin/.claude-plugin/plugin.json theme={null} { "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，每次提交算作新版本。参见[版本管理](/en/plugins-reference#version-management)。 | | `author` | 可选。有助于归属。 | 有关 `homepage`、`repository` 和 `license` 等附加字段，请参阅[完整清单模式](/en/plugins-reference#plugin-manifest-schema)。 技能位于 `skills/` 目录中。每个技能是包含 `SKILL.md` 文件的文件夹。文件夹名称成为技能名称，以前缀插件的命名空间（名为 `my-first-plugin` 的插件中的 `hello/` 创建 `/my-first-plugin:hello`）。 在插件文件夹中创建技能目录： ```bash theme={null} mkdir -p my-first-plugin/skills/hello ``` 然后创建 `my-first-plugin/skills/hello/SKILL.md`，内容如下： ```markdown my-first-plugin/skills/hello/SKILL.md theme={null} --- 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 以加载你的插件： ```bash theme={null} claude --plugin-dir ./my-first-plugin ``` Claude Code 启动后，尝试你的新技能： ```shell theme={null} /my-first-plugin:hello ``` 你会看到 Claude 以问候语回应。运行 `/help` 查看你的技能列在插件命名空间下。 **为什么需要命名空间？** 插件技能始终使用命名空间（如 `/my-first-plugin:hello`）以防止多个插件具有同名技能时发生冲突。 要更改命名空间前缀，更新 `plugin.json` 中的 `name` 字段。 通过接受用户输入使你的技能动态化。`$ARGUMENTS` 占位符捕获用户在技能名称后提供的任何文本。 更新你的 `SKILL.md` 文件： ```markdown my-first-plugin/skills/hello/SKILL.md theme={null} --- 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` 获取更改，然后用你的名字尝试技能： ```shell theme={null} /my-first-plugin:hello Alex ``` Claude 会用你的名字问候你。有关向技能传递参数的更多信息，请参阅[技能](/en/skills#pass-arguments-to-skills)。 你已成功创建并测试了具有以下关键组件的插件： * **插件清单**（`.claude-plugin/plugin.json`）：描述插件的元数据 * **技能目录**（`skills/`）：包含你的自定义技能 * **技能参数**（`$ARGUMENTS`）：捕获用户输入以实现动态行为 `--plugin-dir` 标志对开发和测试很有用。当你准备好与他人共享插件时，请参阅[创建和分发插件市场](/en/plugin-marketplaces)。 ## 插件结构概览 你已经创建了一个带有技能的插件，但插件可以包含更多：自定义代理、钩子、MCP 服务器、LSP 服务器和后台监控器。 **常见错误**：不要将 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目录内。只有 `plugin.json` 放在 `.claude-plugin/` 内。所有其他目录必须在插件根级别。 | 目录 | 位置 | 用途 | | :---------------- | :--------- | :----------------------------------------------------------------- | | `.claude-plugin/` | 插件根目录 | 包含 `plugin.json` 清单（如果组件使用默认位置则可选） | | `skills/` | 插件根目录 | 技能作为 `/SKILL.md` 目录 | | `commands/` | 插件根目录 | 技能作为平面 Markdown 文件。新插件请使用 `skills/` | | `agents/` | 插件根目录 | 自定义代理定义 | | `hooks/` | 插件根目录 | `hooks.json` 中的事件处理器 | | `.mcp.json` | 插件根目录 | MCP 服务器配置 | | `.lsp.json` | 插件根目录 | 代码智能的 LSP 服务器配置 | | `monitors/` | 插件根目录 | `monitors.json` 中的后台监控器配置 | | `bin/` | 插件根目录 | 插件启用时添加到 Bash 工具 `PATH` 的可执行文件 | | `settings.json` | 插件根目录 | 插件启用时应用的默认[设置](/en/settings) | **后续步骤**：准备添加更多功能？跳转到[开发更复杂的插件](#develop-more-complex-plugins)添加代理、钩子、MCP 服务器和 LSP 服务器。有关所有插件组件的完整技术规范，请参阅[插件参考](/en/plugins-reference)。 ## 开发更复杂的插件 一旦你熟悉了基础插件，就可以创建更复杂的扩展。 ### 向插件添加技能 插件可以包含[代理技能](/en/skills)来扩展 Claude 的能力。技能是模型调用的：Claude 根据任务上下文自动使用它们。 在插件根目录添加 `skills/` 目录，其中包含 `SKILL.md` 文件的技能文件夹： ```text theme={null} my-plugin/ ├── .claude-plugin/ │ └── plugin.json └── skills/ └── code-review/ └── SKILL.md ``` 每个 `SKILL.md` 包含 YAML frontmatter 和说明。包含 `description` 以便 Claude 知道何时使用技能： ```yaml theme={null} --- 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` 加载技能。有关完整的技能编写指导，包括渐进式披露和工具限制，请参阅[代理技能](/en/skills)。 ### 向插件添加 LSP 服务器 对于常见语言如 TypeScript、Python 和 Rust，从官方市场安装预构建的 LSP 插件。仅在需要尚未覆盖的语言支持时创建自定义 LSP 插件。 LSP（语言服务器协议）插件为 Claude 提供实时代码智能。如果你需要支持没有官方 LSP 插件的语言，可以通过向插件添加 `.lsp.json` 文件来创建自己的： ```json .lsp.json theme={null} { "go": { "command": "gopls", "args": ["serve"], "extensionToLanguage": { ".go": "go" } } } ``` 安装你插件的用户必须在其机器上安装语言服务器二进制文件。 有关完整的 LSP 配置选项，请参阅 [LSP 服务器](/en/plugins-reference#lsp-servers)。 ### 向插件添加后台监控器 后台监控器允许你的插件在后台监视日志、文件或外部状态，并在事件到达时通知 Claude。Claude Code 在插件激活时自动启动每个监控器，因此你无需指示 Claude 启动监视。 在插件根目录添加 `monitors/monitors.json` 文件，包含监控器条目数组： ```json monitors/monitors.json theme={null} [ { "name": "error-log", "command": "tail -F ./logs/error.log", "description": "Application error log" } ] ``` `command` 的每个 stdout 行在会话期间作为通知传递给 Claude。有关完整模式，包括 `when` 触发器和变量替换，请参阅[监控器](/en/plugins-reference#monitors)。 ### 为插件提供默认设置 插件可以在插件根目录包含 `settings.json` 文件，在插件启用时应用默认配置。目前仅支持 `agent` 和 `subagentStatusLine` 键。 设置 `agent` 会激活插件的[自定义代理](/en/sub-agents)之一作为主线程，应用其系统提示、工具限制和模型。这允许插件在启用时更改 Claude Code 的默认行为。 ```json settings.json theme={null} { "agent": "security-reviewer" } ``` 此示例激活插件 `agents/` 目录中定义的 `security-reviewer` 代理。`settings.json` 中的设置优先于 `plugin.json` 中声明的 `settings`。未知键被静默忽略。 ### 组织复杂插件 对于具有许多组件的插件，按功能组织目录结构。有关完整的目录布局和组织模式，请参阅[插件目录结构](/en/plugins-reference#plugin-directory-structure)。 ### 在本地测试插件 使用 `--plugin-dir` 标志在开发期间测试插件。这直接加载你的插件，无需安装。 ```bash theme={null} claude --plugin-dir ./my-plugin ``` 该标志也接受插件目录的 `.zip` 归档，需要 Claude Code v2.1.128 或更高版本。 ```bash theme={null} claude --plugin-dir ./my-plugin.zip ``` 当 `--plugin-dir` 插件与已安装的市场插件同名时，本地副本在该会话中优先。这让你无需先卸载即可测试已安装插件的更改。例外是托管设置强制启用或强制禁用的插件：`--plugin-dir` 无法覆盖这些。 当你对插件进行更改时，运行 `/reload-plugins` 无需重启即可获取更新。这会重新加载插件、技能、代理、钩子、插件 MCP 服务器和插件 LSP 服务器。测试你的插件组件： * 使用 `/plugin-name:skill-name` 尝试你的技能 * 检查代理是否出现在 `/agents` 中 * 验证钩子按预期工作 你可以通过多次指定标志一次加载多个插件： ```bash theme={null} claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two ``` 要测试已打包为 `.zip` 归档并托管在 URL 的插件（如 CI 构建产物），改用 `--plugin-url`。Claude Code 在启动时获取归档并仅在该会话中加载它。如果获取失败或归档无效，Claude Code 报告插件加载错误并不带它启动。与任何插件源相同的[信任考虑](/en/discover-plugins#security)适用：仅将此标志指向你控制或信任的归档。 要加载多个插件，为每个 URL 重复标志： ```bash theme={null} claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip ``` 或传递空格分隔的 URL 作为单个引号参数： ```bash theme={null} claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip" ``` ### 调试插件问题 如果你的插件没有按预期工作： 1. **检查结构**：确保你的目录在插件根目录，而不是在 `.claude-plugin/` 内 2. **单独测试组件**：分别检查每个技能、代理和钩子 3. **使用验证和调试工具**：参见[调试和开发工具](/en/plugins-reference#debugging-and-development-tools)了解 CLI 命令和故障排除技术 ### 共享你的插件 当你的插件准备好共享时： 1. **添加文档**：包含带有安装和使用说明的 `README.md` 2. **选择版本控制策略**：决定是设置明确的 `version` 还是依赖 git 提交 SHA。参见[版本管理](/en/plugins-reference#version-management) 3. **创建或使用市场**：通过[插件市场](/en/plugin-marketplaces)分发安装 4. **与他人测试**：在更广泛分发之前让团队成员测试插件 一旦你的插件进入市场，其他人可以使用[发现和安装插件](/en/discover-plugins)中的说明安装它。要保持插件对团队内部使用，在[私有仓库](/en/plugin-marketplaces#private-repositories)中托管市场。 ### 将插件提交到社区市场 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](https://claude.ai/settings/plugins/submit) * **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) 在提交之前在本地运行 `claude plugin validate`。审查管道在每个提交上运行相同的检查，以及自动安全筛选。 经批准的插件在 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目录中固定到特定提交 SHA，当你向仓库推送新提交时 CI 自动更新固定。公共目录每晚从审查管道同步，因此批准和你的插件出现在 `marketplace.json` 之间可能有延迟。要检查你的插件是否可安装，在[社区目录](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)中搜索其名称。 官方市场 `claude-plugins-official` 是单独策划的。Anthropic 自行决定包含哪些插件。没有申请流程，提交表单不会将插件添加到官方市场。 如果 Anthropic 在官方市场中列出你的插件，你的 CLI 可以提示 Claude Code 用户安装它。参见[从你的 CLI 推荐插件](/en/plugin-hints)。 有关完整技术规范、调试技术和分发策略，请参阅[插件参考](/en/plugins-reference)。 ## 将现有配置转换为插件 如果你的 `.claude/` 目录中已有技能或钩子，可以将它们转换为插件以便于共享和分发。 ### 迁移步骤 创建新的插件目录： ```bash theme={null} mkdir -p my-plugin/.claude-plugin ``` 在 `my-plugin/.claude-plugin/plugin.json` 创建清单文件： ```json my-plugin/.claude-plugin/plugin.json theme={null} { "name": "my-plugin", "description": "Migrated from standalone configuration", "version": "1.0.0" } ``` 将现有配置复制到插件目录： ```bash theme={null} # 复制命令 cp -r .claude/commands my-plugin/ # 复制代理（如果有） cp -r .claude/agents my-plugin/ # 复制技能（如果有） cp -r .claude/skills my-plugin/ ``` 如果你的设置中有钩子，创建钩子目录： ```bash theme={null} mkdir my-plugin/hooks ``` 创建 `my-plugin/hooks/hooks.json`，包含你的钩子配置。从 `.claude/settings.json` 或 `settings.local.json` 复制 `hooks` 对象，因为格式相同。命令通过 stdin 接收 JSON 格式的钩子输入，因此使用 `jq` 提取文件路径： ```json my-plugin/hooks/hooks.json theme={null} { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }] } ] } } ``` 加载插件以验证一切正常： ```bash theme={null} claude --plugin-dir ./my-plugin ``` 测试每个组件：运行你的命令，检查代理是否出现在 `/agents` 中，验证钩子是否正确触发。 ### 迁移时的变化 | 独立（`.claude/`） | 插件 | | :------------------------- | :----------------------------- | | 仅在一个项目中可用 | 可通过市场共享 | | `.claude/commands/` 中的文件 | `plugin-name/commands/` 中的文件 | | `settings.json` 中的钩子 | `hooks/hooks.json` 中的钩子 | | 必须手动复制以共享 | 使用 `/plugin install` 安装 | 迁移后，你可以从 `.claude/` 中删除原始文件以避免重复。加载时插件版本将优先。 ## 后续步骤 现在你了解了 Claude Code 的插件系统，以下是不同目标的建议路径： ### 对于插件用户 * [发现和安装插件](/en/discover-plugins)：浏览市场并安装插件 * [配置团队市场](/en/discover-plugins#configure-team-marketplaces)：为你的团队设置仓库级插件 ### 对于插件开发者 * [创建和分发市场](/en/plugin-marketplaces)：打包和共享你的插件 * [插件参考](/en/plugins-reference)：完整技术规范 * 深入了解特定插件组件： * [技能](/en/skills)：技能开发详情 * [子代理](/en/sub-agents)：代理配置和能力 * [钩子](/en/hooks)：事件处理和自动化 * [MCP](/en/mcp)：外部工具集成