{/* TRANSLATED — 已翻译为中文 */}

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

# 插件参考

> Claude Code 插件系统的完整技术参考，包括模式、CLI 命令和组件规范。

<Tip>
  想要安装插件？请参阅[发现和安装插件](/en/discover-plugins)。要创建插件，请参阅[插件](/en/plugins)。要分发插件，请参阅[插件市场](/en/plugin-marketplaces)。
</Tip>

本参考提供 Claude Code 插件系统的完整技术规范，包括组件模式、CLI 命令和开发工具。

**插件**是一个自包含的组件目录，通过自定义功能扩展 Claude Code。插件组件包括技能、代理、hooks、MCP 服务器、LSP 服务器和监视器。

## 插件组件参考

### 技能

插件向 Claude Code 添加技能，创建你或 Claude 可以调用的 `/name` 快捷方式。

**位置**：插件根目录中的 `skills/` 或 `commands/` 目录，或插件根目录中的单个 `SKILL.md` 文件

**文件格式**：技能是包含 `SKILL.md` 的目录；命令是简单的 markdown 文件

**技能结构**：

```text theme={null}
skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md
```

**集成行为**：

* 安装插件时会自动发现技能和命令
* Claude 可以根据任务上下文自动调用它们
* 技能可以在 SKILL.md 旁边包含支持文件

有关完整详情，请参阅[技能](/en/skills)。

### 代理

插件可以为特定任务提供专用子代理，Claude 可以在适当时自动调用。

**位置**：插件根目录中的 `agents/` 目录

**文件格式**：描述代理能力的 Markdown 文件

**代理结构**：

```markdown theme={null}
---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.
```

插件代理支持 `name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background` 和 `isolation` frontmatter 字段。唯一有效的 `isolation` 值是 `"worktree"`。出于安全原因，插件附带的代理不支持 `hooks`、`mcpServers` 和 `permissionMode`。

**集成点**：

* 代理出现在 `/agents` 界面中
* Claude 可以根据任务上下文自动调用代理
* 用户可以手动调用代理
* 插件代理与内置 Claude 代理协同工作

有关完整详情，请参阅[子代理](/en/sub-agents)。

### Hooks

插件可以提供自动响应 Claude Code 事件的事件处理器。

**位置**：插件根目录中的 `hooks/hooks.json`，或内联在 plugin.json 中

**格式**：包含事件匹配器和操作的 JSON 配置

**Hook 配置**：

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}
```

插件 hooks 响应与[用户定义 hooks](/en/hooks) 相同的生命周期事件：

| 事件                 | 触发时机                                                                                                                                          |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SessionStart`        | 会话开始或恢复时                                                                                                                       |
| `Setup`               | 使用 `--init-only` 启动 Claude Code 时，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备工作             |
| `UserPromptSubmit`    | 提交提示词时，在 Claude 处理之前                                                                                                   |
| `UserPromptExpansion` | 用户输入的命令扩展为提示词时，在到达 Claude 之前。可以阻止扩展                                                     |
| `PreToolUse`          | 工具调用执行之前。可以阻止它                                                                                                              |
| `PermissionRequest`   | 权限对话框出现时                                                                                                                       |
| `PermissionDenied`    | 工具调用被自动模式分类器拒绝时。返回 `{retry: true}` 告诉模型可以重试被拒绝的工具调用                     |
| `PostToolUse`         | 工具调用成功后                                                                                                                             |
| `PostToolUseFailure`  | 工具调用失败后                                                                                                                                |
| `PostToolBatch`       | 完整的并行工具调用批次解析后，在下一次模型调用之前                                                                         |
| `Notification`        | Claude Code 发送通知时                                                                                                                  |
| `SubagentStart`       | 子代理生成时                                                                                                                             |
| `SubagentStop`        | 子代理完成时                                                                                                                               |
| `TaskCreated`         | 通过 `TaskCreate` 创建任务时                                                                                                          |
| `TaskCompleted`       | 任务标记为完成时                                                                                                               |
| `Stop`                | Claude 完成响应时                                                                                                                        |
| `StopFailure`         | 由于 API 错误导致轮次结束时。输出和退出代码被忽略                                                                               |
| `TeammateIdle`        | [代理团队](/en/agent-teams)队友即将空闲时                                                                                     |
| `InstructionsLoaded`  | CLAUDE.md 或 `.claude/rules/*.md` 文件加载到上下文时。在会话启动时和会话期间延迟加载文件时触发         |
| `ConfigChange`        | 会话期间配置文件更改时                                                                                                     |
| `CwdChanged`          | 工作目录更改时，例如 Claude 执行 `cd` 命令时。适用于使用 direnv 等工具进行响应式环境管理 |
| `FileChanged`         | 监视的文件在磁盘上更改时。`matcher` 字段指定要监视的文件名                                                            |
| `WorktreeCreate`      | 通过 `--worktree` 或 `isolation: "worktree"` 创建 worktree 时。替换默认的 git 行为                                            |
| `WorktreeRemove`      | 移除 worktree 时，无论是在会话退出时还是子代理完成时                                                                   |
| `PreCompact`          | 上下文压缩之前                                                                                                                              |
| `PostCompact`         | 上下文压缩完成后                                                                                                                     |
| `Elicitation`         | MCP 服务器在工具调用期间请求用户输入时                                                                                              |
| `ElicitationResult`   | 用户响应 MCP 诱导后，在响应发送回服务器之前                                                            |
| `SessionEnd`          | 会话终止时                                                                                                                              |

**Hook 类型**：

* `command`：执行 shell 命令或脚本
* `http`：将事件 JSON 作为 POST 请求发送到 URL
* `mcp_tool`：调用已配置的 [MCP 服务器](/en/mcp)上的工具
* `prompt`：使用 LLM 评估提示词（使用 `$ARGUMENTS` 占位符表示上下文）
* `agent`：运行带有工具的代理验证器，用于复杂的验证任务

### MCP 服务器

插件可以捆绑模型上下文协议（MCP）服务器，将 Claude Code 连接到外部工具和服务。

**位置**：插件根目录中的 `.mcp.json`，或内联在 plugin.json 中

**格式**：标准 MCP 服务器配置

**MCP 服务器配置**：

```json theme={null}
{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}
```

**集成行为**：

* 插件 MCP 服务器在插件启用时自动启动
* 服务器作为标准 MCP 工具出现在 Claude 的工具包中
* 服务器功能与 Claude 现有工具无缝集成
* 插件服务器可以独立于用户 MCP 服务器进行配置

### LSP 服务器

<Tip>
  想要使用 LSP 插件？从官方市场安装：在 `/plugin` Discover 标签页中搜索 "lsp"。本节介绍如何为官方市场未覆盖的语言创建 LSP 插件。
</Tip>

插件可以提供[语言服务器协议](https://microsoft.github.io/language-server-protocol/)（LSP）服务器，为 Claude 在处理代码库时提供实时代码智能。

LSP 集成提供：

* **即时诊断**：Claude 在每次编辑后立即看到错误和警告
* **代码导航**：跳转到定义、查找引用和悬停信息
* **语言感知**：代码符号的类型信息和文档

**位置**：插件根目录中的 `.lsp.json`，或内联在 `plugin.json` 中

**格式**：将语言服务器名称映射到其配置的 JSON 配置

**`.lsp.json` 文件格式**：

```json theme={null}
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
```

**内联在 `plugin.json` 中**：

```json theme={null}
{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}
```

**必填字段：**

| 字段                 | 描述                                  |
| :-------------------- | :------------------------------------------- |
| `command`             | 要执行的 LSP 二进制文件（必须在 PATH 中）  |
| `extensionToLanguage` | 将文件扩展名映射到语言标识符 |

**可选字段：**

| 字段                   | 描述                                               |
| :---------------------- | :-------------------------------------------------------- |
| `args`                  | LSP 服务器的命令行参数                 |
| `transport`             | 通信传输：`stdio`（默认）或 `socket`    |
| `env`                   | 启动服务器时设置的环境变量     |
| `initializationOptions` | 初始化期间传递给服务器的选项        |
| `settings`              | 通过 `workspace/didChangeConfiguration` 传递的设置    |
| `workspaceFolder`       | 服务器的工作区文件夹路径                      |
| `startupTimeout`        | 等待服务器启动的最长时间（毫秒）        |
| `shutdownTimeout`       | 等待优雅关闭的最长时间（毫秒）     |
| `restartOnCrash`        | 崩溃时是否自动重启服务器 |
| `maxRestarts`           | 放弃前的最大重启尝试次数       |

<Warning>
  **你必须单独安装语言服务器二进制文件。** LSP 插件配置 Claude Code 如何连接到语言服务器，但不包含服务器本身。如果你在 `/plugin` Errors 标签页中看到 `Executable not found in $PATH`，请为你的语言安装所需的二进制文件。
</Warning>

**可用的 LSP 插件：**

| 插件              | 语言服务器            | 安装命令                                                                            |
| :------------------ | :------------------------- | :----------------------------------------------------------------------------------------- |
| `pyright-lsp`       | Pyright (Python)           | `pip install pyright` 或 `npm install -g pyright`                                          |
| `typescript-lsp`    | TypeScript Language Server | `npm install -g typescript-language-server typescript`                                     |
| `rust-analyzer-lsp` | rust-analyzer              | [参阅 rust-analyzer 安装](https://rust-analyzer.github.io/manual.html#installation) |

先安装语言服务器，然后从市场安装插件。

### 监视器

插件可以声明后台监视器，Claude Code 在插件活动时自动启动。每个监视器在会话生命周期内运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，因此 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视。

插件监视器使用与[监视器工具](/en/tools-reference#monitor-tool)相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，以与 [hooks](#hooks) 相同的信任级别在非沙箱环境中运行，并在监视器工具不可用的主机上被跳过。

<Note>
  插件监视器需要 Claude Code v2.1.105 或更高版本。
</Note>

**位置**：插件根目录中的 `monitors/monitors.json`，或内联在 `plugin.json` 中

**格式**：监视器条目的 JSON 数组

以下 `monitors/monitors.json` 监视部署状态端点和本地错误日志：

```json theme={null}
[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]
```

要内联声明监视器，将 `plugin.json` 中的 `experimental.monitors` 设置为相同的数组。要从非默认路径加载，将 `experimental.monitors` 设置为相对路径字符串，如 `"./config/monitors.json"`。监视器是[实验性组件](#experimental-components)。

**必填字段：**

| 字段         | 描述                                                                                                           |
| :------------ | :-------------------------------------------------------------------------------------------------------------------- |
| `name`        | 插件内唯一的标识符。防止插件重新加载或再次调用技能时出现重复进程 |
| `command`     | 作为持久后台进程在会话工作目录中运行的 shell 命令                                 |
| `description` | 正在监视的内容的简短摘要。显示在任务面板和通知摘要中                         |

**可选字段：**

| 字段  | 描述                                                                                                                                                                                                              |
| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `when` | 控制监视器何时启动。`"always"` 在会话启动时和插件重新加载时启动，这是默认值。`"on-skill-invoke:<skill-name>"` 在首次调度此插件中的命名技能时启动 |

`command` 值支持与 MCP 和 LSP 服务器配置相同的[变量替换](#environment-variables)：`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${CLAUDE_PROJECT_DIR}`、`${user_config.*}` 以及环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自身的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

在会话中禁用插件不会停止已经运行的监视器。它们在会话结束时停止。

### 主题

插件可以附带颜色主题，这些主题与内置预设和用户的本地主题一起出现在 `/theme` 中。主题是 `themes/` 中的 JSON 文件，包含 `base` 预设和稀疏的 `overrides` 颜色令牌映射。主题是[实验性组件](#experimental-components)。

```json theme={null}
{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}
```

选择插件主题会在用户配置中持久化 `custom:<plugin-name>:<slug>`。插件主题是只读的；在 `/theme` 中按 `Ctrl+E` 会将其复制到 `~/.claude/themes/`，以便用户可以编辑副本。

***

## 插件安装范围

安装插件时，你选择一个**范围**，决定插件在哪里可用以及谁可以使用它：

| 范围     | 设置文件                                   | 用例                                                 |
| :-------- | :---------------------------------------------- | :------------------------------------------------------- |
| `user`    | `~/.claude/settings.json`                       | 跨所有项目可用的个人插件（默认） |
| `project` | `.claude/settings.json`                         | 通过版本控制共享的团队插件                  |
| `local`   | `.claude/settings.local.json`                   | 项目特定插件，已添加到 gitignore                     |
| `managed` | [托管设置](/en/settings#settings-files) | 托管插件（只读，仅更新）                 |

插件使用与其他 Claude Code 配置相同的范围系统。有关安装说明和范围标志，请参阅[安装插件](/en/discover-plugins#install-plugins)。有关范围的完整说明，请参阅[配置范围](/en/settings#configuration-scopes)。

***

## 插件清单模式

`.claude-plugin/plugin.json` 文件定义插件的元数据和配置。本节介绍所有支持的字段和选项。

清单是可选的。如果省略，Claude Code 会在[默认位置](#file-locations-reference)自动发现组件，并从目录名称派生插件名称。当你需要提供元数据或自定义组件路径时使用清单。

### 完整模式

```json theme={null}
{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
```

### 必填字段

如果你包含清单，`name` 是唯一的必填字段。

| 字段  | 类型   | 描述                               | 示例              |
| :----- | :----- | :---------------------------------------- | :------------------- |
| `name` | string | 唯一标识符（kebab-case，无空格） | `"deployment-tools"` |

此名称用于组件的命名空间。例如，在 UI 中，名为 `plugin-dev` 的插件的代理 `agent-creator` 将显示为 `plugin-dev:agent-creator`。

### 未识别的字段

Claude Code 会忽略它不识别的顶层字段。你可以在 `plugin.json` 中保留来自其他生态系统的元数据，插件仍然会加载。这使得维护一个同时充当 VS Code 或 Cursor 扩展清单、npm `package.json` 或 MCPB/DXT 包清单的清单变得实用。

`claude plugin validate` 将未识别的字段报告为警告而非错误。如果某个字段与已识别字段相差一两个字符，警告会建议可能的正确名称。只有未识别字段警告的插件仍然通过验证并在运行时加载。

类型错误的字段仍然会导致失败。例如，`keywords` 值是字符串而不是数组就是加载错误，`claude plugin validate` 会将其报告为错误。

传递 `--strict` 将警告视为错误。在 CI 中使用它可以在发布前捕获拼写错误的字段名或来自其他工具清单的遗留字段，即使插件在运行时会加载。

```bash theme={null}
claude plugin validate ./my-plugin --strict
```

### 元数据字段

| 字段         | 类型   | 描述                                                                                                                                                                                                                                                                                                                                      | 示例                                                           |
| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
| `$schema`     | string | 用于编辑器自动完成和验证的 JSON Schema URL。Claude Code 在加载时忽略此字段。                                                                                                                                                                                                                                             | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
| `displayName` | string | {/* min-version: 2.1.143 */}在 `/plugin` 选择器和其他 UI 界面中显示的人类可读名称。省略时回退到 `name`。与 `name` 不同，可以包含空格和任何大小写。不用于命名空间或查找。需要 Claude Code v2.1.143 或更高版本。                                                                            | `"Deployment Tools"`                                              |
| `version`     | string | 可选。语义版本。设置此项会将插件固定到该版本字符串，因此用户仅在你更新时才会收到更新。如果省略，Claude Code 回退到 git commit SHA，因此每次提交都被视为新版本。如果在市场条目中也设置了，`plugin.json` 优先。参阅[版本管理](#version-management)。 | `"2.1.0"`                                                         |
| `description` | string | 插件用途的简要说明                                                                                                                                                                                                                                                                                                              | `"Deployment automation tools"`                                   |
| `author`      | object | 作者信息                                                                                                                                                                                                                                                                                                                               | `{"name": "Dev Team", "email": "dev@company.com"}`                |
| `homepage`    | string | 文档 URL                                                                                                                                                                                                                                                                                                                                | `"https://docs.example.com"`                                      |
| `repository`  | string | 源代码 URL                                                                                                                                                                                                                                                                                                                                  | `"https://github.com/user/plugin"`                                |
| `license`     | string | 许可证标识符                                                                                                                                                                                                                                                                                                                               | `"MIT"`, `"Apache-2.0"`                                           |
| `keywords`    | array  | 发现标签                                                                                                                                                                                                                                                                                                                                   | `["deployment", "ci-cd"]`                                         |

### 组件路径字段

| 字段                   | 类型                  | 描述                                                                                                                                               | 示例                                              |
| :---------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `skills`                | string\|array         | 包含 `<name>/SKILL.md` 的自定义技能目录（除默认 `skills/` 外）                                                                  | `"./custom/skills/"`                                 |
| `commands`              | string\|array         | 自定义扁平 `.md` 技能文件或目录（替换默认 `commands/`）                                                                               | `"./custom/cmd.md"` 或 `["./cmd1.md"]`               |
| `agents`                | string\|array         | 自定义代理文件（替换默认 `agents/`）                                                                                                           | `"./custom/agents/reviewer.md"`                      |
| `hooks`                 | string\|array\|object | Hook 配置路径或内联配置                                                                                                                        | `"./my-extra-hooks.json"`                            |
| `mcpServers`            | string\|array\|object | MCP 配置路径或内联配置                                                                                                                         | `"./my-extra-mcp-config.json"`                       |
| `outputStyles`          | string\|array         | 自定义输出样式文件/目录（替换默认 `output-styles/`）                                                                                 | `"./styles/"`                                        |
| `lspServers`            | string\|array\|object | [语言服务器协议](https://microsoft.github.io/language-server-protocol/)配置，用于代码智能（跳转到定义、查找引用等） | `"./.lsp.json"`                                      |
| `experimental.themes`   | string\|array         | 颜色主题文件/目录（替换默认 `themes/`）。参阅[主题](#themes)                                                                         | `"./themes/"`                                        |
| `experimental.monitors` | string\|array         | 插件活动时自动启动的后台[监视器](/en/tools-reference#monitor-tool)配置。参阅[监视器](#monitors)       | `"./monitors.json"`                                  |
| `userConfig`            | object                | 启用时提示用户配置的可配置值。参阅[用户配置](#user-configuration)                                                           | 见下文                                            |
| `channels`              | array                 | 用于消息注入的通道声明（Telegram、Slack、Discord 风格）。参阅[通道](#channels)                                                    | 见下文                                            |
| `dependencies`          | array                 | 此插件所需的其他插件，可选带 semver 版本约束。参阅[约束插件依赖版本](/en/plugin-dependencies)       | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

### 实验性组件

`experimental` 键下的组件（`themes` 和 `monitors`）的清单模式可能在版本之间发生变化，因为它们仍在稳定中。你在哪里声明它们是单独的迁移：顶层仍然有效，`claude plugin validate` 会发出警告，未来的版本将要求使用 `experimental.*`。

### 用户配置

`userConfig` 字段声明 Claude Code 在启用插件时提示用户输入的值。使用此选项代替要求用户手动编辑 `settings.json`。

```json theme={null}
{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}
```

键必须是有效的标识符。每个选项支持以下字段：

| 字段         | 必填 | 描述                                                                              |
| :------------ | :------- | :--------------------------------------------------------------------------------------- |
| `type`        | 是      | `string`、`number`、`boolean`、`directory` 或 `file` 之一                             |
| `title`       | 是      | 配置对话框中显示的标签                                                  |
| `description` | 是      | 字段下方显示的帮助文本                                                        |
| `sensitive`   | 否       | 如果为 `true`，则屏蔽输入并将值存储在安全存储中而非 `settings.json` |
| `required`    | 否       | 如果为 `true`，字段为空时验证失败                                      |
| `default`     | 否       | 用户未提供时使用的值                                                |
| `multiple`    | 否       | 对于 `string` 类型，允许字符串数组                                             |
| `min` / `max` | 否       | `number` 类型的边界                                                                 |

每个值都可以作为 `${user_config.KEY}` 在 MCP 和 LSP 服务器配置、hook 命令和监视器命令中替换。非敏感值也可以在技能和代理内容中替换。所有值都作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量导出到插件子进程。

非敏感值存储在 `settings.json` 的 `pluginConfigs[<plugin-id>].options` 下。敏感值存储在系统钥匙串中（在钥匙串不可用时存储在 `~/.claude/.credentials.json` 中）。钥匙串存储与 OAuth 令牌共享，总限制约为 2 KB，因此请保持敏感值较小。

### 通道

`channels` 字段允许插件声明一个或多个将内容注入对话的消息通道。每个通道绑定到插件提供的 MCP 服务器。

```json theme={null}
{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}
```

`server` 字段是必填的，必须与插件的 `mcpServers` 中的键匹配。可选的每通道 `userConfig` 使用与顶层字段相同的模式，允许插件在启用时提示输入 bot 令牌或所有者 ID。

### 路径行为规则

自定义路径是替换还是扩展插件的默认目录取决于字段：

* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认的 `commands/` 目录。要保留默认值并添加更多，请明确列出：`"commands": ["./commands/", "./extras/"]`
* **添加到默认值**：`skills`。默认的 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载
* **有自己的合并规则**：[hooks](#hooks)、[MCP 服务器](#mcp-servers)和 [LSP 服务器](#lsp-servers)。参阅各节了解多个源如何组合

当插件同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本会在 `/doctor`、`claude plugin list` 和 `/plugin` 详情视图中标记被忽略的文件夹。插件仍然使用清单路径加载。当清单键指向默认文件夹内时，例如 `"commands": ["./commands/deploy.md"]`，不会显示警告，因为在这种情况下文件夹被显式引用。

对于所有路径字段：

* 所有路径必须相对于插件根目录并以 `./` 开头
* 自定义路径中的组件使用相同的命名和命名空间规则
* 多个路径可以指定为数组
* 当技能路径指向直接包含 `SKILL.md` 的目录时，例如 `"skills": ["./"]` 指向插件根目录，SKILL.md 中的 frontmatter `name` 字段决定技能的调用名称。这提供了稳定的名称，与安装目录无关。如果 frontmatter 中未设置 `name`，则使用目录基名作为回退。

在插件根目录有 `SKILL.md`、没有 `skills/` 子目录且没有 `skills` 清单字段的插件在 Claude Code v2.1.142 及更高版本中会自动作为单技能插件加载。你不需要为此布局在 `plugin.json` 中设置 `"skills": ["./"]`。技能的调用名称遵循与上述相同的规则：frontmatter `name` 字段，或目录基名作为回退。

**路径示例**：

```json theme={null}
{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}
```

### 环境变量

Claude Code 提供三个变量用于引用路径。所有变量都在技能内容、代理内容、hook 命令、监视器命令以及 MCP 或 LSP 服务器配置中出现的任何位置内联替换。所有变量也作为环境变量导出到 hook 进程和 MCP 或 LSP 服务器子进程。

**`${CLAUDE_PLUGIN_ROOT}`**：插件安装目录的绝对路径。使用此路径引用与插件捆绑的脚本、二进制文件和配置文件。在 hook 命令中，使用带有 `args` 的 [exec 形式](/en/hooks#exec-form-and-shell-form)，以便路径作为单个参数传递，无需引号。在 shell 形式的 hooks 和监视器命令中，用双引号包装，如 `"${CLAUDE_PLUGIN_ROOT}"`。此路径在插件更新时会更改。前一版本的目录在更新后大约七天内保留在磁盘上，然后才会被清理，但请将其视为临时性的，不要在此处写入状态。

当插件在会话中更新时，hook 命令、监视器、MCP 服务器和 LSP 服务器继续使用前一版本的路径。运行 `/reload-plugins` 将 hooks、MCP 服务器和 LSP 服务器切换到新路径；监视器需要重新启动会话。

**`${CLAUDE_PLUGIN_DATA}`**：用于在更新中保留的插件状态的持久目录。使用此目录存储已安装的依赖项（如 `node_modules` 或 Python 虚拟环境）、生成的代码、缓存以及应跨插件版本保留的任何其他文件。此变量首次被引用时会自动创建目录。

**`${CLAUDE_PROJECT_DIR}`**：项目根目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。使用此路径引用项目本地脚本或配置文件。用引号包装以处理带空格的路径，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。MCP 服务器也可以调用 MCP `roots/list` 请求，该请求返回 Claude Code 启动时的目录。

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}
```

#### 持久数据目录

`${CLAUDE_PLUGIN_DATA}` 目录解析为 `~/.claude/plugins/data/{id}/`，其中 `{id}` 是插件标识符，`a-z`、`A-Z`、`0-9`、`_` 和 `-` 之外的字符被替换为 `-`。对于安装为 `formatter@my-marketplace` 的插件，目录为 `~/.claude/plugins/data/formatter-my-marketplace/`。

常见用途是一次性安装语言依赖项，并在会话和插件更新之间重用它们。由于数据目录比任何单个插件版本都持久存在，仅检查目录存在无法检测更新何时更改了插件的依赖清单。推荐的模式是将捆绑的清单与数据目录中的副本进行比较，并在不同时重新安装。

此 `SessionStart` hook 在首次运行时安装 `node_modules`，并在插件更新包含更改的 `package.json` 时再次安装：

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}
```

当存储的副本缺失或与捆绑的副本不同时，`diff` 以非零值退出，涵盖首次运行和更改依赖项的更新。如果 `npm install` 失败，尾部的 `rm` 会移除复制的清单，以便下次会话重试。

捆绑在 `${CLAUDE_PLUGIN_ROOT}` 中的脚本可以针对持久化的 `node_modules` 运行：

```json theme={null}
{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}
```

当你从最后安装的范围卸载插件时，数据目录会自动删除。`/plugin` 界面会显示目录大小并在删除前提示。CLI 默认删除；传递 [`--keep-data`](#plugin-uninstall) 以保留它。

***

## 插件缓存和文件解析

插件通过两种方式之一指定：

* 通过 `claude --plugin-dir` 或 `claude --plugin-url`，仅在会话期间有效。
* 通过市场，安装供未来会话使用。

出于安全和验证目的，Claude Code 将*市场*插件复制到用户的本地**插件缓存**（`~/.claude/plugins/cache`）而不是就地使用。在开发引用外部文件的插件时，理解此行为很重要。

每个已安装的版本是缓存中的单独目录。当你更新或卸载插件时，前一版本目录被标记为孤立，并在 7 天后自动删除。宽限期让已经加载旧版本的并发 Claude Code 会话可以继续运行而不会出错。

Claude 的 Glob 和 Grep 工具在搜索时会跳过孤立的版本目录，因此文件结果不包含过时的插件代码。

### 路径遍历限制

已安装的插件无法引用其目录外的文件。遍历插件根目录外的路径（如 `../shared-utils`）在安装后将不起作用，因为这些外部文件不会被复制到缓存中。

### 使用符号链接在市场内共享文件

如果你的插件需要与同一市场的其他部分共享文件，可以在插件目录内创建符号链接。当插件被复制到缓存时，符号链接的处理方式取决于其目标解析的位置：

* **在插件自身的目录内：** 符号链接作为相对符号链接保留在缓存中，因此它在运行时继续解析到复制的目标。
* **在同一市场内的其他位置：** 符号链接被解引用。目标内容被复制到缓存中替换它。这允许元插件的 `skills/` 目录链接到市场中其他插件定义的技能。
* **在市场外部：** 符号链接因安全原因被跳过。这防止插件将任意主机文件（如系统路径）拉入缓存。

对于使用 `--plugin-dir` 或从本地路径安装的插件，只有解析在插件自身目录内的符号链接才会被保留。所有其他符号链接都被跳过。

以下命令从市场插件内部创建指向兄弟插件定义的共享技能的链接。在 Windows 上，使用提升权限的命令提示符中的 `mklink /D` 或启用开发者模式：

```bash theme={null}
ln -s ../../shared-plugin/skills/foo ./skills/foo
```

这在维护缓存系统安全优势的同时提供了灵活性。

***

## 插件目录结构

### 标准插件布局

完整的插件遵循此结构：

```text theme={null}
enterprise-plugin/
├── .claude-plugin/           # Metadata directory (optional)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills as flat .md files
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Output style definitions
│   └── terse.md
├── themes/                   # Color theme definitions
│   └── dracula.json
├── monitors/                 # Background monitor configurations
│   └── monitors.json
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── bin/                      # Plugin executables added to PATH
│   └── my-tool               # Invokable as bare command in Bash tool
├── settings.json            # Default settings for the plugin
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history
```

<Warning>
  `.claude-plugin/` 目录包含 `plugin.json` 文件。所有其他目录（commands/、agents/、skills/、output-styles/、themes/、monitors/、hooks/）必须位于插件根目录，而不是在 `.claude-plugin/` 内。
</Warning>

插件根目录的 `CLAUDE.md` 文件不会作为项目上下文加载。插件通过技能、代理和 hooks 而不是 CLAUDE.md 来贡献上下文。要附带加载到 Claude 上下文中的说明，请将它们放在[技能](#skills)中。

### 文件位置参考

| 组件         | 默认位置             | 用途                                                                                                                                                                                    |
| :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **清单**      | `.claude-plugin/plugin.json` | 插件元数据和配置（可选）                                                                                                                                               |
| **技能**        | `skills/`                    | 具有 `<name>/SKILL.md` 结构的技能                                                                                                                                                    |
| **命令**      | `commands/`                  | 作为扁平 Markdown 文件的技能。新插件请使用 `skills/`                                                                                                                               |
| **代理**        | `agents/`                    | 子代理 Markdown 文件                                                                                                                                                                    |
| **输出样式** | `output-styles/`             | 输出样式定义                                                                                                                                                                   |
| **主题**        | `themes/`                    | 颜色主题定义                                                                                                                                                                    |
| **Hooks**         | `hooks/hooks.json`           | Hook 配置                                                                                                                                                                         |
| **MCP 服务器**   | `.mcp.json`                  | MCP 服务器定义                                                                                                                                                                     |
| **LSP 服务器**   | `.lsp.json`                  | 语言服务器配置                                                                                                                                                             |
| **监视器**      | `monitors/monitors.json`     | 后台监视器配置                                                                                                                                                          |
| **可执行文件**   | `bin/`                       | 添加到 Bash 工具 `PATH` 的可执行文件。插件启用时，此处的文件可作为裸命令在任何 Bash 工具调用中调用                                                   |
| **设置**      | `settings.json`              | 插件启用时应用的默认配置。目前仅支持 [`agent`](/en/sub-agents) 和 [`subagentStatusLine`](/en/statusline#subagent-status-lines) 键 |

***

## CLI 命令参考

Claude Code 提供用于非交互式插件管理的 CLI 命令，适用于脚本和自动化。

### plugin install

从可用市场安装插件。

```bash theme={null}
claude plugin install <plugin> [options]
```

**参数：**

* `<plugin>`：插件名称或 `plugin-name@marketplace-name` 用于特定市场

**选项：**

| 选项                | 描述                                       | 默认值 |
| :-------------------- | :------------------------------------------------ | :------ |
| `-s, --scope <scope>` | 安装范围：`user`、`project` 或 `local` | `user`  |
| `-h, --help`          | 显示命令帮助                          |         |

范围决定已安装插件添加到哪个设置文件。例如，`--scope project` 写入 .claude/settings.json 中的 `enabledPlugins`，使插件对克隆项目仓库的每个人可用。

**示例：**

```bash theme={null}
# Install to user scope (default)
claude plugin install formatter@my-marketplace

# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project

# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local
```

### plugin uninstall

移除已安装的插件。

```bash theme={null}
claude plugin uninstall <plugin> [options]
```

**参数：**

* `<plugin>`：插件名称或 `plugin-name@marketplace-name`

**选项：**

| 选项                | 描述                                                                                              | 默认值 |
| :-------------------- | :------------------------------------------------------------------------------------------------------- | :------ |
| `-s, --scope <scope>` | 从范围卸载：`user`、`project` 或 `local`                                                      | `user`  |
| `--keep-data`         | 保留插件的[持久数据目录](#persistent-data-directory)                            |         |
| `--prune`             | 同时移除没有其他插件需要的自动安装依赖项。参阅 [plugin prune](#plugin-prune) |         |
| `-y, --yes`           | 跳过 `--prune` 确认提示。当 stdin 或 stdout 不是 TTY 时必需                       |         |
| `-h, --help`          | 显示命令帮助                                                                                 |         |

**别名：**`remove`、`rm`

默认情况下，从最后剩余的范围卸载也会删除插件的 `${CLAUDE_PLUGIN_DATA}` 目录。使用 `--keep-data` 保留它，例如在测试新版本后重新安装时。

### plugin prune

移除不再被任何已安装插件需要的自动安装插件依赖项。Claude Code 为满足另一个插件的 [`dependencies`](/en/plugin-dependencies) 字段而拉入的依赖项会被移除；你直接安装的插件永远不会被触及。

```bash theme={null}
claude plugin prune [options]
```

**选项：**

| 选项                | 描述                                                              | 默认值 |
| :-------------------- | :----------------------------------------------------------------------- | :------ |
| `-s, --scope <scope>` | 在范围修剪：`user`、`project` 或 `local`                            | `user`  |
| `--dry-run`           | 列出将被移除的内容而不实际移除                     |         |
| `-y, --yes`           | 跳过确认提示。当 stdin 或 stdout 不是 TTY 时必需 |         |
| `-h, --help`          | 显示命令帮助                                                 |         |

**别名：**`autoremove`

该命令列出孤立的依赖项，并在移除前请求确认。要一步移除插件并清理其依赖项，运行 `claude plugin uninstall <plugin> --prune`。

<Note>
  `claude plugin prune` 需要 Claude Code v2.1.121 或更高版本。
</Note>

### plugin enable

启用已禁用的插件。如果插件声明了[依赖项](/en/plugin-dependencies)，Claude Code 会在相同范围传递性地启用它们，当依赖项未安装时命令会失败。

```bash theme={null}
claude plugin enable <plugin> [options]
```

**参数：**

* `<plugin>`：插件名称或 `plugin-name@marketplace-name`

**选项：**

| 选项                | 描述                                    | 默认值 |
| :-------------------- | :--------------------------------------------- | :------ |
| `-s, --scope <scope>` | 要启用的范围：`user`、`project` 或 `local` | `user`  |
| `-h, --help`          | 显示命令帮助                       |         |

### plugin disable

禁用插件而不卸载它。当另一个已启用的插件[依赖于](/en/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)目标时会失败。错误消息包含一个链式命令，先禁用每个依赖项。

```bash theme={null}
claude plugin disable <plugin> [options]
```

**参数：**

* `<plugin>`：插件名称或 `plugin-name@marketplace-name`

**选项：**

| 选项                | 描述                                     | 默认值 |
| :-------------------- | :---------------------------------------------- | :------ |
| `-s, --scope <scope>` | 要禁用的范围：`user`、`project` 或 `local` | `user`  |
| `-h, --help`          | 显示命令帮助                        |         |

### plugin update

将插件更新到最新版本。

```bash theme={null}
claude plugin update <plugin> [options]
```

**参数：**

* `<plugin>`：插件名称或 `plugin-name@marketplace-name`

**选项：**

| 选项                | 描述                                               | 默认值 |
| :-------------------- | :-------------------------------------------------------- | :------ |
| `-s, --scope <scope>` | 要更新的范围：`user`、`project`、`local` 或 `managed` | `user`  |
| `-h, --help`          | 显示命令帮助                                  |         |

***

### plugin list

列出已安装的插件及其版本、源市场和启用状态。

```bash theme={null}
claude plugin list [options]
```

**选项：**

| 选项        | 描述                                                    | 默认值 |
| :------------ | :------------------------------------------------------------- | :------ |
| `--json`      | 以 JSON 格式输出                                                 |         |
| `--available` | 包含市场中可用的插件。需要 `--json` |         |
| `-h, --help`  | 显示命令帮助                                       |         |

### plugin details

显示插件的组件清单和预计 token 成本。输出列出插件贡献的所有组件，按技能、代理、Hooks、MCP 服务器和 LSP 服务器分组，以及它为每个会话添加的 token 估计量。技能组包括 `skills/` 和 `commands/` 条目。

```bash theme={null}
claude plugin details <name>
```

**参数：**

* `<name>`：插件名称或 `plugin-name@marketplace-name`

**选项：**

| 选项       | 描述              | 默认值 |
| :----------- | :----------------------- | :------ |
| `-h, --help` | 显示命令帮助 |         |

输出显示每个组件的两个成本数字：

* **常驻：** 无论任何组件是否触发，插件的列表文本（如技能描述、代理描述和命令名称）为每个会话添加的 token。
* **调用时：** 组件触发时消耗的 token。按组件显示，而非插件总计，因为典型会话仅调用组件的子集。

此示例显示具有两个技能的插件的输出：

```
dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.
```

常驻总计通过活动模型的 `count_tokens` API 计算。每组件数字从该总计按比例缩放。如果 API 不可达，命令会回退到基于字符的估计。

### plugin tag

为当前目录中的插件创建发布 git 标签。从插件文件夹内运行。参阅[标记插件发布](/en/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

```bash theme={null}
claude plugin tag [options]
```

**选项：**

| 选项        | 描述                                                                | 默认值 |
| :------------ | :------------------------------------------------------------------------- | :------ |
| `--push`      | 创建后将标签推送到远程                               |         |
| `--dry-run`   | 打印将被标记的内容而不实际创建标签                        |         |
| `-f, --force` | 即使工作树脏或标签已存在也创建标签 |         |
| `-h, --help`  | 显示命令帮助                                                   |         |

***

## 调试和开发工具

### 调试命令

使用 `claude --debug` 查看插件加载详情：

这会显示：

* 正在加载哪些插件
* 插件清单中的任何错误
* 技能、代理和 hook 注册
* MCP 服务器初始化

### 常见问题

| 问题                               | 原因                           | 解决方案                                                                                                                                                        |
| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 插件未加载                  | 无效的 `plugin.json`           | 运行 `claude plugin validate` 或 `/plugin validate` 检查 `plugin.json`、skill/agent/command frontmatter 和 `hooks/hooks.json` 的语法和模式错误 |
| 技能未出现                | 错误的目录结构       | 确保 `skills/` 或 `commands/` 在插件根目录，而不是在 `.claude-plugin/` 内                                                                             |
| Hooks 未触发                    | 脚本不可执行           | 运行 `chmod +x script.sh`                                                                                                                                        |
| MCP 服务器失败                    | 缺少 `${CLAUDE_PLUGIN_ROOT}` | 对所有插件路径使用变量                                                                                                                               |
| 路径错误                         | 使用了绝对路径             | 所有路径必须是相对路径并以 `./` 开头                                                                                                                  |
| LSP `Executable not found in $PATH` | 未安装语言服务器   | 安装二进制文件（例如 `npm install -g typescript-language-server typescript`）                                                                               |

### 示例错误消息

**清单验证错误**：

* `Invalid JSON syntax: Unexpected token } in JSON at position 142`：检查缺少的逗号、多余的逗号或未引用的字符串
* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`：缺少必填字段
* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`：JSON 语法错误

**插件加载错误**：

* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`：命令路径存在但不包含有效的命令文件
* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`：marketplace.json 中的 `source` 路径指向不存在的目录
* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`：移除重复的组件定义或移除市场条目中的 `strict: false`

### Hook 故障排除

**Hook 脚本未执行**：

1. 检查脚本是否可执行：`chmod +x ./scripts/your-script.sh`
2. 验证 shebang 行：第一行应为 `#!/bin/bash` 或 `#!/usr/bin/env bash`
3. 检查路径是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
4. 手动测试脚本：`./scripts/your-script.sh`

**Hook 未在预期事件上触发**：

1. 验证事件名称是否正确（区分大小写）：`PostToolUse`，而非 `postToolUse`
2. 检查匹配器模式是否匹配你的工具：`"matcher": "Write|Edit"` 用于文件操作
3. 确认 hook 类型有效：`command`、`http`、`mcp_tool`、`prompt` 或 `agent`

### MCP 服务器故障排除

**服务器未启动**：

1. 检查命令是否存在且可执行
2. 验证所有路径使用 `${CLAUDE_PLUGIN_ROOT}` 变量
3. 检查 MCP 服务器日志：`claude --debug` 显示初始化错误
4. 在 Claude Code 外部手动测试服务器

**服务器工具未出现**：

1. 确保服务器在 `.mcp.json` 或 `plugin.json` 中正确配置
2. 验证服务器正确实现了 MCP 协议
3. 检查调试输出中的连接超时

### 目录结构错误

**症状**：插件加载但组件（技能、代理、hooks）缺失。

**正确结构**：组件必须在插件根目录，而不是在 `.claude-plugin/` 内。只有 `plugin.json` 属于 `.claude-plugin/`。

```text theme={null}
my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Only manifest here
├── commands/            ← At root level
├── agents/              ← At root level
└── hooks/               ← At root level
```

如果你的组件在 `.claude-plugin/` 内，请将它们移到插件根目录。

**调试清单**：

1. 运行 `claude --debug` 并查找 "loading plugin" 消息
2. 检查每个组件目录是否在调试输出中列出
3. 验证文件权限允许读取插件文件

***

## 分发和版本控制参考

### 版本管理

Claude Code 使用插件的版本作为缓存键，决定是否有可用更新。当你运行 `/plugin update` 或自动更新触发时，Claude Code 计算当前版本，如果与已安装的匹配则跳过更新。

版本从以下设置的第一个解析：

1. 插件 `plugin.json` 中的 `version` 字段
2. 插件在 `marketplace.json` 中的市场条目的 `version` 字段
3. 插件源的 git commit SHA，适用于 git 托管市场中的 `github`、`url`、`git-subdir` 和相对路径源
4. `unknown`，适用于 `npm` 源或不在 git 仓库中的本地目录

这为你提供了两种版本化插件的方式：

| 方法               | 方式                                                              | 更新行为                                                                                                                                                      | 最佳用途                                          |
| :--------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
| **显式版本**   | 在 `plugin.json` 中设置 `"version": "2.1.0"`                        | 仅当你更新此字段时用户才会收到更新。推送新提交而不更新它没有效果，`/plugin update` 报告"already at the latest version"。 | 具有稳定发布周期的已发布插件      |
| **Commit-SHA 版本** | 从 `plugin.json` 和市场条目中省略 `version` | 用户在每次对插件 git 源的新提交时收到更新                                                                                                     | 积极开发中的内部或团队插件 |

<Warning>
  如果你在 `plugin.json` 中设置了 `version`，每次你想让用户收到更改时都必须更新它。仅推送新提交是不够的，因为 Claude Code 看到相同的版本字符串并保留缓存副本。如果你在快速迭代，请不设置 `version`，以便使用 git commit SHA。
</Warning>

如果你使用显式版本，请遵循[语义版本控制](https://semver.org)（`MAJOR.MINOR.PATCH`）：破坏性更改更新 MAJOR，新功能更新 MINOR，错误修复更新 PATCH。在 `CHANGELOG.md` 中记录更改。

***

## 另请参阅

* [插件](/en/plugins) - 教程和实际用法
* [插件市场](/en/plugin-marketplaces) - 创建和管理市场
* [技能](/en/skills) - 技能开发详情
* [子代理](/en/sub-agents) - 代理配置和能力
* [Hooks](/en/hooks) - 事件处理和自动化
* [MCP](/en/mcp) - 外部工具集成
* [设置](/en/settings) - 插件的配置选项