plugin-hints.md +0 −172 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# CLI からプラグインを推奨する
6
7> CLI から 1 行のマーカーを出力して、Claude Code ユーザーに公式プラグインのインストールを促します。
8
9CLI または SDK を保守していて、公式の Anthropic マーケットプレイスにプラグインがある場合、ツールは Claude Code ユーザーにそのプラグインのインストールを促すことができます。CLI は Claude Code 内で実行されていることを検出すると、stderr に 1 行のマーカーを書き込みます。Claude Code はマーカーを読み取り、出力から削除し、ユーザーに 1 回限りのインストールプロンプトを表示します。
10
11このプロトコルは追加のコマンドを必要とせず、Claude Code の外でユーザーが実行する場合に CLI が出力する内容を変更しません。
12
13このページは CLI および SDK メンテナー向けです。プラグインのインストールを探している場合は、[プラグインの発見とインストール](/docs/ja/discover-plugins)を参照してください。
14
15<h2 id="how-it-works">
16 仕組み
17</h2>
18
19Claude Code は、Bash および PowerShell ツールを通じて実行するすべてのコマンド、および [hook](/docs/ja/hooks) コマンドに対して、[`CLAUDECODE`](/docs/ja/env-vars) 環境変数を `1` に設定します。v2.1.172 以降では、同じサブプロセスで [`CLAUDE_CODE_CHILD_SESSION`](/docs/ja/env-vars) も `1` に設定します。CLI がこれらの変数のいずれかを検出すると、自己終了型の `<claude-code-hint />` タグを stderr に書き込みます。hook コマンドではヒントタグは削除され、無視されます。Bash および PowerShell ツール出力のみがインストールプロンプトをトリガーします。
20
21Claude Code がコマンド出力を受け取ると、以下を実行します。
22
231. ヒント行をスキャンし、出力がモデルに到達する前に削除します
242. ヒントが公式 Anthropic マーケットプレイスのプラグインをターゲットにしていることを確認します
253. プラグインがまだインストールされていないこと、および以前にプロンプトが表示されていないことを確認します
264. ヒントを出力したコマンドの名前を表示するインストールプロンプトをユーザーに表示します
27
28Claude Code はプラグインを自動的にインストールすることはありません。ユーザーが常に確認します。
29
30<h2 id="emit-the-hint">
31 ヒントを発行する
32</h2>
33
34ヒントプロンプトは、公式の Anthropic マーケットプレイスにリストされているプラグインに対してのみ発火します。統合をリリースする前に、[プラグインを公式マーケットプレイスに登録する](#get-your-plugin-into-the-official-marketplace)を参照してください。
35
36環境変数で発行をゲートして、人間が CLI を直接実行する場合にマーカーが表示される可能性を低くしてから、タグを stderr に独立した行として書き込みます。チェックする変数を選択してください。
37
38* `CLAUDECODE`：すべての Claude Code バージョンで設定されるため、最も多くのセッションに到達します。Claude Code が開始する tmux セッションと stdio MCP サーバーサブプロセスでも設定されます。IDE 拡張機能は、人間が CLI を直接実行する可能性がある統合ターミナルでも設定します。
39* `CLAUDE_CODE_CHILD_SESSION`：Claude Code 自体がスポーンするサブプロセス（ツール呼び出し、フックコマンド、[ステータスライン](/docs/ja/statusline)コマンドなど）でのみ設定されるため、タグは通常、人間のターミナルに到達しません。セッション内で開始された長時間実行プロセス（tmux サーバーなど）は変数をキャプチャするため、そのプロセスから後で起動されたシェルは依然として生のタグを表示します。
40
41以下の例は、最大限のリーチのために `CLAUDECODE` でゲートし、公式マーケットプレイスの `example-cli` という名前のプラグインのヒントを発行します。
42
43<CodeGroup>
44 ```javascript Node.js theme={null}
45 if (process.env.CLAUDECODE) {
46 process.stderr.write(
47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
48 )
49 }
50 ```
51
52 ```python Python theme={null}
53 import os, sys
54
55 if os.environ.get("CLAUDECODE"):
56 print(
57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
58 file=sys.stderr,
59 )
60 ```
61
62 ```go Go theme={null}
63 if os.Getenv("CLAUDECODE") != "" {
64 fmt.Fprintln(os.Stderr,
65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
66 }
67 ```
68
69 ```shell Shell theme={null}
70 if [ -n "$CLAUDECODE" ]; then
71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
72 fi
73 ```
74</CodeGroup>
75
76公式マーケットプレイスのプラグイン名で `example-cli` を置き換えてください。
77
78<h2 id="choose-where-to-emit">
79 出力場所を選択する
80</h2>
81
82ヒントを出力するコードパスを制御します。Claude Code はプラグイン別に重複排除するため、すべての呼び出しで出力しても欠点はありません。うまく機能するタッチポイントは以下の通りです。
83
84| 配置 | 機能する理由 |
85| :------------- | :------------------------------------- |
86| `--help` 出力 | Claude は不慣れな CLI を探索するときにヘルプを実行することが多い |
87| 不明なサブコマンドエラー | Claude がインターフェイスについて混乱している瞬間に到達します |
88| ログインまたは認証成功 | ユーザーはすでにセットアップの心構えができています |
89| 初回実行ウェルカムメッセージ | 自然なオンボーディングの瞬間 |
90
91<h2 id="what-the-user-sees">
92 ユーザーに表示される内容
93</h2>
94
95ヒントがすべてのチェックに合格すると、Claude Code は以下のようなプロンプトを表示します。
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 プラグイン推奨
100
101 example-cli コマンドはプラグインのインストールを提案しています。
102
103 プラグイン: example-cli
104 マーケットプレイス: claude-plugins-official
105 example-cli デプロイメント向けの公式統合
106
107 インストールしますか？
108 ❯ 1. はい、example-cli をインストール
109 2. いいえ
110 3. いいえ、プラグインインストールヒントを再度表示しない
111
112─────────────────────────────────────────────────────────────
113```
114
115プロンプトはヒントを生成したコマンドの名前を表示するため、ユーザーはツールと推奨するプラグイン間の不一致を検出できます。ユーザーが 30 秒以内に応答しない場合、Claude Code はプロンプトを**いいえ**として却下します。
116
117プロンプト頻度は制限されており、一部のセッションではプロンプトが表示されません。
118
119* **プラグインごとに 1 回**: プロンプトが表示された後、Claude Code はプラグインを記録し、ユーザーの回答に関係なく、二度とそのプラグインのプロンプトを表示しません。
120* **セッションごとに 1 回**: マシン上のすべての CLI にわたって、Claude Code セッションごとに最大 1 つのヒントプロンプトが表示されます。
121* **メインの対話型セッションのみ**: Claude Code はユーザーが入力しているターミナルセッションでのみプロンプトを表示します。Claude Code は [サブエージェント](/docs/ja/sub-agents) が実行するコマンドのプロンプトを表示することはなく、ユーザーが Claude Code を [非対話型モード](/docs/ja/headless) で `-p` フラグを使用して実行する場合、または [Agent SDK](/docs/ja/agent-sdk/overview) を通じて実行する場合もプロンプトを表示しません。Claude Code はこれらすべてのケースでコマンド出力からヒント行を削除します。
122* **テレメトリのオプトアウト**: アナリティクスが無効になっているセッションはヒントプロンプトを表示しません。これには `DISABLE_TELEMETRY` または `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` が設定されているセッション、および Amazon Bedrock や Google Cloud の Agent Platform などのサードパーティプロバイダー上のセッション（[自動テレメトリオプトアウト](/docs/ja/data-usage#default-behaviors-by-api-provider) が適用される）が含まれます。
123
124**はい**を選択するとプラグインがユーザースコープにインストールされます。**いいえ、プラグインインストールヒントを再度表示しない**を選択すると、ユーザーのすべての将来のヒントプロンプトが無効になります。
125
126<h2 id="hint-format">
127 ヒント形式
128</h2>
129
130ヒントは 3 つの必須属性を持つ自己終了型タグです。
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| 属性 | 必須 | 説明 |
137| :------ | :- | :------------------------------ |
138| `v` | はい | プロトコルバージョン。`1` が唯一サポートされている値です |
139| `type` | はい | ヒントの種類。`plugin` が唯一サポートされている値です |
140| `value` | はい | `name@marketplace` 形式のプラグイン識別子 |
141
142属性値は二重引用符で引用するか、引用符なしで残すことができます。引用符なしの値は空白を含むことはできません。エスケープシーケンスはサポートされていません。
143
144<h2 id="requirements">
145 要件
146</h2>
147
148Claude Code はヒントに対して行動する前に 2 つの条件を適用します。どちらかのチェックに失敗したヒントは削除されます。
149
150* **独立した行**: タグは独立した行を占める必要があります。ログステートメント内など、行の途中に埋め込まれたタグは無視されます。行の先頭と末尾の空白は許可されます。
151* **公式マーケットプレイス**: `value` は `claude-plugins-official` などの Anthropic 管理マーケットプレイスのプラグインを参照する必要があります。他のマーケットプレイスを指すヒントは静かに削除されます。
152
153ヒント行は、バージョンまたはタイプが認識されない場合でも、常に出力からモデルに到達する前に削除されるため、マーカーはトークン使用量にカウントされません。
154
155残りのガイダンスは推奨されていますが、強制されていません。Claude Code は CLI がそれに従っているかどうかを観察することはできません。
156
157* **stderr に書き込む**: stderr は `example-cli deploy | jq` などのシェルパイプラインからタグを除外します。Claude Code は両方のストリームをスキャンするため、stdout も機能します。
158* **環境変数でゲートを設定する**: `CLAUDECODE` または `CLAUDE_CODE_CHILD_SESSION` が設定されている場合のみ出力します。[ヒントを出力する](#emit-the-hint)を参照して、2 つの変数がどのように異なるかを確認してください。
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 公式マーケットプレイスにプラグインを取得する
162</h2>
163
164ヒントプロトコルは、公式 Anthropic マーケットプレイス `claude-plugins-official` にリストされているプラグインに対してのみ有効です。Anthropic はそのマーケットプレイスを裁量で管理し、アプリ内送信フォームはプラグインを[コミュニティマーケットプレイス](/docs/ja/plugins#submit-your-plugin-to-the-community-marketplace)に追加します。これはヒントプロトコルがチェックしません。Anthropic パートナー連絡先と協力している場合は、公式マーケットプレイスのリストを調整するために彼らに連絡してください。
165
166<h2 id="see-also">
167 関連項目
168</h2>
169
170* [プラグインを作成する](/docs/ja/plugins): CLI が推奨するプラグインを構築します
171* [プラグインマーケットプレイスを作成および配布する](/docs/ja/plugin-marketplaces): 公式マーケットプレイスの外でプラグインをホストします
172* [環境変数](/docs/ja/env-vars): `CLAUDECODE` および関連変数の完全なリファレンス