插件命令参考

claude plugin shell 命令、会话中的 /plugin 和 /reload-plugins 的参考，以及在一个会话中加载插件的标志。

您可以从 shell 或脚本中以 claude plugin 的形式运行 plugin 命令，或在 Claude Code 会话中以 /plugin 和 /reload-plugins 的形式运行。本参考给出每个命令的标志、默认值、输出和退出代码，以及在一个会话中加载 plugin 的两个标志。

下表列出了每个子命令的常用选项，而非全部选项。在 shell 中运行 claude plugin --help 可查看您的版本具有哪些子命令，运行 claude plugin <subcommand> --help 可查看某个子命令的完整选项列表。

[!NOTE]

这些情况在其他页面上有介绍：

• 安装和管理步骤，以及 /plugin 运行的位置：请参阅 安装和管理 plugins
• 命令在磁盘上更改的内容以及哪个作用域优先：请参阅 Plugin 加载参考
• 错误消息的含义：请参阅 Plugin 故障排除

claude plugin 命令

在 Claude Code 会话之外，从 shell 或脚本中运行 claude plugin <subcommand>。这些子命令无需打开 /plugin 面板即可安装和管理插件。

claude plugins 是 claude plugin 的别名。

所有子命令共用以下退出码、插件参数和作用域值：

• 退出码：成功时为 0，失败时为 1。validate 额外使用退出码 2 表示意外错误，eval 额外使用其章节中列出的退出码。
• 插件参数：<plugin> 参数是插件的 name 或 name@marketplace。当两个市场提供同名插件时，请使用限定形式。configure 只接受限定形式。
• 作用域：--scope 接受 user、project 或 local，用于指定命令写入的设置文件。update 还接受 managed。

plugin init

在 ~/.claude/skills/<name>/ 下生成一个新插件的脚手架。除非您的管理员已阻止 skills 目录插件，否则它会在您的下一个会话中以 <name>@skills-dir 的形式加载，无需安装步骤。

new 是 init 的别名。

有关从此命令开始的创建、测试和编辑工作流，请参阅创建插件。

claude plugin init <name> [options]

<name> 会成为 ~/.claude/skills/ 下的目录名，以及插件清单中的 name。

该命令没有用于指定其他位置的标志。如需改为在项目内生成脚手架，请参阅创建插件。

生成一个带有起始 skill 和 hook 文件的插件：

claude plugin init my-helper --with skills hooks

Claude Code 会验证它写入的内容，并打印 Created plugin "my-helper" at ~/.claude/skills/my-helper，随后显示该插件加载时使用的 id，以及用于关闭它的 claude plugin disable 命令。

当 Claude Code 无法安全地生成脚手架时，它会以 1 退出且不写入任何内容，消息中会说明原因。常见原因如下：

• 未知的 --with 值
• 目标位置已有脚手架但未使用 --force
• 托管的市场允许列表中不包含 skills-dir 来源，或拒绝列表中列出了它。此时的消息为 Plugins from ~/.claude/skills/ are blocked by your organization's managed settings。

plugin install

从您的某个市场安装插件。i 是 install 的别名。

claude plugin install <plugin> [options]

大多数插件安装时不会弹出提示。对于市场条目通过运行命令来安装或为下载设置了 headersHelper 的插件，Claude Code 会先打印该命令并询问 Run this command now? [y/N]。

在 shell 中运行 claude plugin install --help，查看您的版本支持的所有选项。

从您自己的终端传入 -y，即可接受显示的命令而不弹出提示。以下是没有 TTY 时以及由 Claude 运行该命令时的情况：

• stdin 或 stdout 不是 TTY，且您既未传入 -y 也未传入 --accept-command：安装被拒绝。输出会说明该命令仅被显示，退出码为 1
• Claude 通过其 Bash 工具运行该命令：-y 被忽略。请改为从您自己的终端运行该命令

如需与克隆该项目的所有人共享插件，请使用 --scope project 运行 claude plugin install 并提交 .claude/settings.json。然后让每个人在自己的克隆中添加该市场并运行相同的命令：

claude plugin install formatter@my-marketplace --scope project

Claude Code 会打印 Successfully installed plugin: formatter@my-marketplace (scope: project)。当没有安装任何新内容时，输出会说明原因：

• 已在该作用域安装：输出为 Plugin "formatter@my-marketplace" is already installed (scope: project)，退出码为 0
• 您拒绝了命令来源提示：输出为 Aborted.，退出码为 1
• 您拒绝了 headersHelper 提示，或在没有 TTY 的情况下无法确认：输出为 Aborted — the command was not run.，退出码为 1

JSON 结果格式

当您向 plugin install 传入 --json 时，stdout 的最后一行是一个 JSON 对象。请只解析这一行，因为 Claude Code 会在它之前打印市场声明的任何命令。

以下三个字段始终存在：

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

其他字段（例如 pluginId、scope 和 failureCode）仅在适用时出现。

plugin uninstall、plugin update、plugin enable 和 plugin disable 上的 --json 选项会打印相同的对象，并带有该子命令自己的字段。

用法错误（例如无效的 --scope）不会打印结果行，而是以 1 退出，并在 stderr 上输出原因。

市场命令的 JSON 结果

在 plugin marketplace add、plugin marketplace remove 和 plugin marketplace update 上，--json 会在 stdout 的最后一行打印一个 JSON 对象，其中包含 command、outcome 和 message 字段。以下是 claude plugin marketplace remove your-marketplace --json 的结果：

{"command":"marketplace-remove","outcome":"ok","marketplace":"your-marketplace","message":"Successfully removed marketplace: your-marketplace"}

command 的值为 marketplace-add、marketplace-remove 或 marketplace-update。以下字段仅在适用时出现：

• marketplace：命令所作用的市场名称
• failureCode：表示命令失败原因的代码，例如 invalid_source

当参数是保留名称 anthropic-plugin-directory 时，plugin marketplace add 和 plugin marketplace remove 可能不打印结果行，因此对于该名称请检查退出码。

接受已显示的安装命令

当某次 --json 运行显示了市场声明的命令但没有运行它时，failed 结果中还会带有一个 shownCommand 对象。它的字段包括所显示的命令、该命令所属的插件，以及该命令的 sha256。

如需准确接受该命令，请从您自己的终端重新运行，并将该 sha256 作为 --accept-command 传入，因为该标志在 Claude Code 会话内不起作用。需要 Claude Code v2.1.271 或更高版本。

该 sha256 仅对完全相同的命令、插件和市场目录视为接受。如果自命令显示以来其中任何一项发生了变化，Claude Code 将不接受该 sha256，并再次显示该命令。本次运行自身的市场刷新所获取到的变化也算作此类变化。

如果 shownCommand.acceptCommandMatched 为 false，说明您传入的 sha256 与当前显示的命令不匹配。请先审查该命令，再使用其 sha256 重新运行。

plugin uninstall

从某个作用域中移除已安装的插件。remove 和 rm 是 uninstall 的别名。

claude plugin uninstall <plugin> [options]

从项目作用域卸载插件：

claude plugin uninstall formatter@my-marketplace --scope project

Claude Code 会打印 Successfully uninstalled plugin: formatter (scope: project)。当插件未在该作用域安装时，命令会打印一行以 Failed to uninstall plugin "formatter@my-marketplace": 开头的内容，并以 1 退出。

如果失败行后面接着 "formatter" was not uninstalled: 并指出某个设置文件，说明 Claude Code 无法确认该作用域的设置不再启用该插件，因此该插件及其保存的所有内容仍保持安装状态。使用 --json 时，结果中带有 failureCode: "settings_still_on"。此设置检查需要 Claude Code v2.1.282 或更高版本。

卸载会删除和保留的内容

当您从插件安装的最后一个作用域卸载该插件时，Claude Code 还会删除该插件存储的选项和密钥以及其数据目录 ~/.claude/plugins/data/<id>/。有三种例外情况：

• 使用 --keep-data 时，数据目录会保留
• 当另一个已安装的插件使用同一文件夹时（例如 ID 与此插件仅在字母大小写上不同的插件），数据目录会保留
• 当 Claude Code 从该作用域移除插件后无法读回已安装插件列表时，选项、密钥和数据目录都会保留，因为该插件可能仍安装在另一个作用域。卸载仍然成功。消息会列出保留了哪些内容以及如何删除它们，使用 --json 时，结果中带有 savedKept: "install_records_unreadable"

使用 --json 时，keptData 会报告目录是否保留，保留时 /plugin 会显示 · data preserved。对于未使用 --keep-data 却被保留的目录，此报告需要 Claude Code v2.1.281 或更高版本。savedKept 字段需要 Claude Code v2.1.282 或更高版本。

plugin enable

启用已禁用的插件。对于从 claude.ai 同步的插件，请传入 <name>@synced 作为插件。

claude plugin enable <plugin> [options]

不带 --scope 时，命令会按 local、project、user 的顺序检查您的设置文件，并使用第一个提及该插件的作用域。

如果您传入的 --scope 中未声明该插件，命令要么写入一个覆盖，要么失败：

• 优先级高于声明所在作用域的作用域：Claude Code 在您传入的作用域写入覆盖。例如，claude plugin disable formatter --scope local 仅为您自己关闭一个在项目中启用的插件
• 任何其他作用域：命令失败，并输出 Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.

如果插件在解析出的作用域中已启用，命令会打印 Plugin "formatter" is already enabled 并以 1 退出。使用 --json 时，结果中带有 "failureCode": "already_in_goal_state" 和 "alreadyInGoalState": true，因此脚本可以将这种情况视为成功。

当插件声明了依赖时，Claude Code 也会启用它们。以下情况命令会失败：

• 某个依赖未安装：启用失败，并为每个缺失的依赖打印 claude plugin install 命令
• 某个依赖被您组织的插件策略阻止：启用失败，并指出被阻止的依赖
• 某个依赖在优先级高于目标作用域的作用域中被设为 false：启用失败。请在该作用域启用该依赖，或传入 --scope 写入该作用域

在插件声明所在的位置重新启用它：

claude plugin enable formatter

Claude Code 会打印 Successfully enabled plugin: formatter (scope: project)，其中指出它检测到的作用域。

plugin disable

禁用插件而不卸载它。对于从 claude.ai 同步的插件，请传入 <name>@synced 作为插件。

claude plugin disable [plugin] [options]

不带 --scope 时，作用域按照与 plugin enable 相同的 local、project、user 顺序自动检测。

如果您既未传入插件名称也未传入 --all，Claude Code 会打印 Please specify a plugin name or use --all to disable all plugins 并以 1 退出。禁用一个已禁用的插件会打印 Plugin "formatter" is already disabled 并以 1 退出，这与 plugin enable 对已启用插件的处理方式相同。

对于仍被需要的插件，命令会失败：

• 另一个已启用的插件依赖它：命令失败，并指出需要先禁用的依赖方
• 您的组织要求将其作为同步插件：命令失败，且不保存任何内容

禁用一个插件：

claude plugin disable formatter

Claude Code 会打印 Successfully disabled plugin: formatter (scope: project)。

plugin update

将插件更新到其市场提供的最新版本。新版本会在您的下一个会话中加载，或在正在运行的会话中运行 /reload-plugins 后加载。

claude plugin update <plugin> [options]

更新插件：

claude plugin update formatter@my-marketplace

Claude Code 会打印 Checking for updates for plugin "formatter@my-marketplace"…，然后打印结果。当没有更新的版本时，它会打印 formatter is already at the latest version (1.0.0). 并以 0 退出，除非它重试该插件的依赖安装且该安装失败。

命令更新哪个作用域

如果您省略 --scope，命令会按 local、project、user、managed 的顺序检查，在当前项目中该插件安装所在的最具体作用域进行更新。

在 v2.1.281 之前，省略 --scope 时命令使用 user，因此更新仅安装在项目或本地作用域的插件会失败，并输出 Plugin "<name>" is not installed at scope user。在这些版本上，请传入 --scope。

managed 是唯一可以更新但不能安装到的作用域。有关管理员安装的插件，请参阅为您的组织管理插件。

按裸名称更新

您可以传入裸插件名称，命令会将其与您已安装的插件进行匹配。当来自不同市场的已安装插件同名时，命令会拒绝更新，并列出应改为运行的限定形式 plugin-name@marketplace-name 命令。按裸名称更新需要 Claude Code v2.1.246 或更高版本。

重试未完成的依赖安装

当插件已是最新版本时，命令还可以在其缓存副本中重试未完成的依赖安装。有关该重试何时运行或被跳过，请参阅它列出的包未安装。如果重试失败，输出为 Failed to update plugin "formatter@my-marketplace" 及原因，退出码为 1。在 v2.1.287 之前，命令会报告插件已是最新版本，而不会重试安装。

plugin list

列出已安装的插件及其版本、作用域和状态。

claude plugin list [options]

Claude Code 会按每个插件的加载方式对人类可读输出进行分组：

• Installed plugins:：您从市场安装的插件
• Session-only plugins (--plugin-dir / --plugin-url):：由同一命令中的这些标志加载的插件，例如 claude --plugin-dir ./my-plugin plugin list
• Skills-directory plugins (.claude/skills/*):：Claude Code 在 skills 目录中找到的插件
• Synced from claude.ai：从您的 claude.ai 账户同步的插件

当所有分组都为空时，Claude Code 会打印 No plugins installed. Use `claude plugin install` to install a plugin.

JSON 输出

使用 --json 时，Claude Code 会打印一个数组，每次安装对应一个对象。每个对象带有以下字段。id、version、scope、enabled 和 installPath 始终存在，其他字段仅在适用时出现。

使用 --json --available 时，Claude Code 会打印一个对象而不是数组。其 installed 字段包含已安装插件对象的数组，其 available 字段为每个未安装的市场插件包含一个对象，带有以下字段。

plugin details

显示插件的组件清单及其预计 token 开销。

插件必须已加载：已安装、在 skills 目录中找到，或在同一命令中通过 --plugin-dir 或 --plugin-url 传入。<name> 是插件的 name 或 name@marketplace。

claude plugin details <name>

该命令除 --help 外不接受其他标志。

显示已安装插件提供的内容：

claude plugin details formatter

Claude Code 会打印插件的名称、版本、描述和来源，然后是以下部分：

• Component inventory：插件的 skill、Agent、hook、MCP 服务器和 LSP 服务器
• Projected token cost：插件为每个会话增加的常驻 token
• Per-component (rounded)：每个 skill、Agent 和命令的常驻和调用时估算值。插件没有这些组件时省略

有关这两个开销数值的含义，请参阅衡量插件开销和使用情况。

对于未加载的插件，Claude Code 会打印以下消息并以 1 退出：

Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.

以 @builtin 结尾的 ID 指向某个 Claude Code 内置插件。如果您传入这样的 ID 而 Claude Code 找不到该插件，消息会改为：

Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.

plugin configure

显示已安装插件的 userConfig 选项以及哪些已设置，或保存通过 stdin 传入的值。需要 Claude Code v2.1.285 或更高版本。

claude plugin configure <plugin>

不带标志时，命令会列出每个选项，最多附带三个标签：required 或 optional，然后是清单声明为敏感的选项的 sensitive，然后是 set 或 not set。它不打印任何已保存的值。使用 --json 时，输出包含非敏感选项的已保存值，但绝不包含敏感选项的文本。

如需保存值，请将它们写入一个文件，内容为将选项键映射到字符串值的 JSON 对象，然后通过 stdin 传入该文件。请将 formatter@my-marketplace 替换为 claude plugin list 所显示的您自己插件的 id。以下示例从内容为 {"api_url": "https://example.com"} 的文件 values.json 中设置一个名为 api_url 的选项：

claude plugin configure formatter@my-marketplace --values-stdin < values.json

Claude Code 会根据选项声明的类型验证每个值，并打印 Configuration saved. Restart Claude Code to apply it.。如果您传入了清单未声明的键，或者某个值未通过验证，命令将不保存任何内容，打印 Failed to save configuration: 及原因，并以 1 退出。使用 --json 时，被拒绝的值还会在 stdout 上打印一个对象，其 refused 字段带有 message，以及当某一个选项出错时该选项的 option 键。

请传入插件完整的 name@marketplace id，即 claude plugin list 所显示的形式。configure 不接受裸 name。当没有已加载的插件具有该 id 时，命令会打印 No installed plugin has the id "<plugin>". 并以 1 退出。

有关捆绑 MCP 服务器的设置，请参阅 plugin install --config 或 /plugin 中的 Configure 项。

plugin prune

移除不再被任何已安装插件需要的自动安装的依赖。该命令绝不会移除您自己安装的插件。autoremove 是 prune 的别名。

claude plugin prune [options]

预览清理将移除的内容：

claude plugin prune --dry-run

Claude Code 会列出孤立的依赖，并以 (dry run — nothing removed) 结尾。没有需要移除的内容时，它会打印一行以 Nothing to prune 开头的内容。

不带 --dry-run 时，命令仅在您于提示处确认或传入 -y 后才移除孤立的依赖。

无论您在提示处如何回答，退出码都是 0。

prune 的行为取决于是否连接了终端以及您是否传入 -y：

plugin eval

运行插件的 eval 用例并报告评分结果。需要 Claude Code v2.1.269 或更高版本。

每个用例由一个提示词加若干评分器组成。Claude Code 会在仅加载目标插件的隔离会话中多次运行它，默认还会在不加载该插件的情况下运行，以便报告显示两者的差异。

有关用例格式、评分器、结果和 CI 用法，请参阅使用 eval 测试插件。

claude plugin eval [target] [options]

可选的 target 默认为当前目录，可采用以下任一形式：

• 插件目录
• 单个 prompt.md 或 case.yaml 文件
• 以 name 或 name@marketplace 形式给出的已安装插件
• name@skills-dir

请将 target 放在 --tag、--allow-tools 和 --json 之前。这些选项都会把其后的单词作为自己的值，因此写在它们之一之后的 target 会被当作标签、工具名称或 JSON 输出路径，而不是 target。

下表列出了大多数运行所使用的选项。运行 claude plugin eval --help 查看完整选项集，包括 --case、--tag、--output-dir、--report、--allow-real-servers、--keep-temp 和 --verbose。

退出码报告运行的结束方式。如需在流水线中据此采取行动，请参阅在 CI 中运行 eval。

plugin eval init

为当前目录中的插件创建 eval 套件。需要 Claude Code v2.1.269 或更高版本。请参阅创建您的第一个 eval 套件。

claude plugin eval init [name] [options]

请从插件的根文件夹运行该命令，即包含 .claude-plugin/plugin.json 或 skill 的 SKILL.md 的目录。如需有意在另一个目录中生成套件，请传入 --eval-dir。

在终端中，该命令会打开一个交互式 Claude Code 会话进行编写访谈。在访谈中，Claude 会执行以下操作：

1. 阅读插件
2. 询问您它应该擅长什么
3. 提出用例和评分器
4. 编写用例文件
5. 运行用例并与您一起审查评分，以检查评分器的评分方式是否与您一致

使用 --bare 或没有终端时，该命令会改为写入一个空白的单用例模板。当 Claude 在 Claude Code 会话内运行该命令时，命令会打印供该会话遵循的访谈说明，而不是写入模板。

可选的 name 是用例名称。使用 --bare 或没有终端时它是必需的，因为命令会为该用例写入空白模板。用例名称以字母或数字开头，且只能包含字母、数字、.、_ 和 -。在所有平台上，命令还会拒绝 Windows 无法存储的名称，例如 con 或以 . 结尾的名称。

该命令接受以下选项：

plugin tag

为插件发布创建一个名为 <name>--v<version> 的附注 git 标签。在打标签之前，命令会检查插件的 plugin.json 与列出它的任何市场条目在版本上是否一致。

有关何时为发布打标签，请参阅发布插件。

claude plugin tag [path] [options]

[path] 是插件目录，默认为当前目录。命令会从该目录向上查找列出该插件的 .claude-plugin/marketplace.json，以找到市场条目。

在市场检出中预览插件的标签：

claude plugin tag plugins/formatter --dry-run

Claude Code 会打印计划：

• 插件名称
• 版本及其来源文件
• 匹配的市场条目（如果有）
• 标签名称
• 它将运行的 git tag 和 git push 命令

不带 --dry-run 时，Claude Code 会打印 Created tag formatter--v1.0.0，以及 Pushed to origin 或需要您自己运行的推送命令。如果推送失败，标签仍会在本地创建，命令会以错误退出。

当无法安全地打标签时，命令会以 1 退出并打印原因。常见原因如下：

• plugin.json 或市场条目中没有 version
• 标签已存在
• 工作树有未提交的更改

plugin test

运行 mod（一种其代码会注册事件处理程序的插件）的测试。该命令不需要会话、登录或网络。有关如何编写测试，请参阅测试 mod。

claude plugin test [directory]

[directory] 是 mod 的目录，默认为当前目录。命令会运行该目录下所有名称以 .test.ts 或 .test.tsx 结尾的文件，当有测试失败时以状态 1 退出。

运行 ./first-mod 中 mod 的测试：

claude plugin test ./first-mod

plugin validate

验证插件清单、市场清单，或某个目录中的 skill、Agent 和命令，并以 CI 作业可据以行动的退出码退出。有关创建、测试和编辑工作流，请参阅创建插件。有关验证器在每种清单中检查的内容，请参阅插件清单参考和市场参考。

claude plugin validate <path> [options]

在提交插件之前验证它：

claude plugin validate ./my-plugin --strict

验证目录

<path> 是清单文件或目录。给定目录时，Claude Code 会根据在其中找到的内容选择要验证的对象：

• .claude-plugin/marketplace.json（如果存在）
• 否则为 .claude-plugin/plugin.json
• 否则为组件文件，根据目录名称选择。在没有清单的情况下验证组件文件需要 Claude Code v2.1.233 或更高版本：
  • 名为 skills、agents 或 commands 的目录：其中的文件
  • 名为 .claude 的目录：其中的 skills、agents 和 commands 目录
  • 任何其他目录：其 .claude 下的这三个目录

当目录同时包含 .claude-plugin/marketplace.json 和 .claude-plugin/plugin.json 时，Claude Code 会验证市场，同时也验证插件的清单和组件文件。这需要 Claude Code v2.1.289 或更高版本。

Claude Code 不会跟随您指定的目录内的符号链接。其行为取决于链接所在的位置：

• 插件或 .claude 根目录下链接的 skills、agents 或 commands 目录：Claude Code 会警告其中的内容均未被读取。
• skills、agents 或 commands 目录内的链接条目：Claude Code 会跳过它，并按目录警告跳过了多少个会话本会加载的条目。
• 您指定的 skills、agents 或 commands 目录本身是符号链接，或其父级 .claude 目录是符号链接：Claude Code 会报告错误且不检查其中任何内容。请改为指定真实目录。

有几类文件不会被验证运行读取：

• 插件根目录下的 SKILL.md：当您针对插件目录运行 claude plugin validate 时，Claude Code 不会检查插件根目录下的 SKILL.md
• 插件根目录下的 CLAUDE.md：在插件运行中，Claude Code 还会对插件根目录下的 CLAUDE.md 发出警告
• 市场运行中的插件文件：从市场目录运行时，Claude Code 不会打开市场所列出的、位于其他目录中的插件的 skill、Agent、命令或 hook 文件，也不会打开它们捆绑的 MCP 服务器文件。如需查找这些文件中的错误，请验证每个插件目录

验证清单文件

当文件名不是 plugin.json 或 marketplace.json 且不在 .claude-plugin 目录中时，Claude Code 会根据其字段判断它是什么。在以下情况下，它将该文件作为市场验证，否则作为插件清单验证：

• plugins 是数组
• plugins 和 owner 同时存在
• 文件包含仅 marketplace.json 定义的字段（例如 owner），且不包含仅 plugin.json 定义的字段（例如 author）

如需自行选择检查类型，请将文件命名为 plugin.json 或 marketplace.json。Claude Code 会将 .claude-plugin 目录中的任何其他文件作为插件清单验证。

输出和退出码

Claude Code 会打印它验证的文件、所有错误和警告及其路径，以及一行结论。退出码与结论一致：

使用 --json 时，Claude Code 会将报告以一个 JSON 对象写入 stdout，包含以下顶层字段：

• success：与退出码给出的结论相同
• strict：本次运行是否将警告视为错误
• target：Claude Code 验证的解析后路径
• manifest：清单自身的结果，对于没有清单的运行为 null
• contents：每个文件的结果，每项指出其 file，并带有 errors、warnings 和 notes 数组。没有错误、警告或备注的文件不会有条目，因此没有可报告内容时 contents 为空。对于同时包含 marketplace.json 和 plugin.json 的目录，manifest 是 marketplace.json 的结果，plugin.json 的结果放在 contents 中
  • gatingHooks：每个可以拒绝操作的 mod hook（例如 tool.call hook）是否有 .catch 处理程序。每项给出 module、pattern、hook 和 hasCatch。需要 Claude Code v2.1.290 或更高版本
• advice：本次运行的建议，每个条目以 file 指出 README，并带有 message 和可粘贴的 installLine。没有建议时为空。需要 Claude Code v2.1.295 或更高版本

以 2 退出时，命令不会向 stdout 写入任何内容。错误消息输出到 stderr。

关于 README 的建议

claude plugin validate 输出中的 Advice 块表示插件的 README 中没有从市场安装该插件的行，并会给出一行供您添加。建议不是错误也不是警告。无论是否使用 --strict，它都不会改变结论行或退出码。它需要 Claude Code v2.1.295 或更高版本。

例如，验证 acme-tools 市场的目录时，会为其 deploy-helper 插件打印以下建议：

Validating marketplace manifest: /path/to/acme-tools/.claude-plugin/marketplace.json

ℹ Advice (does not change the verdict):

  ❯ /path/to/acme-tools/plugins/deploy-helper/README.md: This README has no line that installs "deploy-helper" from a marketplace. Add the install line, which works in one step on Claude Code 2.1.275 or later.
      /plugin install deploy-helper --marketplace acme/tools

✔ Validation passed

如需清除该建议，请将建议的行粘贴到它所指出的 README 中，然后在 shell 中再次运行 claude plugin validate。Advice 块就会消失。

如果建议的行包含占位符 <owner>/<repo>，原样粘贴并不能清除建议。请先获取真实来源：

• 您验证的是插件自身的目录：当市场从其自身目录内的某个目录列出该插件时，请改为验证该目录。当市场从其他位置（例如 GitHub 仓库）列出该插件时，请自行填写 <owner>/<repo>
• 您验证的是市场的目录：Claude Code 会根据该目录顶层 .git 目录的 origin 远程填入来源。当它无法使用该远程时（例如不存在该远程），请自行将 <owner>/<repo> 替换为您市场的来源

当 plugin install 或其简写形式 plugin i 在同一行后面跟着以下任一内容时，您已经编写的安装行即被视为有效。/plugin 和 claude plugin 两种写法都有效：

• <plugin>@<marketplace>，例如 /plugin install deploy-helper@acme-tools
• 插件名称和 --marketplace <source>，例如 /plugin install deploy-helper --marketplace acme/tools

claude plugin marketplace 命令

从您的 shell 运行 claude plugin marketplace <subcommand> 来添加、列出、刷新和移除您安装插件的市场。

• 退出码：这些子命令遵循插件命令的退出码约定
• 作用域：它们的 --scope 标志没有 -s 短形式

关于市场是什么以及 Claude Code 如何缓存它，请参阅插件加载参考。

plugin marketplace add

从 GitHub 仓库、git URL、托管的 marketplace.json 或本地路径添加市场，并在设置文件中声明它。

添加后，Claude Code 会安装您已安装的插件缺失的任何依赖项。

claude plugin marketplace add <source> [options]

<source> 采用下表中的任何形式，其形式决定了源类型以及 Claude Code 如何获取市场。关于生成的源对象，请参阅市场参考。

对于克隆 URL 不带 .git 后缀的主机（如 AWS CodeCommit），请改为在 extraKnownMarketplaces 中将市场添加为 git 条目。Claude Code 克隆 git 条目，无论其 URL 是否以 .git 结尾。

Claude Code 也克隆具有嵌套子组的 gitlab.com URL，例如 https://gitlab.com/group/subgroup/project。

添加市场并与项目共享：

claude plugin marketplace add your-org/your-marketplace --scope project

Claude Code 打印 Successfully added marketplace: your-marketplace (declared in project settings)，使用市场自己清单中的 name。重复添加或无效源会改为打印以下结果之一：

• 市场已在磁盘上：输出为 Marketplace 'your-marketplace' already on disk — declared in project settings，退出码为 0
• 无法识别的源：输出为 Invalid marketplace source format. Try: owner/repo, https://..., or ./path，退出码为 1
• 裸主机，如 gitlab.example.com/team/plugins：添加失败，作为无效的 owner/repo 简写，消息告诉您添加 https:// 或使用本地路径

通过 claude plugin marketplace list 的 From claude.ai: 部分中打印的名称添加托管在 claude.ai 上的市场：

claude plugin marketplace add --claudeai claudeai-organization-library

使用 --claudeai 时，命令拒绝 --scope 和 --sparse。市场为您的账户托管，未在设置文件中声明，因此您无法通过项目的 .claude/settings.json 共享它。

plugin marketplace list

列出您添加的每个市场及其源。

claude plugin marketplace list [options]

Claude Code 打印 Configured marketplaces: 和每个市场一行 Source:，或 No marketplaces configured。

使用 --json 时，Claude Code 打印一个数组，每个市场一个对象，包含下面的字段。每个字段都是字符串。

添加的 claude.ai 市场没有本地克隆，因此其条目在 installLocation 的位置携带其 claude.ai 标识符 marketplaceId 和 organizationUuid。它也在记录时携带 scope 和 status。

如果您的终端会话从您的 claude.ai 账户同步插件，文本列表以 From claude.ai: 部分结尾。该部分列出 claude.ai 为您的账户列出但您尚未添加的市场，包括基于 git 的和托管的。它需要 Claude Code v2.1.273 或更高版本。

要从该部分添加市场，请参阅从 claude.ai 添加市场。

--json 输出仅覆盖已配置的市场，并排除该部分。

plugin marketplace remove

从您的设置中移除市场的声明。rm 是 remove 的别名。

[!WARNING]

当您从最后一个声明市场的作用域中移除市场时，Claude Code 也会删除其缓存并卸载您从中安装的每个插件。它也会删除它们保存的选项和密钥和数据（如果可以的话）。

要在不丢失其插件的情况下刷新市场，请改为运行 plugin marketplace update。

claude plugin marketplace remove <name> [options]

<name> 是 plugin marketplace list 显示的市场名称，而不是您传递给 add 的源。

从每个作用域中移除市场：

claude plugin marketplace remove your-marketplace

Claude Code 打印 Successfully removed marketplace: your-marketplace。当命令卸载插件时，输出在诸如 Also uninstalled 2 plugins from this marketplace: 的行下列出它们。要再次使用其中一个，请添加市场并重新安装插件。

如果您限定作用域到不声明市场的设置文件，命令失败，显示 Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.

plugin marketplace update

从其源刷新一个市场或每个市场，以获取新插件和版本。使用分支或标签 ref 添加的市场更新到该 ref 的最新提交，而不是仓库的默认分支。

claude plugin marketplace update [name] [options]

刷新一个市场：

claude plugin marketplace update your-marketplace

Claude Code 打印 Successfully updated marketplace: your-marketplace。当您省略名称时，它打印计数，如 Successfully updated 2 marketplaces。

会话中的 /plugin

在交互式会话中，/plugin 打开 plugin 面板。每个子命令在选项卡上打开面板、在那里运行操作或内联打印结果。/plugins 和 /marketplace 是 /plugin 的别名。

您只能在交互式终端会话中运行这些命令。在非交互式运行（例如 claude -p）中，Claude Code 回复 /plugin 在此环境中不可用。

有关哪些表面有 /plugin、如何在没有它的情况下安装以及每个面板选项卡显示的内容，请参阅 安装和管理 plugins。

<plugin> 是 plugin name 或 name@marketplace。

下表列出每个会话形式。shell 子命令 init、update、details、prune、eval、eval init 和 test 没有会话形式。

如果您在 /plugin enable、disable、uninstall 或 configure 中命名当前项目中未安装的 plugin，Claude Code 打印 Plugin "<plugin>" is not installed in this project 而不是操作。

/reload-plugins

应用待处理的插件更改到正在运行的会话中，无需重新启动。待处理的更改是指自会话启动以来在磁盘上安装、更新、启用、禁用或编辑的插件。

当你关闭 /plugin 面板时，如果你在其中进行了待处理的更改，Claude Code 会为你运行 /reload-plugins。在面板外发生的插件更改（例如你在另一个终端中运行的 claude plugin 命令）之后，请自己运行它。

/reload-plugins [--force]

重新加载摘要

Claude Code 重新加载每个活跃的插件并打印一行摘要，Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers，在没有交互式终端的会话中省略插件 MCP 服务器计数。当任何插件失败时，摘要会添加 N errors during load. Run /plugin for details.

技能计数涵盖插件提供的每个技能，包括其 commands/ 条目和其 SKILL.md 技能。代理计数是会话中加载的代理数量，包括不来自插件的代理。

当重新加载的插件的依赖项缺失时，Claude Code 会安装它们，再次重新加载，并在摘要中附加 (+ N dependencies: <names>) resolved。

更改 MCP 工具的重新加载

当重新加载会添加或删除插件 MCP 服务器或 LSP 工具时，该更改会使prompt 缓存失效，Claude Code 不会应用重新加载。它会打印一行，例如 This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply. 传递 --force 以应用它。

没有交互式终端的会话

/reload-plugins 也在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 和带有 -p 的非交互模式。需要 Claude Code v2.1.260 或更高版本。

在这些会话中，该命令仅在你自己将其键入会话时运行，例如在 -p 提示或桌面应用的提示框中。当它以其他方式到达时，例如通过远程控制或从 Slack 中继的消息，该命令回复 /reload-plugins isn't available over a remote connection in this session. 并且不重新加载任何内容。

这些会话中的重新加载不连接或断开插件 MCP 服务器。这些更改在你的下一个会话中生效。

为一个会话加载 plugin 的标志

两个 claude 标志仅为一个会话加载 plugin，而不安装它。两者都是可重复的。

Plugin 作者使用它们在发布前测试 plugin。对于加载-编辑-重新加载工作流，请参阅 在没有市场的情况下开发。

任一标志加载的 plugin 是会话内 plugin。claude plugin list 将其显示为 <name>@inline，作用域为 session，但仅当相同的标志在子命令前时，例如 claude --plugin-dir ./my-plugin plugin list。该 plugin 在以 Session-only plugins 开头的标题下显示为 <name>@inline，--json 将其 scope 报告为 session。

当会话内 plugin 与已安装的 plugin 共享名称时，Claude Code 为该会话加载会话内副本并跳过已安装的副本。如果您使用 claude plugin disable <name>@inline 禁用了会话内副本，或托管设置锁定该 plugin 名称，已安装的副本改为加载。有关优先级，请参阅 Plugin 加载参考。

管理员可以拒绝两个标志和 CLAUDE_CODE_PLUGIN_DIRS 变量中命名的文件夹，使用托管 disableSideloadFlags 设置。Claude Code 然后打印标志被您组织的托管设置禁用，并退出 1 而不启动。

从 Agent SDK，plugins 选项等同于 --plugin-dir。

后续步骤

• 安装和管理 plugins：与步骤相同的操作，带有您在每个步骤看到的内容
• Plugin 加载参考：每个命令在磁盘上更改的内容以及哪个作用域生效
• Plugin 故障排除：安装、市场、加载和验证错误消息及其修复
• Plugin 清单参考：claude plugin validate 检查的字段