自作CLIからClaude Codeのプラグイン導入を案内する方法

この記事の要点
- CLI の中で Claude Code の中だと分かったら、標準エラー出力へ claude-code-hint のタグを1行出すと、利用者に導入の案内が出る
- 対象は公式のマーケットプレイスに載っているプラグインだけ。案内は1つのプラグインにつき一度きりで、30秒無回答は「いいえ」
- 手元では、CLAUDECODE=1 を付けて実行し、タグが標準エラーに出ることを確かめる
活用例:自社の CLI を使っている人へ、AI の開発ツールの連携プラグインを自然に知らせる
- 部署
- 開発者向けサービス・プロダクト
- 使うもの
- Claude Code の claude-code-hint タグと公式マーケットプレイス
- AIに任せる
- タグを出す小さなコードの下書き
- 人が決める
- 公式マーケットプレイスへの掲載・案内の対象にするか
自社で CLI(コマンドラインの道具)や SDK を出している会社は、「Claude Code の中で使われているときだけ、連携プラグインを案内したい」と思うことがあります。
Claude Code には、そのための決まった1行のタグがあります。この記事では、公式ドキュメント「Prompt users to install your plugin」(2026年11月16日確認)にもとづいて、出し方と、案内が出る条件をまとめます。
結論:標準エラーに1行のタグを出すだけ
CLI が Claude Code の中で動いていると分かったら、標準エラー出力へ、次の形のタグを1行だけ書きます。
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
Claude Code は、シェルの出力(Bash と PowerShell の道具)からこの行を取り除いて、Claude が読む前に消します。そして利用者に、1回だけ導入の案内を出します。
ただし対象は、公式のマーケットプレイスに載っているプラグインだけです。 公式の名前のマーケットプレイスにあるものが対象で、コミュニティ用の claude-community は含まれません。プラグインを公開する流れ自体は、プラグインのマーケットプレイス の記事で説明しています。
出す条件:環境変数で判定する
利用者が自分でターミナルから CLI を動かしたときに、タグが見えると困ります。そこで、環境変数で Claude Code の中かどうかを判定します。
| 環境変数 | 入る場面 |
|---|---|
| CLAUDECODE | Claude Code が動かす Bash・PowerShell のコマンドと、フックのコマンド。どの版でも入る。IDE 拡張の統合ターミナルにも入る |
| CLAUDE_CODE_CHILD_SESSION | v2.1.172 以降で、Claude Code が自分で起こした処理だけに入る |
IDE の統合ターミナルで利用者が自分で CLI を動かした場合も出してよいなら CLAUDECODE、それを避けたいなら CLAUDE_CODE_CHILD_SESSION で判定します。公式の例は、Node.js・Python・Go・シェルの4つで、どれも同じ考え方です。シェルの例は次のとおりです。
if [ -n "$CLAUDECODE" ]; then
echo '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
fi
毎回の起動で出して構いません。案内は、1つのプラグインにつき一度しか出ません。
タグの書き方
タグは独立した1行にします。行の途中に埋め込むと無視されます。属性は3つとも必須です。
| 属性 | 意味 |
|---|---|
| v | 版。1だけが使える |
| type | 種類。plugin だけが使える |
| value | プラグインの名前@マーケットプレイスの名前 |
値は二重引用符で囲んでも、囲まなくても構いません。囲まない場合は空白を含められません。なお v や type が未知の値でも、行は出力から消されます。
案内が出る条件
次の条件がすべて満たされたときだけ、利用者に案内が出ます。
- 公式のマーケットプレイスの手元の写しにそのプラグインがあり、まだ入っておらず、方針で禁止されていない
- 分析(アナリティクス)が有効。DISABLE_TELEMETRY などで切っているときや、Amazon Bedrock のような外部プロバイダー経由のときは出ない
- 1セッションに1回、プラグインごとに生涯1回。そのパソコンで案内したプラグインが100個に達したあとは出ない
- 利用者が「今後は案内しない」を選んでいない
- 手元で、人が見ているセッション。
claude -p、サブエージェント、フック、クラウドのセッション、遠隔操作、エージェントチームの仲間では出ない
利用者に見える画面
利用者には「Plugin recommendation」という案内が出ます。プラグイン名・マーケットプレイス名・説明が並び、選択肢は3つです。
- Yes, install:自分のアカウント(ユーザー範囲)にプラグインを入れる
- No:今回は入れない
- No, and don't show plugin installation hints again:以後、この種類の案内を出さない
30秒答えがなければ「No」として扱われます。案内には、Claude が実行したコマンドの先頭の単語も出るので、利用者は「どのコマンドの案内か」を見分けられます。
動作の確かめ方
手元では、次の2通りで確かめます。
CLAUDECODE=1 example-cliと実行し、標準エラーにタグの行が出ることを確かめる- 環境変数なしで
example-cliを実行し、余計な出力が無いことを確かめる
設計の注意
案内は、利用者の許可なしに入れる仕組みではありません。入れるかどうかは、必ず利用者が選びます。 自社で出すときも、プラグインの中身(スキル・フック・MCP)が利用者の環境に何を足すかを、先に整理しておくと安心です。配布するプラグインの安全面の考え方は プラグインのセキュリティ の記事にまとめています。
まとめ
- CLAUDECODE などで Claude Code の中だと確かめ、標準エラーに claude-code-hint のタグを1行出す
- 対象は公式のマーケットプレイスのプラグインだけ。案内は1つにつき一度
- 案内は人が見ている手元のセッションだけ。30秒無回答は「いいえ」
- 確かめるときは CLAUDECODE=1 の有無で出力を見比べる
出典:Prompt users to install your plugin(公式ドキュメント)
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


