在 CLI 中推荐你的插件

让 CLI 输出一行标记，以提示 Claude Code 用户安装你的官方插件。

如果你维护 CLI 或 SDK，并且在 Anthropic 官方插件市场中提供了插件，就可以提示 Claude Code 用户安装该插件。当 CLI 检测到自身正在 Claude Code 中运行时，它会向 stderr 写入一行标记。Claude Code 读取并从输出中移除该标记，然后向用户显示一次性安装提示。

Claude Code 会先从命令输出中移除提示行，再将输出发送给模型。因此，该标记不会出现在对话中，也不会计入 Token 用量。此协议不需要运行额外命令，也不会改变 CLI 向 Claude Code 之外的用户显示的内容。

本页面面向 CLI 和 SDK 维护者。如果你希望安装插件，请参阅发现并安装插件。

工作原理

Claude Code 会为通过 Bash 和 PowerShell 工具运行的每条命令，以及 Hook 命令，将 CLAUDECODE 环境变量设置为 1。从 v2.1.172 开始，它还会在这些子进程中将 CLAUDE_CODE_CHILD_SESSION 设置为 1。当 CLI 检测到任一变量时，便向 stderr 写入一个自闭合的 <claude-code-hint /> 标签。在 Hook 命令中，该提示标签会被移除并忽略。只有 Bash 和 PowerShell 工具的输出会触发安装提示。

Claude Code 收到命令输出后，会执行以下操作：

1. 扫描提示行，并在输出到达模型前将其移除
2. 检查提示所指向的插件是否位于 Anthropic 官方插件市场
3. 检查该插件是否尚未安装且此前从未提示过
4. 显示安装提示，并注明是哪个命令输出了该提示

Claude Code 绝不会自动安装插件，始终需要用户确认。

输出提示

应通过环境变量控制标记的输出，使用户直接运行 CLI 时尽量不会看到该标记；然后，将标签单独一行写入 stderr。可以选择检查以下任一变量：

• CLAUDECODE：所有 Claude Code 版本都会设置，因此能够覆盖最多的会话。Claude Code 启动的 tmux 会话和 stdio MCP 服务器子进程中也会设置该变量。IDE 扩展同样会在其集成终端中设置它，而用户可能会在该终端中直接运行 CLI。
• CLAUDE_CODE_CHILD_SESSION：仅在 Claude Code 自身启动的子进程中设置，例如工具调用、Hook 命令和状态栏命令，因此标签通常不会出现在用户终端中。如果某个长时间运行的进程（例如 tmux 服务器）在会话内部启动，它会捕获该变量，之后从该进程启动的 shell 仍会显示原始标签。此变量要求 Claude Code v2.1.172 或更高版本，旧版本会话将无法收到提示。

以下示例检查 CLAUDECODE 以获得最大覆盖范围，并为官方插件市场中名为 example-cli 的插件输出提示：

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}

请将 example-cli 替换为插件在官方插件市场中的名称。

选择输出位置

你可以决定哪些代码路径输出提示。Claude Code 会按插件去重，因此每次调用时都输出提示也没有负面影响。以下触发点通常效果较好：

用户会看到什么

提示通过所有检查后，Claude Code 会显示类似以下内容：

─────────────────────────────────────────────────────────────
  Plugin recommendation

    The example-cli command suggests installing a plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Official integration for example-cli deployments

    Would you like to install it?
    ❯ 1. Yes, install example-cli
      2. No
      3. No, and don't show plugin installation hints again

─────────────────────────────────────────────────────────────

提示中会注明输出该标记的命令，以便用户发现工具与其推荐插件不匹配的情况。如果用户在 30 秒内没有响应，提示将按选择 No 关闭。

提示频率受到以下限制：

• 每个插件一次：显示提示后，Claude Code 会记录该插件，无论用户如何选择，此后都不会再次为其显示提示。
• 每个会话一次：一台计算机上的所有 CLI，在每个 Claude Code 会话中最多显示一次插件提示。

选择 Yes 会将插件安装到用户作用域。选择 No, and don't show plugin installation hints again 会为该用户禁用之后的所有插件提示。

提示格式

提示是一个包含三个必需属性的自闭合标签。

<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

属性值可以使用双引号，也可以不加引号。未加引号的值不能包含空白字符。不支持转义序列。

要求

Claude Code 会先检查两个条件，再处理提示。未通过任一检查的提示都会被丢弃：

• 独占一行：标签必须单独占据一行。嵌在行中（例如日志语句内部）的标签会被忽略。该行可以包含前导和尾随空白。
• 官方插件市场：value 必须引用由 Anthropic 管理的插件市场（例如 claude-plugins-official）中的插件。指向其他插件市场的提示会被静默丢弃。

无论版本或类型是否能够识别，提示行始终会在输出到达模型之前被移除，因此该标记不会计入 Token 用量。

以下建议不会被强制执行。Claude Code 无法确认 CLI 是否遵循了这些建议：

• 写入 stderr：stderr 可以避免标签进入 example-cli deploy | jq 等 shell 管道。Claude Code 会扫描两个输出流，因此写入 stdout 也能生效。
• 通过环境变量控制：仅当设置了 CLAUDECODE 或 CLAUDE_CODE_CHILD_SESSION 时才输出。有关两个变量的区别，请参阅输出提示。

将插件加入官方插件市场

提示协议仅对官方 Anthropic 插件市场 claude-plugins-official 中列出的插件生效。Anthropic 会自行决定如何维护该市场。应用内提交表单会将插件添加到社区插件市场，而提示协议不会检查社区市场。如果你正在与 Anthropic 合作伙伴联系人协作，请联系对方以协调官方插件市场上架事宜。

另请参阅

• 创建插件：构建 CLI 所推荐的插件
• 创建和分发插件市场：在官方插件市场之外托管插件
• 环境变量：CLAUDECODE 及相关变量的完整参考