Plugins 参考

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

插件是一个自包含的组件目录，使用自定义功能扩展 Claude Code。插件组件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。

插件组件参考

Skills

插件向 Claude Code 添加 skills，创建可由您或 Claude 调用的 /name 快捷方式。

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

文件格式：Skills 是包含 SKILL.md 的目录；commands 是简单的 markdown 文件

Skill 结构：

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

安装插件时会自动发现 Skills 和 commands。

如果插件没有 skills/ 目录且没有 skills manifest 字段，则插件根目录中的 SKILL.md 会作为单个 skill 加载。设置 frontmatter name 字段来控制 skill 的调用名称。如果没有设置，Claude Code 会回退到安装目录名称，对于从市场安装的插件，这是一个在每次更新时都会改变的版本字符串。对于包含多个 skill 的插件，请使用上面所示的 skills/ 目录布局。

在插件 skills 和 commands 中，Boolean frontmatter 字段（如 disable-model-invocation）接受 yes、no、on、off、1 和 0（任何字母大小写），以及 true 和 false。在 v2.1.218 之前，Claude Code 仅识别 true 和 false。

有关完整详情，请参阅 Skills。

Agents

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

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

文件格式：描述代理功能的 markdown 文件

Agent 结构：

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

Claude Code 会加载插件代理，即使其 frontmatter 没有 name 或无法解析：

没有 name：Claude Code 根据文件名命名代理，因此名为 my-plugin 的插件中的 agents/reviewer.md 会加载为 my-plugin:reviewer
Frontmatter 无法解析：Claude Code 根据文件名命名代理，使用 Agent from my-plugin plugin 作为其描述，并忽略文件中的每个字段

相比之下，Claude Code 会跳过其 frontmatter 没有 name 或无法解析的项目、用户或托管代理文件。

要查找插件默认 agents/ 目录中 frontmatter 无法解析的文件，请运行 claude plugin validate。您传递的路径取决于插件是否有 manifest，两个示例都使用 ./my-plugin 作为插件目录：

具有 manifest 的插件：claude plugin validate ./my-plugin
没有 manifest 的插件：claude plugin validate ./my-plugin/agents。需要 Claude Code v2.1.233 或更高版本。

启用插件后，代理会在 @-mention 类型提示中显示其作用域名称，例如 my-plugin:code-reviewer。

有关完整详情，请参阅 Subagents。

Hooks

插件可以提供事件处理程序，自动响应 Claude Code 事件。

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

格式：具有事件匹配器和操作的 JSON 配置

Hook 配置：

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

插件 hooks 响应与用户定义的 hooks 相同的生命周期事件：

事件	触发时机
`SessionStart`	当会话开始或恢复时
`Setup`	当你使用 `--init-only` 启动 Claude Code，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备
`UserPromptSubmit`	当你提交提示词时，在 Claude 处理之前
`UserPromptExpansion`	当用户输入的命令扩展为提示词时，在到达 Claude 之前。可以阻止扩展
`PreToolUse`	在工具调用执行之前。可以阻止它
`PermissionRequest`	当工具调用需要权限决策时
`PermissionDenied`	当自动模式拒绝工具调用时，包括没有分类器判决的拒绝。使用 JSON `hookSpecificOutput.retry: true` 来告诉模型它可以重试被拒绝的工具调用。Claude Code 在分类器未产生判决时忽略 `retry`
`PostToolUse`	在工具调用成功后
`PostToolUseFailure`	在工具调用失败后
`PostToolBatch`	在一整批并行工具调用解决后，在下一次模型调用之前
`Notification`	当 Claude Code 发送通知时
`MessageDisplay`	当助手消息文本正在显示时
`SubagentStart`	当子代理被生成时
`SubagentStop`	当子代理完成时
`TaskCreated`	当通过 `TaskCreate` 创建任务时
`TaskCompleted`	当任务被标记为已完成时
`Stop`	当 Claude 完成响应时
`StopFailure`	当轮次因 API 错误而结束时
`TeammateIdle`	当代理团队队友即将空闲时
`InstructionsLoaded`	当 CLAUDE.md 或 `.claude/rules/*.md` 文件被加载到上下文中时。在会话开始时和文件在会话期间被延迟加载时触发
`ConfigChange`	当配置文件在会话期间更改时
`CwdChanged`	当工作目录更改时，例如当 Claude 执行 `cd` 命令时。对于使用 direnv 等工具的反应式环境管理很有用
`DirectoryAdded`	当工作目录在会话中期通过 `/add-dir` 或 SDK `register_repo_root` 控制请求添加时
`FileChanged`	当监视的文件在磁盘上更改时。`matcher` 字段指定要监视的文件名
`WorktreeCreate`	当通过 `--worktree`、`isolation: "worktree"` 创建工作树时，或用于后台会话。替换默认的 git 行为
`WorktreeRemove`	当在会话退出时、子代理完成时或删除后台会话时移除工作树
`PreCompact`	在上下文压缩之前
`PostCompact`	在上下文压缩完成后
`PreModelSwitch`	在 Claude Code 应用你或客户端请求的模型切换之前。可以阻止切换
`PostModelSwitch`	在会话的模型更改后，包括 Claude Code 自己进行的更改，例如在你恢复会话时恢复模型
`Elicitation`	当 MCP 服务器在工具调用期间请求用户输入时
`ElicitationResult`	在用户响应 MCP 引出后，在响应发送回服务器之前
`SessionEnd`	当会话终止时

Hook 类型：

command：执行 shell 命令或脚本
http：将事件 JSON 作为 POST 请求发送到 URL
mcp_tool：在配置的 MCP server 上调用工具
prompt：使用 LLM 评估提示（使用 $ARGUMENTS 占位符作为上下文）
agent：运行具有工具的代理验证器以完成复杂验证任务

针对插件自己的捆绑 MCP server 的 hooks 必须使用其作用域名称。工具匹配器和 if 字段采用作用域工具名称 mcp__plugin_<plugin-name>_<server-name>__<tool>，mcp_tool hook 的 server 字段采用 plugin:<plugin-name>:<server-name>。针对裸服务器密钥编写的匹配器永远不会触发。请参阅 Match MCP tools 和 Plugin-provided MCP servers。

MCP servers

插件可以捆绑 Model Context Protocol (MCP) 服务器，以将 Claude Code 与外部工具和服务连接。

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

格式：标准 MCP 服务器配置

MCP 服务器配置：

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

集成行为：

启用插件时，插件 MCP 服务器会自动启动
服务器在 Claude 的工具包中显示为标准 MCP 工具
插件服务器可以独立于用户 MCP 服务器进行配置
如果您在会话中途运行 /reload-plugins，Claude Code 会保持配置未更改的服务器的实时连接

LSP servers

插件可以提供 Language Server Protocol (LSP) 服务器，以在处理您的代码库时为 Claude 提供实时代码智能。

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

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

.lsp.json 文件格式：

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

在 plugin.json 中内联：

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

必需字段：

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

可选字段：

字段	描述
`args`	LSP 服务器的命令行参数
`transport`	通信传输：`stdio`（默认）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上运行每个服务器，因此 stdout 协议规则适用于所有服务器
`env`	启动服务器时要设置的环境变量
`initializationOptions`	在初始化期间传递给服务器的选项
`settings`	通过 `workspace/didChangeConfiguration` 传递的设置
`workspaceFolder`	服务器的工作区文件夹路径
`startupTimeout`	等待服务器启动的最长时间（毫秒）
`shutdownTimeout`	等待正常关闭的最长时间（毫秒）。当超时时间过去时，Claude Code 会终止服务器进程。未设置时，不适用超时
`restartOnCrash`	服务器崩溃后是否重新启动。默认为 `true`。设置为 `false` 以保持崩溃的服务器停止而不是重新启动它
`maxRestarts`	放弃前的最大重启尝试次数
`diagnostics`	编辑后是否将诊断推送到 Claude 的上下文中（默认 `true`）。设置为 `false` 以保持代码导航但禁止自动诊断注入。

restartOnCrash 和 shutdownTimeout 需要 Claude Code v2.1.205 或更高版本。在 v2.1.205 之前，配置架构接受两个选项，但设置其中任何一个都会导致 Claude Code 在启动时完全跳过该 LSP 服务器，原因仅在 claude --debug 输出中可见。

同一扩展名的多个服务器：当多个启用的 LSP 服务器在 extensionToLanguage 中声明相同的文件扩展名时，无论服务器来自一个插件还是来自不同的插件，第一个注册的服务器处理具有该扩展名的文件，其他服务器永远不会启动。/plugin 界面显示一个警告，命名其服务器处于活动状态的插件。

无法初始化的服务器：Claude Code 会跳过配置无效的服务器，例如缺少 command 或 extensionToLanguage 的服务器，其他配置的服务器仍会启动。运行 claude --debug 以查看服务器被跳过的原因。

被跳过的服务器不会声明其文件扩展名，因此声明相同扩展名的另一个有效服务器（来自同一插件或不同插件）仍会处理这些文件。

将日志输出发送到 stderr，而不是 stdout：Claude Code 仅将服务器的 stdout 读取为协议消息，并接受最大 64 KiB 的消息头和最大 32 MiB 的消息体。Claude Code 会断开超过任一限制或向 stdout 写入非协议输出的服务器，并将断开连接计为 restartOnCrash 和 maxRestarts 的崩溃。当您使用 --debug 运行时，Claude Code 会将命名原因的错误写入调试日志。

可用的 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 安装

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

Monitors

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

插件监视器使用与 Monitor tool 相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，以与 hooks 相同的信任级别在非沙箱环境中运行，并在 Monitor tool 不可用的主机上被跳过。

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

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

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

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "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"。监视器是实验性组件。

必需字段：

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

可选字段：

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

command 值支持路径替换 ${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA} 和 ${CLAUDE_PROJECT_DIR}，以及环境中的任何 ${ENV_VAR}。如果脚本需要从插件自己的目录运行，请在命令前加上 cd "${CLAUDE_PLUGIN_ROOT}" && 。

监视器 command 不能引用 ${user_config.*} 值。命令通过 shell 运行，因此 Claude Code 会拒绝监视器并显示错误，而不是替换该值。监视器进程不会接收 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量，因此让监视器脚本从它拥有的配置文件中读取该值。

如果您在会话中途禁用插件，Claude Code 不会停止已在运行的监视器；它们在会话结束时停止。

Themes

插件可以提供颜色主题，这些主题与内置预设和用户的本地主题一起显示在 /theme 中。主题是 themes/ 中的 JSON 文件，具有 base 预设和稀疏的 overrides 颜色令牌映射。主题是实验性组件。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

当用户选择插件主题时，Claude Code 会在其配置中保存 custom:<plugin-name>:<slug>。插件主题是只读的：当用户在 /theme 中按 Ctrl+E 时，Claude Code 会将其复制到 ~/.claude/themes/ 中，以便他们可以编辑副本。

Plugin 安装作用域

当你安装一个 plugin 时，你选择一个作用域来确定 plugin 在哪里可用以及谁可以使用它：

作用域	设置文件	用例
`user`	`~/.claude/settings.json`	在所有项目中可用的个人 plugins（默认）
`project`	`.claude/settings.json`	通过版本控制共享的团队 plugins
`local`	`.claude/settings.local.json`	项目特定的 plugins，当 Claude Code 保存设置到其中时被 gitignored
`managed`	Managed settings	托管 plugins（只读，仅更新）

Plugins 使用与其他 Claude Code 配置相同的作用域系统。有关安装说明和作用域标志，请参阅 Install plugins。有关作用域的完整说明，请参阅 Configuration scopes。

Skills-directory plugins

任何 skills 目录下包含 .claude-plugin/plugin.json 清单的文件夹都会在下一个会话中作为名为 <name>@skills-dir 的 plugin 加载，无需 marketplace，也无需安装步骤。使用 plugin init 来搭建一个。与复制的 marketplace 安装不同，该 plugin 是在原地发现的，而不是复制到 plugin 缓存中。

A skills directory tree supports three distinct things:

What you have	What it is
`<skills-dir>/foo/SKILL.md` with no manifest	一个名为 `foo` 的普通 skill
`<skills-dir>/foo/.claude-plugin/plugin.json`	一个 plugin `foo@skills-dir`，可以捆绑自己的 skills、agents、hooks 等
`<plugin>/skills/bar/SKILL.md`	一个 skill `bar`，打包在 plugin 内部

选择 plugin 从哪里加载

Skills directory	Scope	Loads
`~/.claude/skills/`	personal	在每个项目中加载，因为该位置仅属于你
`<cwd>/.claude/skills/`	project	仅在你接受该文件夹的工作区 trust dialog 后加载

项目范围的 plugin 被检入到仓库中，并到达克隆它的每个协作者。因为该内容来自仓库而不是来自你，它仅在与 .claude/settings.json 中的项目允许规则相同的信任门控后加载，所以信任父文件夹或使用 -p 运行是不够的，运行代码的组件受到进一步限制：

它声明的 MCP servers 会经过与项目 .mcp.json 相同的 per-server approval
LSP servers 仅在你信任工作区后启动
Background monitors 不加载

Personal-scope plugins 没有这些限制。

编辑、重新加载和禁用 skills-directory plugin

你对 skill 的 SKILL.md 所做的更改会立即在当前会话中生效。对 plugin 的其他组件（如 hooks/、.mcp.json、agents/ 和 output-styles/）的更改则不会。运行 /reload-plugins 或重启 Claude Code 来获取这些更改。参见 Live change detection。

要停止加载 skills-directory plugin，删除其文件夹或按名称禁用它。没有 uninstall 步骤，因为没有从 marketplace 安装任何东西。

claude plugin disable my-tool@skills-dir

从 claude.ai 同步的插件

在 Cowork 和云会话中，Claude Code 会将为你的 claude.ai 账户启用的插件下载到会话自身环境中的 ~/.claude/plugins/synced/ 目录，并将每个插件加载为 <name>@synced，没有 marketplace 和没有安装记录。Claude Code 不会在你在自己的终端中启动的会话中加载它们。在该 Cowork 或云环境中，claude plugin list 会在 Synced from claude.ai 标题下显示下载的副本。在 v2.1.239 之前，Claude Code 将这些插件加载为 <name>@inline，这是 --plugin-dir 插件使用的身份。

通过 claude plugin list 打印的 <name>@synced ID 来管理同步的插件：

关闭一个插件：在同步会话中，运行 claude plugin disable <name>@synced，或要求 Claude 运行它。Claude Code 会将该选择保存为该环境的用户级 enabledPlugins 中的 "<name>@synced": false。要重新打开该插件，在同一会话中运行 claude plugin enable <name>@synced。要将插件排除在每个同步会话之外，为你的 claude.ai 账户关闭它。要将其排除在一个项目的每个环境中的同步会话之外，在该项目的已提交 .claude/settings.json 中的 enabledPlugins 下设置 "<name>@synced": false。
在 claude.ai 上管理插件本身：claude plugin install、update 和 uninstall 不适用于同步的插件。要删除一个，为你的 claude.ai 账户关闭该插件；下一个同步会话将在没有它的情况下启动。

当来自任何其他来源的启用插件（例如 marketplace 安装、skills-directory 插件或 --plugin-dir 插件）与同步插件的名称匹配时，Claude Code 会加载该插件并报告同步副本未加载。要改用 claude.ai 副本，请禁用你自己的副本。在 v2.1.239 之前，Claude Code 会加载同步副本而不是同名的 marketplace 安装。

Plugin manifest schema

.claude-plugin/plugin.json 文件定义了你的 plugin 的元数据和配置。

manifest 是可选的。如果省略，Claude Code 会在默认位置自动发现组件，并从目录名称派生 plugin 名称。当你需要提供元数据或自定义组件路径时，使用 manifest。

Complete schema

{
  "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"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "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",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

必需字段

如果你包含 manifest，name 是唯一必需的字段。

字段	类型	描述	示例
`name`	string	唯一标识符，采用 kebab-case，不包含空格、控制字符或双向格式化字符。当marketplace 条目以不同的名称列出 plugin 时，marketplace 条目名称是 `enabledPlugins` 键和 `/plugin` 使用的名称	`"deployment-tools"`

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

无法识别的字段

Claude Code 忽略它不识别的顶级字段。你可以在 plugin.json 中保留来自另一个生态系统的元数据，plugin 仍然会加载。这使得维护一个 manifest 作为 VS Code 或 Cursor 扩展 manifest、npm package.json 或 MCPB/DXT bundle manifest 变得实用。

claude plugin validate 将无法识别的字段报告为警告，而不是错误。如果一个字段与识别的字段相差一两个字符，警告会建议可能的预期名称。仅具有无法识别字段警告的 plugin 仍然通过验证并在运行时加载。

Claude Code 如何处理值类型错误的识别字段取决于该字段：

大多数字段：plugin 无法加载。例如，keywords 值是字符串而不是数组是加载错误，claude plugin validate 会将其报告为错误。
experimental 和 metadata：Claude Code 忽略非对象值，claude plugin validate 报告警告。

传递 --strict 以将警告视为错误。在 CI 中使用它来捕获拼写错误的字段名称或来自另一个工具的 manifest 中遗留的字段，然后再发布，即使 plugin 在运行时会加载。

claude plugin validate ./my-plugin --strict

元数据字段

字段	类型	描述	示例
`$schema`	string	JSON Schema URL，用于编辑器自动完成和验证。Claude Code 在加载时忽略此字段。	`"https://json.schemastore.org/claude-code-plugin-manifest.json"`
`displayName`	string	在 `/plugin` 选择器和其他 UI 表面中显示的人类可读名称。对于 marketplace 安装的 plugin，marketplace 条目上的 `displayName` 优先于此值。当两个地方都未设置显示名称时，用户会看到 `name`。与 `name` 不同，可以包含空格和任何大小写。不用于命名空间或查找。	`"Deployment Tools"`
`version`	string	可选。语义版本。设置此项会将 plugin 固定到该版本字符串，因此用户仅在你提升版本时才会收到更新，除了`command` 源外；请参阅版本管理。如果也在 marketplace 条目中设置，`plugin.json` 优先。如果省略，版本来自版本管理中的下一个源。	`"2.1.0"`
`description`	string	plugin 用途的简要说明	`"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"]`
`metadata`	object	自由格式对象，用于你自己的数据，例如权利或目录字段。Claude Code 不读取它，因此值永远不会影响 plugin 行为。Claude Code 忽略非对象值，`claude plugin validate` 将其报告为警告。在 v2.1.222 之前，Claude Code 将该键视为无法识别的字段。	`{"catalogId": "cat-123"}`
`defaultEnabled`	boolean	当用户未设置 plugin 状态时，plugin 是否以启用状态启动。默认为 `true`。请参阅默认启用。	`false`

默认启用

在 plugin.json 中设置 defaultEnabled: false 以发布已禁用安装的 plugin。用户使用 claude plugin enable <plugin> 或 /plugin 界面将其打开。对于添加成本或用户应该选择加入的范围的 plugin 使用此选项，例如连接到外部服务的 plugin。

defaultEnabled 是当没有其他因素决定 plugin 状态时的后备。两件事优先于它：

用户的设置：任何设置范围内 enabledPlugins 中的 plugin 条目。一旦写入，它会在 plugin 更新和重新安装中持续存在，因此在后续版本中更改 defaultEnabled 不会翻转现有用户。
依赖项要求：当 plugin 被另一个活跃的 plugin 需要时，Claude Code 在安装或启用时为其写入 true。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅启用或禁用具有依赖项的 plugin。

同一字段可以出现在 plugin 的 marketplace 条目中，其中它优先于 plugin.json 中的值。请参阅可选 plugin 字段。

组件路径字段

字段	类型	描述	示例
`skills`	string\|array	包含 `<name>/SKILL.md` 的自定义 skill 目录。添加到默认 `skills/` 扫描。请参阅路径行为规则了解 marketplace-root 异常	`"./custom/skills/"`
`commands`	string\|array	自定义平面 `.md` skill 文件或目录（替换默认 `commands/`）	`"./custom/cmd.md"` 或 `["./cmd1.md"]`
`agents`	string\|array	自定义 agent 文件（替换默认 `agents/`）	`"./custom/agents/reviewer.md"`
`workflows`	string\|array	自定义workflow 脚本文件或目录（替换默认 `workflows/`）	`"./custom/workflows/"`
`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	Language Server Protocol 配置，用于代码智能（转到定义、查找引用等）	`"./.lsp.json"`
`experimental.themes`	string\|array	颜色主题文件/目录（替换默认 `themes/`）。请参阅主题	`"./themes/"`
`experimental.monitors`	string\|array	后台Monitor 配置，在 plugin 活跃时自动启动。请参阅监视器	`"./monitors.json"`
`experimental.evals`	string\|array	plugin 根目录下的目录，当不是默认 `evals/` 时，保存 plugin 的eval cases。`claude plugin eval --eval-dir` 会覆盖它	`"quality/evals"`
`userConfig`	object	在启用时提示的用户可配置值。请参阅用户配置	见下文
`channels`	array	消息注入的频道声明（Telegram、Slack、Discord 风格）。请参阅频道	见下文
`dependencies`	array	此 plugin 需要的其他 plugin，可选择带有 semver 版本约束。请参阅约束 plugin 依赖项版本	`[{ "name": "secrets-vault", "version": "~2.1.0" }]`

实验性组件

experimental 键下的组件 themes 和 monitors 具有在版本之间可能会改变的 manifest schema，同时它们稳定下来。你声明它们的位置是一个单独的迁移：顶级仍然有效，claude plugin validate 发出警告，未来版本将需要 experimental.*。

用户配置

userConfig 字段声明当 plugin 启用时 Claude Code 提示用户的值。使用此选项而不是要求用户手动编辑 settings.json。

{
  "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` 类型的边界

每个值都可用于在 MCP 和 LSP 服务器配置以及 hook 命令中作为 ${user_config.KEY} 进行替换。非敏感值也可以在 skill 和 agent 内容中替换。所有值都作为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量导出到 hook 进程，其中 <KEY> 是选项键的大写形式。

在 shell 中运行的字段拒绝 ${user_config.*}：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件失败并出现错误。每个被拒绝的字段都有一种替代方式来传递值：

被拒绝的字段	如何传递值
Shell 形式的 hook 命令	使用带有 `args` 的 exec 形式，或从 hook 的环境中读取 `CLAUDE_PLUGIN_OPTION_<KEY>`
Monitor 命令	从脚本中的配置文件读取值
MCP `headersHelper`	从脚本中的配置文件读取值

在 v2.1.207 之前，这些字段替换了 ${user_config.KEY} 值；更新依赖此功能的 plugin。

非敏感值存储在用户 settings.json 中 pluginConfigs 键下，作为 pluginConfigs[<plugin-id>].options。

在 macOS 上，Claude Code 将敏感值存储在 macOS Keychain 中，当 Keychain 拒绝写入时回退到 ~/.claude/.credentials.json。在没有支持的 keychain 的平台上，它将它们存储在 ~/.claude/.credentials.json 中。Keychain 存储与 OAuth 令牌共享，总限制约为 2 KB，因此保持敏感值较小。

Claude Code 仅从三个设置源读取所有 pluginConfigs 值：

用户设置：~/.claude/settings.json，启用时提示写入的文件
--settings：CLI 标志或 SDK 内联设置
托管设置：组织控制的策略

当多个源设置相同的键时，托管设置优先，然后是 --settings，然后是用户设置。你可以从此列表中删除的唯一源是用户设置：传递不包含 user 的 --setting-sources，Claude Code 会跳过它们。托管设置和 --settings 保持你传递的任何内容。SDK 的 settingSources 选项设置相同的列表。

项目的 .claude/settings.json 或 .claude/settings.local.json 中的条目被忽略。两个文件都位于工作区中，因此克隆的存储库可以在那里提供值，这些值会流入 plugin hook 命令、MCP 服务器配置、LSP 命令和监视器命令。在 v2.1.207 之前，这些条目被读取。限制特定于 pluginConfigs：enabledPlugins 仍然遵守项目和本地设置。

频道

channels 字段让 plugin 声明一个或多个消息频道，将内容注入到对话中。每个频道绑定到 plugin 提供的 MCP 服务器。

{
  "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 字段是必需的，必须与 plugin 的 mcpServers 中的键匹配。可选的每个频道 userConfig 使用与顶级字段相同的 schema，让 plugin 在启用时提示输入机器人令牌或所有者 ID。

路径行为规则

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

替换默认值：commands、agents、workflows、outputStyles、experimental.themes、experimental.monitors。例如，当 manifest 指定 commands 时，不会扫描默认 commands/ 目录。要保留默认值并添加更多，请明确列出："commands": ["./commands/", "./extras/"]
添加到默认值：skills。默认 skills/ 目录始终被扫描，skills 中列出的目录与其一起加载。异常：对于源解析为 marketplace 根的 marketplace 条目，声明特定子目录会替换默认 skills/ 扫描
自己的合并规则：hooks、MCP 服务器和 LSP 服务器。请参阅每个部分了解多个源如何组合

当 plugin 同时具有默认文件夹和匹配的 manifest 键时，Claude Code 在 claude plugin list 和 /plugin 详细视图中警告被忽略的文件夹。plugin 仍然使用 manifest 路径加载。当 manifest 键指向默认文件夹时，Claude Code 不会发出警告，例如 "commands": ["./commands/deploy.md"]，因为该路径明确命名了文件夹。

对于所有路径字段：

所有路径必须相对于 plugin 根目录并以 ./ 开头，除了 skills 字段也接受 "."
- "." 和 "./" 都表示 plugin 根目录本身
- 在 v2.1.221 之前，"." 无法通过 manifest 验证，plugin 无法加载，因此使用 "./" 来支持早期版本
来自自定义路径的组件使用相同的命名和命名空间规则
可以将多个路径指定为数组
skill 路径可以指向直接包含 SKILL.md 的目录，例如 "skills": ["."] 用于 plugin 根目录
- Claude Code 从 SKILL.md 中的 frontmatter name 字段获取 skill 的调用名称，因此无论安装目录的名称如何，名称都保持稳定
- 如果 frontmatter 中未设置 name，Claude Code 会回退到目录基名

具有根目录中的 SKILL.md、没有 skills/ 子目录且没有 skills manifest 字段的 plugin 会自动作为单 skill plugin 加载。对于此布局，你不需要在 plugin.json 中设置 "skills": ["./"]。

路径示例：

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

环境变量

Claude Code 提供三个变量用于引用路径：

变量	解析为	用途
`${CLAUDE_PLUGIN_ROOT}`	plugin 安装目录的绝对路径	与 plugin 捆绑的脚本、二进制文件和配置文件
`${CLAUDE_PLUGIN_DATA}`	持久目录，在首次引用时创建，在 plugin 更新中存活	已安装的依赖项，例如 `node_modules` 或 Python 虚拟环境、生成的代码和缓存
`${CLAUDE_PROJECT_DIR}`	项目根目录	项目本地脚本和配置文件

所有三个都作为环境变量导出到 hook 进程以及 MCP 和 LSP 服务器子进程。哪些字段内联替换它们取决于 plugin 组件：

Plugin 组件	占位符解析的字段
Skill 和 agent 内容	占位符出现的任何地方
Hook 和 monitor 命令	占位符出现的任何地方
MCP `stdio` 服务器	`command`、`args`、`env`
MCP `http`、`sse`、`ws` 服务器	`url`、`headers`、`headersHelper`
LSP 服务器	`command`、`args`、`env`、`workspaceFolder`

在 hook 命令中，使用带有 args 的 exec 形式，以便每个路径作为一个参数传递，无需引用。在 shell 形式的 hooks 和 monitor 命令中，用双引号包装变量，如 "${CLAUDE_PROJECT_DIR}/scripts/server.sh"。此 shell 形式的 hook 运行与 plugin 捆绑的脚本：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} 在 plugin 更新时改变。前一个版本的目录在更新后的宽限期内保留在磁盘上，但将其视为临时的，不要在那里写入状态。请参阅 plugin 缓存了解清理语义。

当 plugin 在会话中期更新时，hook 命令、monitors、MCP 服务器和 LSP 服务器继续使用前一个版本的路径。运行 /reload-plugins 将 hooks、MCP 服务器和 LSP 服务器切换到新路径；monitors 需要会话重启。在没有交互式终端的会话中，重新加载会将 plugin MCP 服务器保留在旧路径上，直到下一个会话。

对于具有 command 源的 plugin，Claude Code 可以重新加载 plugin 本身。

MCP 服务器也可以调用 roots/list 请求在运行时读取会话的工作目录。请参阅roots/list 返回的内容以及 Claude Code 何时通知服务器更改。

持久数据目录

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

常见用途是一次安装语言依赖项并在会话和 plugin 更新中重复使用它们。将其用于 Python 依赖项、使用 Yarn 或 pnpm 锁定的依赖项以及生命周期脚本必须运行的包。对于 marketplace 安装的 plugin，你可能根本不需要它：Claude Code 在缓存 plugin 时自动安装符合条件的 Node.js 包依赖项。

因为数据目录的生命周期超过任何单个 plugin 版本，仅检查目录存在性无法检测到更新何时更改 plugin 的依赖项 manifest。推荐的模式是将捆绑的 manifest 与数据目录中的副本进行比较，并在它们不同时重新安装。

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

{
  "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 会删除复制的 manifest，以便下一个会话重试。

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

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

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

Plugin 缓存和文件解析

Plugin 可以通过以下两种方式指定：

通过 claude --plugin-dir 或 claude --plugin-url，在会话期间使用。
通过 marketplace，为未来的会话安装。

出于安全和验证目的，Claude Code 将 marketplace plugin 复制到用户的本地 plugin 缓存（~/.claude/plugins/cache）中，而不是就地使用它们，除了 link 模式下的 command 源，Claude Code 通过缓存条目中的链接就地使用这些源。

对于复制的 plugin，每个已安装的版本都是缓存中的一个单独目录，按 marketplace 和 plugin 分组，并以解析的版本命名，包含 plugin 文件和 Node.js 包依赖的自己的副本。从 release tag 解析的依赖会获得一个带有 commit-SHA 后缀的目录名。

当你更新或卸载 plugin 时，Claude Code 会将之前的版本目录标记为孤立，并在大约 14 天后的后台扫描中将其删除。宽限期允许已加载旧版本的并发 Claude Code 会话继续运行而不出错。Claude Code 仅在至少安装了一个 plugin 时才运行扫描；在卸载最后一个 plugin 后，孤立目录会保留在磁盘上，直到你再次安装 plugin。

Claude Code 仅在 plugin 或 marketplace 文件夹不再包含任何目录或符号链接时才将其从缓存中删除。如果你将开发检出符号链接到缓存中作为 plugin 的版本条目，Claude Code 永远不会将该链接标记为孤立，也永远不会删除它或保存它的文件夹。Claude Code 也永远不会在链接的检出中写入其版本跟踪文件。

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

Node.js 包依赖

当 Claude Code 将 plugin 复制到缓存中时，它也会在那里安装 plugin 的 Node.js 包依赖，以便 plugin 的 hooks 和 MCP 服务器可以加载它们。本节涵盖 plugin 在其自己的 package.json 中声明的 npm 和 Bun 包。对于依赖其他 plugin 的 plugin，请参阅 plugin 依赖版本。

Claude Code 在每次创建复制的版本目录时在其中运行安装：当你安装 plugin 时、当 Claude Code 将 plugin 更新到新版本时，以及在会话启动时当启用的 plugin 尚未缓存时（例如在新机器上）。仅当 plugin 的根目录同时包含 package.json 和受支持的 lockfile 时，安装才会运行：

Lockfile	命令
`bun.lock` 或 `bun.lockb`	`bun install --frozen-lockfile --ignore-scripts`
`npm-shrinkwrap.json` 或 `package-lock.json`	`npm ci --ignore-scripts`

如果 plugin 包含多个这些 lockfile，Claude Code 使用第一个匹配项，按顺序检查：bun.lock、bun.lockb、npm-shrinkwrap.json、package-lock.json。Claude Code 跳过 yarn.lock 和 pnpm-lock.yaml，因为 Yarn 和 pnpm 支持绕过 --ignore-scripts 的分辨率时间配置钩子。

为了获得最广泛的覆盖范围，请提供 npm lockfile。Claude Code 从用户的 PATH 运行匹配的 lockfile 的包管理器，如果缺少其他 lockfile，不会回退到它。对于通过 npm 源分发的 plugin，使用 npm-shrinkwrap.json；npm 从已发布的包中排除 package-lock.json。

Claude Code 对此依赖安装进行了约束，以便 plugin 或其包中的任何代码在安装期间都不会执行，并限制其运行时间：

冻结分辨率： Bun 和 npm 安装 lockfile 精确指定的内容，当 package.json 和 lockfile 不一致时失败而不是重新分辨版本。
无生命周期脚本： --ignore-scripts 防止 preinstall、install 和 postinstall 脚本运行，因此在这些脚本中构建本机模块的依赖会下载但在此安装期间不会编译。
60 秒超时： Claude Code 停止运行时间较长的安装并将其视为失败。

获取 npm 源 plugin 本身会在此依赖安装运行之前运行启用了生命周期脚本的 npm install。

失败或跳过的安装永远不会阻止 plugin。当安装失败或 Claude Code 跳过 yarn 或 pnpm lockfile 时，它会在 debug 输出中将原因记录为警告。具有 package.json 但没有 lockfile 的 plugin 会被跳过而不记录日志条目。超时的安装可能会在缓存副本中留下部分 node_modules 树。

你无法关闭自动安装；没有设置或环境变量可以禁用它。在受限网络中，请参阅网络访问要求以了解要允许的主机。

对于自动安装无法提供的依赖，例如需要其生命周期脚本来构建的包、Python 依赖或使用 Yarn 或 pnpm 锁定的 plugin，请从 hook 将它们安装到持久数据目录。

路径遍历限制

Claude Code 不允许 plugin 引用其自己目录之外的文件。它拒绝解析到 plugin 根目录之外的组件路径，无论该路径是在 plugin.json 中声明还是在 marketplace 条目中声明。这涵盖指向 plugin 外部的路径（如 ../shared-utils）和导向 plugin 外部的符号链接，除了一个 marketplace 内的链接。

在 macOS 和 Linux 上，Claude Code 也拒绝包含反斜杠的组件路径，即使该路径保留在 plugin 内。因此，使用反斜杠路径声明的组件仅在 Windows 上加载。使用正斜杠编写组件路径，例如 ./commands/deploy.md。

当 Claude Code 拒绝路径时，它会报告 path escapes plugin directory 错误，并在没有该组件的情况下加载 plugin。

Claude Code 在安装 plugin 时也不会将 plugin 目录之外的文件复制到缓存中，因此当复制的 plugin 内的脚本读取 plugin 根目录上方的路径时，它也找不到这些文件。

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

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

对于使用 --plugin-dir 安装的 plugin、来自本地路径的 plugin 或来自 copy 模式下的 command 源的 plugin，仅保留解析到 plugin 自己目录内的符号链接。所有其他的都被跳过。

以下命令创建从 marketplace plugin 内部到由兄弟 plugin 定义的共享技能的链接。在 Windows 上，从提升的命令提示符使用 mklink /D 或启用开发者模式：

ln -s ../../shared-plugin/skills/foo ./skills/foo

Plugin 目录结构

标准 plugin 布局

一个完整的 plugin 遵循以下结构：

enterprise-plugin/
├── .claude-plugin/           # 元数据目录（可选）
│   └── plugin.json             # plugin 清单
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills 作为平面 .md 文件
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent 定义
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Workflow 脚本
│   └── release-audit.js
├── output-styles/            # 输出样式定义
│   └── terse.md
├── themes/                   # 颜色主题定义
│   └── dracula.json
├── monitors/                 # 后台监视器配置
│   └── monitors.json
├── hooks/                    # Hook 配置
│   ├── hooks.json           # 主 hook 配置
│   └── security-hooks.json  # 其他 hooks
├── bin/                      # 添加到 PATH 的 plugin 可执行文件
│   └── my-tool               # 在 Bash tool 中可作为裸命令调用
├── settings.json            # plugin 的默认设置
├── .mcp.json                # MCP 服务器定义
├── .lsp.json                # LSP 服务器配置
├── scripts/                 # Hook 和实用脚本
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # 许可证文件
└── CHANGELOG.md             # 版本历史

plugin 根目录中的 CLAUDE.md 文件不会作为项目上下文加载。Plugins 通过 skills、agents 和 hooks 而不是 CLAUDE.md 来贡献上下文。要提供加载到 Claude 上下文中的说明，请将其放在 skill 中。

文件位置参考

组件	默认位置	用途
清单	`.claude-plugin/plugin.json`	Plugin 元数据和配置（可选）
Skills	`skills/`	具有 `<name>/SKILL.md` 结构的 Skills
Commands	`commands/`	作为平面 Markdown 文件的 Skills。新 plugins 请使用 `skills/`
Agents	`agents/`	Subagent Markdown 文件
Workflows	`workflows/`	Workflow 脚本文件
输出样式	`output-styles/`	输出样式定义
主题	`themes/`	颜色主题定义
Hooks	`hooks/hooks.json`	Hook 配置
MCP 服务器	`.mcp.json`	MCP 服务器定义
LSP 服务器	`.lsp.json`	语言服务器配置
监视器	`monitors/monitors.json`	后台监视器配置
可执行文件	`bin/`	添加到 Bash tool 的 `PATH` 中的可执行文件，在 plugin 启用时可作为裸命令调用。如果您通过 claude.ai 组织设置分发 plugin，则不能在其中包含此目录
设置	`settings.json`	启用 plugin 时应用的默认配置。仅支持 `agent` 和 `subagentStatusLine` 键

CLI 命令参考

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

plugin init

在 ~/.claude/skills/<name>/ 处搭建一个新插件。在下一个 Claude Code 会话中，它会自动加载为 <name>@skills-dir，并在 /plugin 和 claude plugin list 中显示，无需安装步骤。

请参阅 Skills-directory plugins 了解范围和信任要求。

claude plugin init <name> [options]

该命令接受这些参数：

<name>：插件名称。成为技能命名空间和 ~/.claude/skills/ 下的目录名称，因此不能包含空格或路径分隔符。

该命令接受这些选项：

选项	描述	默认值
`--description <text>`	清单描述
`--author <name>`	作者名称	`git config user.name`
`--author-email <email>`	作者电子邮件	`git config user.email`
`--with <components...>`	同时搭建组件文件夹。有效值：`skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style`、`channel`
`-f, --force`	覆盖目标处现有的 `.claude-plugin/`
`-h, --help`	显示命令帮助

claude plugin new 是此命令的别名。

每个 --with 值都会为该组件添加一个启动文件，准备好编辑：

组件	搭建内容
`skills`	一个额外的命名空间 `<name>:example` 技能，与默认技能并列
`agents`	一个 `agents/` 子代理定义
`hooks`	一个 `hooks/hooks.json`，包含示例事件处理程序
`mcp`	一个 `.mcp.json`，包含 HTTP 和 stdio 服务器示例
`lsp`	一个 `.lsp.json` 语言服务器示例
`output-style`	一个 `output-styles/<name>.md`，在插件启用时自动应用
`channel`	一个基于 MCP 的 channel：一个 stdio 服务器（`server.ts`）、其 `.mcp.json` 和一个 `package.json`

搭建的插件使用 @skills-dir 源而不是市场。管理员可以通过 strictKnownMarketplaces 或在 managed settings 中添加 {"source": "skills-dir"} 到 blockedMarketplaces 来阻止此源。当被阻止时，plugin init 在写入前失败。

这些示例显示常见的调用：

# 搭建最小插件
claude plugin init my-helper

# 搭建带有技能和钩子文件夹的插件
claude plugin init my-helper --with skills hooks

# 覆盖现有搭建
claude plugin init my-helper --force

plugin install

从可用市场安装插件。

claude plugin install <plugin> [options]

该命令接受这些参数：

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

该命令接受这些选项：

选项	描述	默认值
`-s, --scope <scope>`	安装范围：`user`、`project` 或 `local`	`user`
`--config <key=value>`	设置插件清单中声明的 `userConfig` 选项。重复该标志以设置多个选项
`-y, --yes`	接受插件市场声明的命令，无需确认提示：生成具有 `command` source 的插件的命令，或验证存档下载的 `headersHelper`。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令
`--json`	将结果作为 stdout 最后一行的一个 JSON 对象打印，用于脚本。请参阅 JSON result format。需要 Claude Code v2.1.268 或更高版本
`-h, --help`	显示命令帮助

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

使用 --json，stdout 的最后一行是一个 JSON 对象。仅解析该行，因为 Claude Code 会在其前面打印市场声明的任何命令。三个字段始终存在：

command：运行的子命令，例如 install
outcome：ok 或 failed
message：结果的人类可读描述

其他字段，例如 pluginId、scope 和 failureCode，仅在适用时出现。plugin uninstall、plugin update、plugin enable 和 plugin disable 上的 --json 选项打印具有该子命令自己字段的相同对象。使用错误，例如无效的 --scope，不打印结果行并以 stderr 上的原因退出 1。

这些示例显示常见的调用：

# 安装到用户范围（默认）
claude plugin install formatter@my-marketplace

# 安装到项目范围（与团队共享）
claude plugin install formatter@my-marketplace --scope project

# 安装到本地范围（不与团队共享）
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

删除已安装的插件。

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
`-y, --yes`	跳过 `--prune` 确认提示。当 stdin 或 stdout 不是 TTY 时需要
`--json`	将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 `plugin install --json` 相同。不能与 `--prune` 组合。需要 Claude Code v2.1.268 或更高版本
`-h, --help`	显示命令帮助

claude plugin remove 和 claude plugin rm 是此命令的别名。

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

plugin prune

删除不再被任何已安装插件需要的自动安装插件依赖项。Claude Code 为满足另一个插件的 dependencies 字段而拉入的依赖项会被删除；您直接安装的插件永远不会被触及。

claude plugin prune [options]

该命令接受这些选项：

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

claude plugin autoremove 是此命令的别名。

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

plugin enable

启用已禁用的插件。当目标从市场安装并声明 dependencies 时，Claude Code 在同一范围内以传递方式启用它们。该命令在 Enable or disable a plugin with dependencies 列出的条件下失败。

claude plugin enable <plugin> [options]

该命令接受这些参数：

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

该命令接受这些选项：

选项	描述	默认值
`-s, --scope <scope>`	启用范围：`user`、`project` 或 `local`。省略时，Claude Code 检测安装插件的范围	自动检测
`--json`	将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本
`-h, --help`	显示命令帮助

plugin disable

禁用插件而不卸载它。当目标从市场安装时，如果另一个启用的插件 depends on 它，该命令会失败。错误消息包含一个链式命令，首先禁用每个依赖项。

claude plugin disable [plugin] [options]

该命令接受这些参数：

[plugin]：插件名称或 plugin-name@marketplace-name。使用 --all 时可选

该命令接受这些选项：

选项	描述	默认值
`-a, --all`	禁用所有启用的插件。不能与 `--scope` 组合
`-s, --scope <scope>`	禁用范围：`user`、`project` 或 `local`。省略时，Claude Code 检测安装插件的范围	自动检测
`--json`	将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本
`-h, --help`	显示命令帮助

plugin update

将插件更新到最新版本。

claude plugin update <plugin> [options]

该命令接受这些参数：

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

该命令接受这些选项：

选项	描述	默认值
`-s, --scope <scope>`	更新范围：`user`、`project`、`local` 或 `managed`	`user`
`-y, --yes`	接受插件市场声明的命令，无需确认提示：生成具有 `command` source 的插件的命令，或验证存档下载的 `headersHelper`。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令
`--json`	将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本
`-h, --help`	显示命令帮助

plugin list

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

claude plugin list [options]

该命令接受这些选项：

选项	描述	默认值
`--json`	输出为 JSON。具有加载问题或创作警告的插件行携带 `errors` 或 `notes` 字符串数组。在 Claude Code v2.1.268 或更高版本上，并行 `errorDetails` 和 `noteDetails` 数组为每个条目提供诊断 `type` 和它引用的名称，例如插件、市场、服务器或文件
`--available`	包括市场中的可用插件。需要 `--json`
`-h, --help`	显示命令帮助

在交互式会话中，/plugin list 打印类似的列表内联，但仅涵盖市场安装的插件：

从技能目录加载的插件出现在 /plugin 界面和 claude plugin list 中，但不出现在内联 /plugin list 输出中。
在 Claude Code v2.1.239 或更高版本上，从 claude.ai 同步的插件在您在同步会话下载它们的环境中运行 claude plugin list 时出现。它们不出现在内联 /plugin list 输出中。
使用 --plugin-dir 或 --plugin-url 为会话加载的插件出现在 /plugin 界面中，仅当相同标志在子命令前时才出现在 claude plugin list 中，如 claude --plugin-dir <dir> plugin list。仅标志名称标识其位置，因此裸 claude plugin list 无法找到它们，不同于同步插件和技能目录插件，其固定目录 Claude Code 扫描。

交互式形式接受 --enabled 或 --disabled 以仅显示该状态中的插件，以及 ls 作为 list 的简写。

plugin details

显示插件的组件清单和预计令牌成本。输出列出插件贡献的所有组件，分组为 Skills、Agents、Hooks、MCP 服务器和 LSP 服务器，以及它为每个会话添加多少令牌的估计。Skills 组包括 skills/ 和 commands/ 条目。

claude plugin details <name>

该命令接受这些参数：

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

该命令接受这些选项：

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

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

Always-on： 插件的列表文本（如技能描述、代理描述和命令名称）添加到每个会话的令牌，无论任何组件是否触发。
On-invoke： 组件触发时的成本。按组件显示，而不是作为插件总计，因为典型会话仅调用组件的子集。

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

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)  SessionStart  (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.

always-on 总计通过您的活跃模型的 count_tokens API 计算。按组件的数字按比例从该总计缩放。如果 API 无法访问，该命令回退到基于字符的估计。

plugin validate

在发布前检查插件或市场的语法和架构错误。

当验证通过时命令退出 0，失败时退出 1，验证运行本身失败时退出 2，例如当您传递的路径不可读时。

claude plugin validate <path> [options]

该命令接受这些参数：

<path>：插件目录或市场目录的路径。请参阅 Validate a plugin or a directory without a manifest 了解插件运行涵盖的文件。

该命令接受这些选项：

选项	描述	默认值
`--strict`	将警告视为错误，在警告时退出 1。在 CI 中使用以捕获运行时容忍的问题，例如 unrecognized fields
`--json`	将验证报告输出为一个 JSON 对象，具有相同的退出代码。需要 Claude Code v2.1.259 或更高版本
`-h, --help`	显示命令帮助

使用 --json，Claude Code 将报告写入 stdout 作为一个 JSON 对象，具有这些顶级字段：

success：退出代码给出的相同判决
strict：运行是否将警告视为错误
target：Claude Code 验证的已解析路径
manifest：清单自己的结果，或 null 用于 run without a manifest
contents：按文件结果，每个命名其 file 并携带 errors、warnings 和 notes 数组

在退出 2 时，该命令不向 stdout 写入任何内容；错误消息转到 stderr。

在交互式会话中，/plugin validate <path> 内联运行相同的检查。

plugin eval

运行插件的 eval cases 并报告评分结果。需要 Claude Code v2.1.269 或更高版本。每个案例都是一个提示加评分器；Claude Code 在隔离会话中运行它多次，仅加载目标插件，默认情况下也不加载插件，以便报告显示差异。请参阅 Test plugins with evals 了解案例格式、评分器、结果和 CI 使用。

claude plugin eval [target] [options]

可选的 target 是一个插件目录、单个 prompt.md 或 case.yaml 文件、已安装的插件作为 name 或 name@marketplace，或 name@skills-dir，默认为当前目录。将其放在 --tag、--allow-tools 和 --json 之前。

此表列出大多数运行使用的选项。运行 claude plugin eval --help 以获取完整集合，包括 --case、--tag、--output-dir、--report、--allow-real-servers、--keep-temp 和 --verbose。

选项	描述	默认值
`--runs <n>`	每个案例每个分支的运行次数	每个案例的 `runs`，否则 3
`-j, --concurrency <n>`	一次运行的代理会话数，1 到 8。它们共享您的速率限制	`1`
`--model <model>`	被测试代理的模型	每个案例的 `model`，否则 `ANTHROPIC_MODEL`（如果设置），否则 Claude Code 的默认值
`--judge-model <model>`	`llm` 和 `baseline` 评分器的模型	一个小的快速模型
`--ablation <mode>`	`none` 或 `with-without`。请参阅 Compare against a no-plugin baseline	当插件解析时为 `with-without`，否则为 `none`
`--threshold <0..1>`	如果任何案例评分低于此值则退出 1	`1.0`
`--max-cost-usd <usd>`	一旦支出达到此值就停止下一次运行，退出 2，并报告部分结果	无上限
`--allow-tools <tools...>`	授予超出只读集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅 Grant tools
`--scaffold`	运行每个案例的 `scaffold_script`	关闭
`--trust-plugin`	跳过首次运行信任提示，用于 CI。请参阅 What a run can access	关闭
`--mocks <mode>`	`record` 或 `off`。请参阅 Mock MCP servers	`record`
`--eval-dir <dir>`	保存案例的插件下方的目录	清单的 `experimental.evals`，否则 `evals`
`--json [path]`	将 result document 打印到 stdout，或将其写入 `.json` 路径
`--no-publish`	保持 HTML 报告本地
`-h, --help`	显示命令帮助

当每个案例都满足阈值时命令退出 0，在失败案例、加载错误或不受信任的插件目录时退出 1，在部分运行时退出 2，中断时退出 130，终止时退出 143。请参阅 Run evals in CI。

plugin eval init

为当前目录中的插件创建一个 eval 套件。需要 Claude Code v2.1.269 或更高版本。在终端中，这会启动一个创作访谈，读取插件、提议案例和评分器、试验它们并写入文件。使用 --bare，或没有终端时，它会写入一个空白的单案例模板。从交互式 Claude Code 会话内运行，它会打印该会话要遵循的访谈说明，而不是写入模板。请参阅 Create your first eval suite。

claude plugin eval init [name] [options]

可选的 name 是一个案例名称：访谈不需要一个，而 --bare 和无终端模板路径需要一个。它接受这些选项：

选项	描述	默认值
`--bare`	为 `<name>` 写入一个空白的 `prompt.md` 和 `graders/criteria.md`，而不是运行访谈
`-i, --interactive`	需要访谈。没有终端时失败，而不是写入模板
`--eval-dir <dir>`	当前目录下方写入案例的目录	清单的 `experimental.evals`，否则 `evals`
`-h, --help`	显示命令帮助

plugin tag

为插件创建发布 git 标签。默认情况下，该命令标记当前目录中的插件；传递路径以标记其他地方的插件。请参阅 Tag plugin releases。

claude plugin tag [path] [options]

该命令接受这些参数：

[path]：插件目录的路径。默认为当前目录。

该命令接受这些选项：

选项	描述	默认值
`--push`	创建标签后将其推送到远程
`--dry-run`	打印将被标记的内容而不创建标签
`-f, --force`	即使工作树脏或标签已存在也创建标签
`-m, --message <msg>`	标签注释消息。使用 `%s` 作为版本的占位符
`--remote <name>`	使用 `--push` 推送到的远程	`origin`
`-h, --help`	显示命令帮助

调试和开发工具

调试命令

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

这会显示：

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

常见问题

问题	原因	解决方案
插件未加载	无效的 `plugin.json`	运行 `claude plugin validate ./my-plugin` 或 `/plugin validate ./my-plugin`，其中 `./my-plugin` 是你的插件目录，以检查 `plugin.json`、`hooks/hooks.json` 以及插件默认目录中的 skills、agents 和 commands 的前置元数据是否存在语法和模式错误。参见验证插件或没有清单的目录了解运行涵盖的内容
Skills 未显示	目录结构错误	确保 `skills/` 或 `commands/` 在插件根目录，而不是在 `.claude-plugin/` 内
Hooks 未触发	脚本不可执行	运行 `chmod +x script.sh`
MCP 服务器失败	缺少 `${CLAUDE_PLUGIN_ROOT}`	对所有插件路径使用变量
路径错误	使用了绝对路径	使路径相对，以 `./` 开头；参见路径行为规则，其中涵盖了 `skills` 字段的 `"."` 例外
LSP `Executable not found in $PATH`	语言服务器未安装	安装二进制文件（例如，`npm install -g typescript-language-server typescript`）

示例错误消息

清单验证错误：

Invalid JSON syntax: Unexpected token } in JSON at position 142：检查是否缺少逗号、多余逗号或未引用的字符串
Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined：缺少必需字段
Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...：JSON 语法错误。在 v2.1.246 之前，Claude Code 也会为保存为带有字节顺序标记 (BOM) 的 UTF-8 的 plugin.json 产生此错误，即使 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.：删除重复的组件定义或在 marketplace 条目中删除 strict: false

Hook 故障排除

Hook 脚本未执行：

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

Hook 未在预期事件上触发：

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

MCP 服务器故障排除

服务器未启动：

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

服务器工具未显示：

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

目录结构错误

症状：插件加载但组件（skills、agents、hooks）缺失。

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

调试检查清单：

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

分发和版本管理参考

版本管理

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

对于除 command 之外的每种源类型，Claude Code 从以下第一个设置的项中解析版本：

插件 plugin.json 中的 version 字段
插件在 marketplace.json 中的市场条目中的 version 字段
插件源的 git 提交 SHA，适用于 git 托管市场中的 github、url、git-subdir 和相对路径源
SHA-256 摘要，适用于 archive 源：市场条目中的 sha256 固定值，或当你未设置固定值时下载文件的摘要。Claude Code 将其缩短为前 12 个字符
unknown，适用于 npm 源或不在 git 仓库内的本地目录

对于 command 源，Claude Code 始终从命令生成的内容中派生版本：单独的 12 字符内容哈希，或在设置了版本时附加到 plugin.json 版本作为 <version>-<hash>。Claude Code 忽略命令源的市场条目中的 version 字段。因此，命令的哈希输出发生变化会产生新版本，即使编写的版本字符串保持不变。在 link mode 中，哈希覆盖打印目录的真实路径及其顶级条目，而不是文件内容。

对于这些源类型，这为你提供了三种版本控制插件的方式：

方法	如何操作	更新行为	最适合
显式版本	在 `plugin.json` 中设置 `"version": "2.1.0"`	用户仅在你更新此字段时获得更新。推送新提交而不更新它没有效果，`/plugin update` 报告"已是最新版本"。	具有稳定发布周期的已发布插件
提交 SHA 版本	从 `plugin.json` 和市场条目中都省略 `version`	每当源的已解析提交发生变化时，用户获得更新	正在积极开发的内部或团队插件
摘要版本	使用 `archive` 源并从 `plugin.json` 和市场条目中都省略 `version`	使用 `sha256` 固定值时，当你更改固定值时用户获得更新。没有固定值时，每当托管 zip 文件的字节发生变化时用户获得更新	作为 zip 文件发布到静态服务器或工件仓库的插件

如果你使用显式版本，请遵循 semantic versioning（MAJOR.MINOR.PATCH）：对于破坏性更改，增加 MAJOR；对于新功能，增加 MINOR；对于错误修复，增加 PATCH。在 CHANGELOG.md 中记录更改。

另请参阅

Plugins - 教程和实际用法
Plugin marketplaces - 创建和管理市场
Skills - Skill 开发详情
Subagents - Agent 配置和功能
Hooks - 事件处理和自动化
MCP - 外部工具集成
Settings - Plugins 的配置选项

plugins-reference.md +135 −67

121 121

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

123 123

124| Event | When it fires |124| 事件 | 触发时机 |

125| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |125| :-------------------- | :--------------------------------------------------------------------------------------------------------------------- |

127| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |127| `Setup` | 当你使用 `--init-only` 启动 Claude Code，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备 |

132| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |132| `PermissionDenied` | 当自动模式拒绝工具调用时，包括没有分类器判决的拒绝。使用 JSON `hookSpecificOutput.retry: true` 来告诉模型它可以重试被拒绝的工具调用。Claude Code 在分类器未产生判决时忽略 `retry` |

145| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |145| `InstructionsLoaded` | 当 CLAUDE.md 或 `.claude/rules/*.md` 文件被加载到上下文中时。在会话开始时和文件在会话期间被延迟加载时触发 |

147| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |147| `CwdChanged` | 当工作目录更改时，例如当 Claude 执行 `cd` 命令时。对于使用 direnv 等工具的反应式环境管理很有用 |

150| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |150| `WorktreeCreate` | 当通过 `--worktree`、`isolation: "worktree"` 创建工作树时，或用于后台会话。替换默认的 git 行为 |

159 159

160**Hook 类型**：160**Hook 类型**：

161 161

488 "lspServers": "./.lsp.json",488 "lspServers": "./.lsp.json",

489 "experimental": {489 "experimental": {

490 "themes": "./themes/",490 "themes": "./themes/",

491 "monitors": "./monitors.json"491 "monitors": "./monitors.json",

492 "evals": "quality/evals"

492 },493 },

493 "dependencies": [494 "dependencies": [

494 "helper-lib",495 "helper-lib",

564</h3>565</h3>

565 566

566| 字段 | 类型 | 描述 | 示例 |567| 字段 | 类型 | 描述 | 示例 |

567| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |568| :---------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

580| `dependencies` | array | 此 plugin 需要的其他 plugin，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖项版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |582| `dependencies` | array | 此 plugin 需要的其他 plugin，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖项版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

998claude plugin init <name> [options]1000claude plugin init <name> [options]

999```1001```

1000 1002

1001**参数：**1003该命令接受这些参数：

1002 1004

1003* `<name>`：插件名称。成为技能命名空间和 `~/.claude/skills/` 下的目录名称，因此不能包含空格或路径分隔符。1005* `<name>`：插件名称。成为技能命名空间和 `~/.claude/skills/` 下的目录名称，因此不能包含空格或路径分隔符。

1004 1006

1005**选项：**1007该命令接受这些选项：

1006 1008

1007| 选项 | 描述 | 默认值 |1009| 选项 | 描述 | 默认值 |

1008| :----------------------- | :--------------------------------------------------------------------------- | :---------------------- |1010| :----------------------- | :--------------------------------------------------------------------------- | :---------------------- |

1015 1017

1016**别名：** `new`1018`claude plugin new` 是此命令的别名。

1017 1019

1018每个 `--with` 值都会为该组件添加一个启动文件，准备好编辑：1020每个 `--with` 值都会为该组件添加一个启动文件，准备好编辑：

1019 1021

1029 1031

1030搭建的插件使用 `@skills-dir` 源而不是市场。管理员可以通过 `strictKnownMarketplaces` 或在 [managed settings](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) 中添加 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 来阻止此源。当被阻止时，`plugin init` 在写入前失败。1032搭建的插件使用 `@skills-dir` 源而不是市场。管理员可以通过 `strictKnownMarketplaces` 或在 [managed settings](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) 中添加 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 来阻止此源。当被阻止时，`plugin init` 在写入前失败。

1031 1033

1032**示例：**1034这些示例显示常见的调用：

1033 1035

1034```bash theme={null}1036```bash theme={null}

1035# 搭建最小插件1037# 搭建最小插件

1052claude plugin install <plugin> [options]1054claude plugin install <plugin> [options]

1053```1055```

1054 1056

1055**参数：**1057该命令接受这些参数：

1056 1058

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

1058 1060

1059**选项：**1061该命令接受这些选项：

1060 1062

1061| 选项 | 描述 | 默认值 |1063| 选项 | 描述 | 默认值 |

1062| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1064| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1065| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |1067| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |

1068| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，用于脚本。请参阅 [JSON result format](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 | |

1067 1070

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

1069 1072

1070**示例：**1073<span id="plugin-json-result" />使用 `--json`，stdout 的最后一行是一个 JSON 对象。仅解析该行，因为 Claude Code 会在其前面打印市场声明的任何命令。三个字段始终存在：

1074

1075* `command`：运行的子命令，例如 `install`

1076* `outcome`：`ok` 或 `failed`

1077* `message`：结果的人类可读描述

1078

1079其他字段，例如 `pluginId`、`scope` 和 `failureCode`，仅在适用时出现。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项打印具有该子命令自己字段的相同对象。使用错误，例如无效的 `--scope`，不打印结果行并以 stderr 上的原因退出 1。

1080

1081这些示例显示常见的调用：

1071 1082

1072```bash theme={null}1083```bash theme={null}

1073# 安装到用户范围（默认）1084# 安装到用户范围（默认）

1090claude plugin uninstall <plugin> [options]1101claude plugin uninstall <plugin> [options]

1091```1102```

1092 1103

1093**参数：**1104该命令接受这些参数：

1094 1105

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

1096 1107

1097**选项：**1108该命令接受这些选项：

1098 1109

1099| 选项 | 描述 | 默认值 |1110| 选项 | 描述 | 默认值 |

1100| :-------------------- | :------------------------------------------------------------ | :----- |1111| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----- |

1116| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。不能与 `--prune` 组合。需要 Claude Code v2.1.268 或更高版本 | |

1106 1118

1107**别名：** `remove`、`rm`1119`claude plugin remove` 和 `claude plugin rm` 是此命令的别名。

1108 1120

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

1110 1122

1122claude plugin prune [options]1134claude plugin prune [options]

1123```1135```

1124 1136

1125**选项：**1137该命令接受这些选项：

1126 1138

1127| 选项 | 描述 | 默认值 |1139| 选项 | 描述 | 默认值 |

1128| :-------------------- | :--------------------------------- | :----- |1140| :-------------------- | :--------------------------------- | :----- |

1133 1145

1134**别名：** `autoremove`1146`claude plugin autoremove` 是此命令的别名。

1135 1147

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

1137 1149

1145claude plugin enable <plugin> [options]1157claude plugin enable <plugin> [options]

1146```1158```

1147 1159

1148**参数：**1160该命令接受这些参数：

1149 1161

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

1151 1163

1152**选项：**1164该命令接受这些选项：

1153 1165

1154| 选项 | 描述 | 默认值 |1166| 选项 | 描述 | 默认值 |

1155| :-------------------- | :-------------------------------------------------------- | :--- |1167| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :--- |

1169| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |

1158 1171

1159<h3 id="plugin-disable">1172<h3 id="plugin-disable">

1166claude plugin disable [plugin] [options]1179claude plugin disable [plugin] [options]

1167```1180```

1168 1181

1169**参数：**1182该命令接受这些参数：

1170 1183

1171* `[plugin]`：插件名称或 `plugin-name@marketplace-name`。使用 `--all` 时可选1184* `[plugin]`：插件名称或 `plugin-name@marketplace-name`。使用 `--all` 时可选

1172 1185

1173**选项：**1186该命令接受这些选项：

1174 1187

1175| 选项 | 描述 | 默认值 |1188| 选项 | 描述 | 默认值 |

1176| :-------------------- | :-------------------------------------------------------- | :--- |1189| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :--- |

1192| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |

1180 1194

1181<h3 id="plugin-update">1195<h3 id="plugin-update">

1188claude plugin update <plugin> [options]1202claude plugin update <plugin> [options]

1189```1203```

1190 1204

1191**参数：**1205该命令接受这些参数：

1192 1206

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

1194 1208

1195**选项：**1209该命令接受这些选项：

1196 1210

1197| 选项 | 描述 | 默认值 |1211| 选项 | 描述 | 默认值 |

1198| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1212| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1200| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |1214| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |

1215| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |

1202 1217

1203<Note>1218<Note>

1216claude plugin list [options]1231claude plugin list [options]

1217```1232```

1218 1233

1219**选项：**1234该命令接受这些选项：

1220 1235

1221| 选项 | 描述 | 默认值 |1236| 选项 | 描述 | 默认值 |

1222| :------------ | :--------------------- | :-- |1237| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |

1226 1241

1242claude plugin details <name>1257claude plugin details <name>

1243```1258```

1244 1259

1245**参数：**1260该命令接受这些参数：

1246 1261

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

1248 1263

1249**选项：**1264该命令接受这些选项：

1250 1265

1251| 选项 | 描述 | 默认值 |1266| 选项 | 描述 | 默认值 |

1252| :----------- | :----- | :-- |1267| :----------- | :----- | :-- |

1297claude plugin validate <path> [options]1312claude plugin validate <path> [options]

1298```1313```

1299 1314

1300**参数：**1315该命令接受这些参数：

1301 1316

1302* `<path>`：插件目录或市场目录的路径。请参阅 [Validate a plugin or a directory without a manifest](/docs/zh-CN/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) 了解插件运行涵盖的文件。1317* `<path>`：插件目录或市场目录的路径。请参阅 [Validate a plugin or a directory without a manifest](/docs/zh-CN/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) 了解插件运行涵盖的文件。

1303 1318

1304**选项：**1319该命令接受这些选项：

1305 1320

1306| 选项 | 描述 | 默认值 |1321| 选项 | 描述 | 默认值 |

1307| :----------- | :---------------------------------------------------------------------------------- | :-- |1322| :----------- | :---------------------------------------------------------------------------------- | :-- |

1321 1336

1322在交互式会话中，`/plugin validate <path>` 内联运行相同的检查。1337在交互式会话中，`/plugin validate <path>` 内联运行相同的检查。

1323 1338

1339<h3 id="plugin-eval">

1340 plugin eval

1341</h3>

1342

1343运行插件的 [eval cases](/docs/zh-CN/plugin-evals) 并报告评分结果。需要 Claude Code v2.1.269 或更高版本。每个案例都是一个提示加评分器；Claude Code 在隔离会话中运行它多次，仅加载目标插件，默认情况下也不加载插件，以便报告显示差异。请参阅 [Test plugins with evals](/docs/zh-CN/plugin-evals) 了解案例格式、评分器、结果和 CI 使用。

1344

1345```bash theme={null}

1346claude plugin eval [target] [options]

1347```

1348

1349可选的 `target` 是一个插件目录、单个 `prompt.md` 或 `case.yaml` 文件、已安装的插件作为 `name` 或 `name@marketplace`，或 `name@skills-dir`，默认为当前目录。将其放在 `--tag`、`--allow-tools` 和 `--json` 之前。

1350

1351此表列出大多数运行使用的选项。运行 `claude plugin eval --help` 以获取完整集合，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。

1352

1353| 选项 | 描述 | 默认值 |

1354| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

1355| `--runs <n>` | 每个案例每个分支的运行次数 | 每个案例的 `runs`，否则 3 |

1356| `-j, --concurrency <n>` | 一次运行的代理会话数，1 到 8。它们共享您的速率限制 | `1` |

1357| `--model <model>` | 被测试代理的模型 | 每个案例的 `model`，否则 `ANTHROPIC_MODEL`（如果设置），否则 Claude Code 的默认值 |

1358| `--judge-model <model>` | `llm` 和 `baseline` 评分器的模型 | 一个小的快速模型 |

1359| `--ablation <mode>` | `none` 或 `with-without`。请参阅 [Compare against a no-plugin baseline](/docs/zh-CN/plugin-evals#compare-against-a-no-plugin-baseline) | 当插件解析时为 `with-without`，否则为 `none` |

1360| `--threshold <0..1>` | 如果任何案例评分低于此值则退出 1 | `1.0` |

1361| `--max-cost-usd <usd>` | 一旦支出达到此值就停止下一次运行，退出 2，并报告部分结果 | 无上限 |

1362| `--allow-tools <tools...>` | 授予超出只读集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅 [Grant tools](/docs/zh-CN/plugin-evals#grant-tools) | |

1363| `--scaffold` | 运行每个案例的 [`scaffold_script`](/docs/zh-CN/plugin-evals#add-setup-or-history-with-case-yaml) | 关闭 |

1364| `--trust-plugin` | 跳过首次运行信任提示，用于 CI。请参阅 [What a run can access](/docs/zh-CN/plugin-evals#security) | 关闭 |

1365| `--mocks <mode>` | `record` 或 `off`。请参阅 [Mock MCP servers](/docs/zh-CN/plugin-evals#mock-mcp-servers) | `record` |

1366| `--eval-dir <dir>` | 保存案例的插件下方的目录 | 清单的 `experimental.evals`，否则 `evals` |

1367| `--json [path]` | 将 [result document](/docs/zh-CN/plugin-evals#json-result) 打印到 stdout，或将其写入 `.json` 路径 | |

1368| `--no-publish` | 保持 HTML 报告本地 | |

1369| `-h, --help` | 显示命令帮助 | |

1370

1371当每个案例都满足阈值时命令退出 0，在失败案例、加载错误或不受信任的插件目录时退出 1，在部分运行时退出 2，中断时退出 130，终止时退出 143。请参阅 [Run evals in CI](/docs/zh-CN/plugin-evals#run-evals-in-ci)。

1372

1373<h3 id="plugin-eval-init">

1374 plugin eval init

1375</h3>

1376

1377为当前目录中的插件创建一个 eval 套件。需要 Claude Code v2.1.269 或更高版本。在终端中，这会启动一个创作访谈，读取插件、提议案例和评分器、试验它们并写入文件。使用 `--bare`，或没有终端时，它会写入一个空白的单案例模板。从交互式 Claude Code 会话内运行，它会打印该会话要遵循的访谈说明，而不是写入模板。请参阅 [Create your first eval suite](/docs/zh-CN/plugin-evals#create-your-first-eval-suite)。

1378

1379```bash theme={null}

1380claude plugin eval init [name] [options]

1381```

1382

1383可选的 `name` 是一个案例名称：访谈不需要一个，而 `--bare` 和无终端模板路径需要一个。它接受这些选项：

1384

1385| 选项 | 描述 | 默认值 |

1386| :------------------ | :------------------------------------------------------------- | :---------------------------------- |

1387| `--bare` | 为 `<name>` 写入一个空白的 `prompt.md` 和 `graders/criteria.md`，而不是运行访谈 | |

1388| `-i, --interactive` | 需要访谈。没有终端时失败，而不是写入模板 | |

1389| `--eval-dir <dir>` | 当前目录下方写入案例的目录 | 清单的 `experimental.evals`，否则 `evals` |

1390| `-h, --help` | 显示命令帮助 | |

1391

1324<h3 id="plugin-tag">1392<h3 id="plugin-tag">

1325 plugin tag1393 plugin tag

1326</h3>1394</h3>

1331claude plugin tag [path] [options]1399claude plugin tag [path] [options]

1332```1400```

1333 1401

1334**参数：**1402该命令接受这些参数：

1335 1403

1336* `[path]`：插件目录的路径。默认为当前目录。1404* `[path]`：插件目录的路径。默认为当前目录。

1337 1405

1338**选项：**1406该命令接受这些选项：

1339 1407

1340| 选项 | 描述 | 默认值 |1408| 选项 | 描述 | 默认值 |

1341| :-------------------- | :---------------------- | :------- |1409| :-------------------- | :---------------------- | :------- |

plugins-reference.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

Plugins 参考

插件组件参考

Skills

Agents

Hooks

MCP servers

LSP servers

Monitors

Themes

Plugin 安装作用域

Skills-directory plugins

选择 plugin 从哪里加载

编辑、重新加载和禁用 skills-directory plugin

从 claude.ai 同步的插件

Plugin manifest schema

Complete schema

必需字段

无法识别的字段

元数据字段

默认启用

组件路径字段

实验性组件

用户配置

频道

路径行为规则

环境变量

持久数据目录

Plugin 缓存和文件解析

Node.js 包依赖

路径遍历限制

使用符号链接在 marketplace 内共享文件

Plugin 目录结构

标准 plugin 布局

文件位置参考

CLI 命令参考

plugin init

plugin install

plugin uninstall

plugin prune

plugin enable

plugin disable

plugin update

plugin list

plugin details

plugin validate

plugin eval

plugin eval init

plugin tag

调试和开发工具

调试命令

常见问题

示例错误消息

Hook 故障排除

MCP 服务器故障排除

目录结构错误

分发和版本管理参考

版本管理

另请参阅