Plugin 命令参考

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

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

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

claude plugin 命令

从 shell 或脚本中运行 claude plugin <subcommand>，在 Claude Code 会话外。这些子命令安装和管理 plugins，而不打开 /plugin 面板。 claude plugins 是 claude plugin 的别名。每个子命令共享这些退出代码、plugin 参数和作用域值：

退出代码：成功时为 0，失败时为 1。validate 为意外错误添加退出 2，eval 添加其部分中列出的代码。
Plugin 参数：<plugin> 参数是 plugin name 或 name@marketplace。当两个市场提供相同的名称时，使用限定形式。
作用域：--scope 接受 user、project 或 local，并命名命令写入的设置文件。update 也接受 managed。

plugin init

在 ~/.claude/skills/<name>/ 处搭建新 plugin。它在您的下一个会话中作为 <name>@skills-dir 加载，无需安装步骤。 new 是 init 的别名。对于以此命令开始的创建、测试和编辑工作流，请参阅创建 plugin。

claude plugin init <name> [options]

<name> 成为 ~/.claude/skills/ 下的目录名称和 plugin 清单中的 name。该命令没有用于另一个位置的标志。要改为在项目内搭建，请参阅创建 plugin。

标志	描述
`--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/`

使用启动 skill 和 hook 文件搭建 plugin：

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-directory plugins 的托管设置

plugin install

从您添加的市场安装 plugin。i 是 install 的别名。

claude plugin install <plugin> [options]

大多数 plugins 无需提示即可安装。对于其市场条目运行命令来安装它或为其下载设置 headersHelper 的 plugin，Claude Code 首先打印命令并询问 Run this command now? [y/N]。

标志	描述
`-s, --scope <scope>`	安装作用域：`user`、`project` 或 `local`。默认为 `user`
`--config <key=value>`	设置 plugin 清单声明的 `userConfig` 选项。为每个选项重复该标志。需要 Claude Code v2.1.147 或更高版本
`-y, --yes`	接受显示的安装命令，无需 `Run this command now?` 提示。当命令在 Claude Code 会话内运行时（例如从 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更高版本
`--accept-command <sha256>`	接受显示的安装命令，其 `sha256` 之前的 `--json` 运行在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。请参阅接受显示的安装命令。需要 Claude Code v2.1.271 或更高版本
`--json`	将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 JSON 结果格式。需要 Claude Code v2.1.268 或更高版本

从您自己的终端传递 -y 以接受显示的命令而无需提示。以下是没有 TTY 和 Claude 运行命令时发生的情况：

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

为克隆项目的每个人安装 plugin：

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 运行显示市场声明的命令且不运行它时，failed 结果也带有 shownCommand 对象。其字段包括显示的命令、它所属的 plugin 和命令的 sha256。要接受完全相同的命令，从您自己的终端使用该 sha256 作为 --accept-command 重新运行，因为该标志在 Claude Code 会话内无效。需要 Claude Code v2.1.271 或更高版本。 sha256 计为完全相同的命令、plugin 和市场目录的接受。如果自命令显示以来其中任何一个发生了变化，Claude Code 不接受 sha256 并再次显示命令。运行自己的市场刷新获取的更改也计为此类更改。如果 shownCommand.acceptCommandMatched 为 false，您传递的 sha256 与现在显示的命令不匹配。在使用其 sha256 重新运行之前查看该命令。

plugin uninstall

从一个作用域删除已安装的 plugin。remove 和 rm 是 uninstall 的别名。

claude plugin uninstall <plugin> [options]

标志	描述
`-s, --scope <scope>`	从作用域卸载：`user`、`project` 或 `local`。默认为 `user`
`--keep-data`	保留 plugin 的持久数据目录 `~/.claude/plugins/data/<id>/`
`--prune`	也删除自动安装的 dependencies，没有剩余 plugin 需要
`-y, --yes`	跳过 `--prune` 确认提示。当 stdin 或 stdout 不是 TTY 时，`--prune` 需要
`--json`	将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 `plugin install --json` 相同。不能与 `--prune` 组合。需要 Claude Code v2.1.268 或更高版本

从项目作用域卸载 plugin：

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

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

plugin enable

启用禁用的 plugin。对于从 claude.ai 同步的 plugin，将 <name>@synced 作为 plugin 传递。

claude plugin enable <plugin> [options]

标志	描述
`-s, --scope <scope>`	启用的作用域：`user`、`project` 或 `local`。省略时自动检测
`--json`	将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本

不使用 --scope，命令按本地、项目、用户的顺序检查您的设置文件，并使用提及 plugin 的第一个作用域。如果您传递 plugin 未声明的 --scope，命令要么写入覆盖，要么失败：

优先于声明作用域的作用域：Claude Code 在您传递的作用域处写入覆盖。例如，claude plugin disable formatter --scope local 仅为您关闭项目启用的 plugin
任何其他作用域：命令失败，显示 Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.

如果 plugin 已在解析的作用域启用，命令打印 Plugin "formatter" is already enabled 并退出 1。使用 --json，结果具有 "failureCode": "already_in_goal_state" 和 "alreadyInGoalState": true，因此脚本可以将该情况视为成功。当 plugin 声明 dependencies 时，Claude Code 也启用它们。命令在这些情况下失败：

dependency 未安装：启用失败并为每个缺失的 dependency 打印 claude plugin install 命令
dependency 被您组织的 plugin 策略阻止：启用失败并命名被阻止的 dependency
dependency 在优先级高于目标作用域的作用域处设置为 false：启用失败。在该作用域启用 dependency，或传递 --scope 以在那里写入

在声明它的任何地方重新启用 plugin：

claude plugin enable formatter

Claude Code 打印 Successfully enabled plugin: formatter (scope: project)，命名它检测到的作用域。

plugin disable

禁用 plugin 而不卸载它。对于从 claude.ai 同步的 plugin，将 <name>@synced 作为 plugin 传递。

claude plugin disable [plugin] [options]

标志	描述
`-a, --all`	禁用每个启用的 plugin。不能与 plugin 名称或 `--scope` 组合
`-s, --scope <scope>`	禁用的作用域：`user`、`project` 或 `local`。省略时自动检测
`--json`	将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本

不使用 --scope，作用域以与 plugin enable 相同的本地、项目、用户顺序自动检测。如果您既不传递 plugin 名称也不传递 --all，Claude Code 打印 Please specify a plugin name or use --all to disable all plugins 并退出 1。禁用已禁用的 plugin 打印 Plugin "formatter" is already disabled 并退出 1，如 plugin enable 对已启用的 plugin 所做的那样。命令对仍然需要的 plugin 失败：

另一个启用的 plugin depends on 它：命令失败并命名要首先禁用的依赖项
您的组织要求它作为同步 plugin：命令失败并保存任何内容

禁用一个 plugin：

claude plugin disable formatter

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

plugin update

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

claude plugin update <plugin> [options]

标志	描述
`-s, --scope <scope>`	更新的作用域：`user`、`project`、`local` 或 `managed`。默认为 plugin 安装的作用域
`-y, --yes`	接受来自 command-source plugin 的更改的安装命令，无需提示。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。需要 Claude Code v2.1.229 或更高版本
`--accept-command <sha256>`	接受市场声明的命令，其 `sha256` 之前的 `--json` 运行在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。需要 Claude Code v2.1.271 或更高版本
`--json`	将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 `plugin install --json` 相同。需要 Claude Code v2.1.268 或更高版本

managed 是您可以更新但不能安装的唯一作用域。对于管理员安装的 plugins，请参阅为您的组织管理 plugins。更新 plugin：

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。您可以传递裸 plugin 名称，命令将其与您安装的 plugins 匹配。当来自不同市场的已安装 plugins 共享名称时，命令拒绝更新并列出要运行的限定 plugin-name@marketplace-name 命令。按裸名称更新需要 Claude Code v2.1.246 或更高版本。

plugin list

列出已安装的 plugins，包括其版本、作用域和状态。

claude plugin list [options]

标志	描述
`--json`	将列表打印为 JSON
`--available`	也列出您的市场提供但您未安装的 plugins。没有 `--json` 时无效

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

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

当任何组中都没有内容时，Claude Code 打印 No plugins installed. Use `claude plugin install` to install a plugin.

JSON 输出

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

字段	类型	描述
`id`	string	安装为 `name@marketplace`，会话内 plugins 为 `name@inline`，skills-directory plugins 为 `name@skills-dir`，从 claude.ai 同步的 plugins 为 `name@synced`
`version`	string	对于市场安装，Claude Code 在安装时计算的版本。对于会话内、skills-directory 或同步 plugin，清单的 `version`，或当它不声明任何内容时为 `unknown`
`scope`	string	安装为 `user`、`project`、`local` 或 `managed`；skills-directory plugins 为 `user` 或 `project`；会话内 plugins 为 `session`；从 claude.ai 同步的 plugins 为 `synced`
`enabled`	boolean	plugin 在您的合并设置中是否启用
`installPath`	string	plugin 加载的目录
`installedAt`	string	安装的 ISO 时间戳。仅市场安装
`lastUpdated`	string	最后更新的 ISO 时间戳。仅市场安装
`projectPath`	string	安装所属的项目。仅 `project` 和 `local` 作用域
`mcpServers`	object	plugin 的 MCP 服务器定义，当市场安装的 plugin 有任何时
`errors`	array of strings	加载错误，当 plugin 加载失败时
`notes`	array of strings	plugin 加载并工作时的创作警告
`errorDetails`	array of objects	每个 `errors` 条目一个对象，给出其诊断 `type` 和它引用的名称，例如 plugin、市场、服务器或文件。需要 Claude Code v2.1.268 或更高版本
`noteDetails`	array of objects	每个 `notes` 条目的相同详细对象。需要 Claude Code v2.1.268 或更高版本

使用 --json --available，Claude Code 打印一个对象而不是数组。其 installed 字段保存已安装 plugin 对象的数组，其 available 字段保存每个未安装市场 plugin 的一个对象，带有下面的字段。

字段	类型	描述
`pluginId`	string	`name@marketplace`
`name`	string	plugin 在市场中的名称
`marketplaceName`	string	提供它的市场
`source`	string or object	市场条目的 source：相对路径为字符串，否则为对象
`description`	string	条目的描述，当它有时
`version`	string	条目的版本，当它声明时
`installCount`	number	安装计数，当 Claude Code 有 plugin 的计数时

plugin details

显示 plugin 的组件清单及其预计令牌成本。 plugin 必须被加载：已安装、在 skills 目录中找到，或在同一命令中使用 --plugin-dir 或 --plugin-url 传递。<name> 是 plugin name 或 name@marketplace。

claude plugin details <name>

命令除了 --help 外不接受任何标志。显示已安装 plugin 的贡献：

claude plugin details formatter

Claude Code 打印 plugin 的名称、版本、描述和源，然后是这些部分：

Component inventory：plugin 的 skills、agents、hooks、MCP 服务器和 LSP 服务器
Projected token cost：plugin 添加到每个会话的始终开启令牌
Per-component (rounded)：每个 skill、agent 和命令的始终开启和按调用估计。当 plugin 没有时省略

对于两个成本数字的含义，请参阅测量 plugin 成本和使用。对于未加载的 plugin，Claude Code 打印

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

并退出 1。

plugin prune

删除自动安装的 dependencies，没有已安装的 plugin 需要。命令永远不会删除您自己安装的 plugin。autoremove 是 prune 的别名。

claude plugin prune [options]

标志	描述
`-s, --scope <scope>`	在作用域处修剪：`user`、`project` 或 `local`。默认为 `user`
`--dry-run`	列出将被删除的内容而不删除它
`-y, --yes`	跳过确认提示。当 stdin 或 stdout 不是 TTY 时需要

预览修剪将删除的内容：

claude plugin prune --dry-run

Claude Code 列出孤立的 dependencies 并以 (dry run — nothing removed) 结尾。当没有要删除的内容时，它打印以 Nothing to prune 开头的行。不使用 --dry-run，命令仅在您在提示处确认或传递 -y 后删除孤立的 dependencies。无论您在提示处的答案如何，退出代码都是 0。 prune 的作用取决于是否附加了终端以及您是否传递了 -y：

终端和标志	发生的情况
交互式终端，无 `-y`	列出孤立的 dependencies 并询问 `Remove? [y/N]`
任何终端，`-y`	删除它们并打印 `Removed N auto-installed plugins: <names>`
非 TTY stdin 或 stdout，无 `-y`	打印列表和 Not a TTY — run `claude plugin prune -y` to remove.，不删除任何内容

plugin eval

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

claude plugin eval [target] [options]

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

plugin 目录
单个 prompt.md 或 case.yaml 文件
已安装的 plugin，如 name 或 name@marketplace
name@skills-dir

将目标放在 --tag、--allow-tools 和 --json 之前。这些选项中的每一个都将其后的单词作为其值，因此在其中一个之后写入的目标被读作标签、工具名称或 JSON 输出路径，而不是目标。此表列出大多数运行使用的选项。运行 claude plugin eval --help 以获取完整集合，包括 --case、--tag、--output-dir、--report、--allow-real-servers、--keep-temp 和 --verbose。

选项	描述	默认
`--runs <n>`	每个 arm 中每个案例的运行	每个案例的 `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`。请参阅与无 plugin 基线比较	当 plugin 解析时为 `with-without`，否则为 `none`
`--threshold <0..1>`	如果任何案例评分低于此，退出 1	`1.0`
`--max-cost-usd <usd>`	一旦支出达到此值，在下一次运行前停止，退出 2，并报告部分结果	无限制
`--allow-tools <tools...>`	授予超出只读集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅授予工具
`--scaffold`	运行每个案例的 `scaffold_script`	关闭
`--trust-plugin`	跳过首次运行信任提示，用于 CI。请参阅运行可以访问的内容	关闭
`--mocks <mode>`	`record` 或 `off`。请参阅 Mock MCP 服务器	`record`
`--eval-dir <dir>`	plugin 下方保存案例的目录	清单的 `experimental.evals`，否则 `evals`
`--json [path]`	将结果文档打印到 stdout，或将其写入 `.json` 路径
`--no-publish`	保持 HTML 报告本地

退出代码报告运行如何结束。要在管道中对其进行操作，请参阅在 CI 中运行 evals。

退出代码	含义
`0`	每个案例都满足阈值
`1`	失败的案例、加载错误或不受信任的 plugin 目录
`2`	部分运行
`130`	中断
`143`	终止

plugin eval init

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

claude plugin eval init [name] [options]

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

读取 plugin
询问您它应该做什么
提议案例和评分器
写入案例文件
运行案例并与您一起查看评分，以检查评分器是否按您的方式评分

使用 --bare 或没有终端，命令改为写入空白单案例模板。当 Claude 从 Claude Code 会话内运行命令时，命令打印该会话要遵循的访谈说明，而不是写入模板。可选的 name 是案例名称。它对于 --bare 或没有终端是必需的，因为命令为该案例写入空白模板。访谈不需要。命令接受这些选项：

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

plugin tag

为 plugin 发布创建名为 <name>--v<version> 的带注释 git 标签。在标记之前，命令检查 plugin 的 plugin.json 和任何列出它的市场条目是否同意版本。有关何时标记发布，请参阅发布 plugin。

claude plugin tag [path] [options]

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

标志	描述
`--push`	创建后将标签推送到 `--remote`
`--dry-run`	打印将被标记的内容而不创建标签
`-f, --force`	跳过脏工作树和标签已存在检查
`-m, --message <msg>`	标签注释消息。`%s` 代表版本。默认为 `<name> <version>`
`--remote <name>`	使用 `--push` 推送到的远程。默认为 `origin`

预览市场检出中 plugin 的标签：

claude plugin tag plugins/formatter --dry-run

Claude Code 打印计划：

plugin 名称
版本和它来自哪个文件
匹配的市场条目，当有时
标签名称
它将运行的 git tag 和 git push 命令

不使用 --dry-run，Claude Code 打印 Created tag formatter--v1.0.0 和 Pushed to origin 或您自己运行的推送命令。如果推送失败，标签仍在本地创建，命令以错误退出。当它无法安全标记时，命令退出 1 并打印原因。常见原因是：

plugin.json 或市场条目中没有 version
标签已存在
工作树是脏的

plugin validate

验证 plugin 清单、市场清单或目录中的 skills、agents 和命令，并以 CI 作业可以操作的代码退出。对于创建、测试和编辑工作流，请参阅创建 plugin。对于验证器在每个清单中检查的内容，请参阅 plugin 清单参考和市场参考。

claude plugin validate <path> [options]

标志	描述
`--strict`	将警告视为错误，因此运行时容忍的未识别字段和缺失元数据失败。需要 Claude Code v2.1.145 或更高版本
`--json`	将验证报告输出为一个 JSON 对象，具有相同的退出代码。需要 Claude Code v2.1.259 或更高版本

在提交前验证 plugin：

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 Code 不跟随您命名的目录内的符号链接。它的作用取决于链接的位置：

plugin 或 .claude 根下的链接 skills、agents 或 commands 目录：Claude Code 警告其中的任何内容都未被读取。
skills、agents 或 commands 目录内的链接条目：Claude Code 跳过它并警告，每个目录，它跳过了多少条目，会话会加载。
您命名的 skills、agents 或 commands 目录本身是符号链接，或其父 .claude 目录是：Claude Code 报告错误并检查其中的任何内容。改为命名真实目录。

验证运行不读取几个文件：

plugin 根处的 SKILL.md：当您针对 plugin 目录运行 claude plugin validate 时，Claude Code 不检查 plugin 根处的 SKILL.md
plugin 根处的 CLAUDE.md：在 plugin 运行中，Claude Code 也警告 plugin 根处的 CLAUDE.md
市场运行中的 Plugin 文件：从市场目录，Claude Code 不打开 plugins 的 skill、agent、command 或 hook 文件。要在这些文件中查找错误，验证每个 plugin 目录

输出和退出代码

Claude Code 打印它验证的文件、任何错误和警告及其路径，以及判决行。退出代码遵循判决：

退出代码	判决行	含义
`0`	`Validation passed` 或 `Validation passed with warnings`	清单加载。使用 `--strict`，也没有警告
`1`	`Validation failed` 或 `Validation failed (--strict treats warnings as errors)`	错误，或 `--strict` 下的警告
`2`	`Unexpected error during validation: <reason>`	验证器本身失败，例如在不可读的路径上

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

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

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

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]

标志	描述
`--scope <scope>`	声明市场的设置文件：`user`、`project` 或 `local`。默认为 `user`
`--sparse <paths...>`	将 git 检出限制在这些目录，用于 monorepos。仅限 `github` 和 `git` 源
`--claudeai`	将参数读取为托管在 claude.ai 上的市场的名称，而不是源。需要 Claude Code v2.1.273 或更高版本

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

你输入的	源类型	Claude Code 如何获取它
`owner/repo`、`owner/repo#ref` 或 `owner/repo@ref`	`github`	克隆 GitHub 仓库，给定时固定到 `ref`。所有者和仓库必须遵循 GitHub 命名规则
`user@host:path[.git][#ref]`	`git`	通过 SSH 克隆
`https://example.com/repo.git[#ref]` 或包含 `/_git/` 的 URL	`git`	通过 HTTPS 克隆，包括 Azure DevOps URL
`https://github.com/owner/repo` 或 `https://gitlab.com/namespace/project`	`git`	在追加 `.git` 后通过 HTTPS 克隆
任何其他 `http://` 或 `https://` URL，包括没有 `.git` 的自托管 git 主机	`url`	将 URL 作为 `marketplace.json` 获取。要改为克隆那里的仓库，请追加 `.git`
`./path`、`../path`、`/path` 或 `~/path` 到目录	`directory`	就地读取目录。在 Windows 上，`.\`、`..\` 和 `C:\` 形式也可以工作
相同的路径形式，到 `.json` 文件	`file`	就地读取文件

对于克隆 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]

标志	描述
`--json`	将列表打印为 JSON

Claude Code 打印 Configured marketplaces: 和每个市场一行 Source:，或 No marketplaces configured。使用 --json 时，Claude Code 打印一个数组，每个市场一个对象，包含下面的字段。每个字段都是字符串。

字段	描述
`name`	市场的名称
`source`	`github`、`git`、`url`、`directory`、`file` 或 `claudeai`
`repo`	`owner/repo`。仅限 `github` 源
`url`	克隆或获取 URL。仅限 `git` 和 `url` 源
`path`	本地路径。仅限 `directory` 和 `file` 源
`ref`	固定的分支或标签。`github` 和 `git` 源，仅在固定时
`installLocation`	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 的别名。

当你从最后一个声明市场的作用域中移除市场时，Claude Code 也会删除其缓存并卸载你从中安装的每个插件。不使用 --scope 时，命令从每个作用域中移除声明。要在不丢失其插件的情况下刷新市场，请改为运行 plugin marketplace update。

claude plugin marketplace remove <name> [options]

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

标志	描述
`--scope <scope>`	从一个设置作用域中移除声明：`user`、`project` 或 `local`。不使用它时，Claude Code 从每个作用域中移除声明

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

claude plugin marketplace remove your-marketplace

Claude Code 打印 Successfully removed marketplace: your-marketplace，当你限定作用域时添加 (from project settings)。如果你限定作用域到不声明市场的设置文件，命令失败，显示 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]

该命令除了 --help 外不接受任何标志。刷新一个市场：

claude plugin marketplace update your-marketplace

Claude Code 打印 Successfully updated marketplace: your-marketplace。当你省略名称时，它打印计数，如 Successfully updated 2 marketplaces。没有添加市场时，它打印 No marketplaces configured 并退出 0。

会话中的 /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 没有会话形式。

命令	别名	它做什么
`/plugin`		在 Discover 选项卡上打开面板。`/plugin` 后的任何无法识别的第一个单词也这样做
`/plugin help`	`/plugin --help`、`/plugin -h`	显示 `/plugin` 子命令的使用列表
`/plugin list [--enabled\|--disabled]`	`ls`	内联打印您的市场安装 plugins，带有版本、作用域和状态。过滤标志仅显示该状态。启用状态尚未应用的 plugin 标记为 `— run /reload-plugins to apply`。需要 Claude Code v2.1.163 或更高版本
`/plugin install`	`i`	打开 Discover 选项卡
`/plugin install <plugin>`	`i`	在 Discover 选项卡中打开 plugin 的详细信息。使用 `name@marketplace`，在该市场的列表中打开它们
`/plugin install <plugin> --marketplace <source>`	`i`	当您尚未添加时添加 `<source>` 处的市场，要求您首先确认，然后打开 plugin 的详细信息。请参阅在一个命令中添加市场和安装。需要 Claude Code v2.1.275 或更高版本
`/plugin manage`		打开 Installed 选项卡
`/plugin stats`		打开 Stats 选项卡，在 `/skill-doctor` 可用的会话中。其他任何地方它在 Discover 选项卡上打开面板
`/plugin enable <plugin>`		在 plugin 处打开 Installed 选项卡并启用它
`/plugin disable <plugin>`		在 plugin 处打开 Installed 选项卡并禁用它
`/plugin uninstall <plugin>`		在 plugin 处打开 Installed 选项卡并卸载它
`/plugin configure <plugin>`	`config`	打开 plugin 的 `userConfig` 对话框，或报告 plugin 不声明任何。需要 Claude Code v2.1.147 或更高版本
`/plugin validate <path>`		打印与 `claude plugin validate` 相同的报告，内联
`/plugin tag [path] [--push] [--dry-run] [--force]`		创建发布标签，如 `claude plugin tag` 所做的那样。接受 `--push`、`--dry-run` 和 `--force` 或 `-f`；使用任何其他标志或额外参数，Claude Code 改为打印使用
`/plugin marketplace`	`market`	不做任何可见的事情。传递 `add`、`list`、`update` 或 `remove`
`/plugin marketplace add [source]`	`market add`	使用源，添加它并报告结果。不使用源，打开 Add marketplace 输入
`/plugin marketplace list`	`market list`	内联打印您的市场名称
`/plugin marketplace update [name]`	`market update`	打开 Marketplaces 选项卡。使用名称，在那里刷新该市场
`/plugin marketplace remove [name]`	`market remove`、`market rm`、`marketplace rm`	打开 Marketplaces 选项卡。使用名称，在那里删除该市场

如果您在 /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]

标志	描述
`--force`	应用重新加载，即使它会使 prompt 缓存失效。不带破折号的 `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-dir <path>`	从目录或其 `.zip` 存档加载 plugin。plugins 的文件夹加载每个包含 `.claude-plugin/plugin.json` 的子文件夹。每个标志接受一个路径	`claude --plugin-dir ./my-plugin --plugin-dir ./other.zip`
`--plugin-url <url>`	从 URL 获取 plugin `.zip` 存档。重复标志，或在一个引用值中传递多个 URL 空格分隔	`claude --plugin-url "https://example.com/a.zip https://example.com/b.zip"`

任一标志加载的 plugin 是会话内 plugin。claude plugin list 将其显示为 <name>@inline，作用域为 session，但仅当相同的标志在子命令前时。例如，运行 claude --plugin-dir ./my-plugin plugin list。当会话内 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 检查的字段

插件

使用插件

创建插件

运行 marketplace

管理组织的插件

故障排除

参考

claude plugin 命令

plugin init

plugin install

JSON 结果格式

接受显示的安装命令

plugin uninstall

plugin enable

plugin disable

plugin update

plugin list

JSON 输出

plugin details

plugin prune

plugin eval

plugin eval init

plugin tag

plugin validate

验证目录

输出和退出代码

claude plugin marketplace 命令

plugin marketplace add

plugin marketplace list

plugin marketplace remove

plugin marketplace update

会话中的 /plugin

/reload-plugins

重新加载摘要

更改 MCP 工具的重新加载

没有交互式终端的会话

为一个会话加载 plugin 的标志

后续步骤

​claude plugin 命令

​plugin init

​plugin install

​JSON 结果格式

​接受显示的安装命令

​plugin uninstall

​plugin enable

​plugin disable

​plugin update

​plugin list

​JSON 输出

​plugin details

​plugin prune

​plugin eval

​plugin eval init

​plugin tag

​plugin validate

​验证目录

​输出和退出代码

​claude plugin marketplace 命令

​plugin marketplace add

​plugin marketplace list

​plugin marketplace remove

​plugin marketplace update

​会话中的 /plugin

​/reload-plugins

​重新加载摘要

​更改 MCP 工具的重新加载

​没有交互式终端的会话

​为一个会话加载 plugin 的标志

​后续步骤

claude plugin 命令

plugin init

plugin install

JSON 结果格式

接受显示的安装命令

plugin uninstall

plugin enable

plugin disable

plugin update

plugin list

JSON 输出

plugin details

plugin prune

plugin eval

plugin eval init

plugin tag

plugin validate

验证目录

输出和退出代码

claude plugin marketplace 命令

plugin marketplace add

plugin marketplace list

plugin marketplace remove

plugin marketplace update

会话中的 /plugin

/reload-plugins

重新加载摘要

更改 MCP 工具的重新加载

没有交互式终端的会话

为一个会话加载 plugin 的标志

后续步骤