自作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 の中かどうかを判定します。

環境変数入る場面
CLAUDECODEClaude Code が動かす Bash・PowerShell のコマンドと、フックのコマンド。どの版でも入る。IDE 拡張の統合ターミナルにも入る
CLAUDE_CODE_CHILD_SESSIONv2.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 が未知の値でも、行は出力から消されます。

案内が出る条件

次の条件がすべて満たされたときだけ、利用者に案内が出ます。

利用者に見える画面

利用者には「Plugin recommendation」という案内が出ます。プラグイン名・マーケットプレイス名・説明が並び、選択肢は3つです。

30秒答えがなければ「No」として扱われます。案内には、Claude が実行したコマンドの先頭の単語も出るので、利用者は「どのコマンドの案内か」を見分けられます。

動作の確かめ方

手元では、次の2通りで確かめます。

  1. CLAUDECODE=1 example-cli と実行し、標準エラーにタグの行が出ることを確かめる
  2. 環境変数なしで example-cli を実行し、余計な出力が無いことを確かめる

設計の注意

案内は、利用者の許可なしに入れる仕組みではありません。入れるかどうかは、必ず利用者が選びます。 自社で出すときも、プラグインの中身(スキル・フック・MCP)が利用者の環境に何を足すかを、先に整理しておくと安心です。配布するプラグインの安全面の考え方は プラグインのセキュリティ の記事にまとめています。

まとめ

  1. CLAUDECODE などで Claude Code の中だと確かめ、標準エラーに claude-code-hint のタグを1行出す
  2. 対象は公式のマーケットプレイスのプラグインだけ。案内は1つにつき一度
  3. 案内は人が見ている手元のセッションだけ。30秒無回答は「いいえ」
  4. 確かめるときは CLAUDECODE=1 の有無で出力を見比べる

出典:Prompt users to install your plugin(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事