新しい CLI ツールを npm 等で配布しても、AI エージェント（Claude Code / Codex など）は学習データにないツールの存在と使い方を知らない。「エージェントに指示すれば使ってくれる」状態にするには、認識経路をツール自身に多層で同梱する。確実な順に:

多層の設計（実装パターン）

1. スキルの自己設置コマンド（最強）: CLI に install-skill 等のサブコマンドを持たせ、同梱した SKILL.md（使い方・入力ファイルの書き方の薄いガイド。スクリプト非同梱）をエージェントのスキル検出ディレクトリ（.claude/skills/ と .agents/skills/ の両方、--user でユーザーレベル）へ書き込む。@playwright/cli の install-skill が先行例。スキルの版が CLI の版と常に一致し、プラグイン等の別配布経路を管理しなくて済む。
2. 入力ファイルの JSON Schema 同梱: 宣言的な設定/シナリオを受け取るツールならスキーマをパッケージに同梱し、scaffold（init）が生成するファイルに $schema を書き込む。AI はスキーマを読めば語彙を正確に書け、人間のエディタ補完・検証にも効く。スキーマとランタイムバリデーションの乖離は空通しになるので、同じ入力集合に対する accept/reject の同値性をテストで固定する（ajv 等でスキーマを実行して照合）。
3. 語彙付き --help: AI は未知の CLI でまず help を叩くので、サブコマンド一覧だけでなく入力ファイルの語彙一覧と最小例まで help に載せ、help 自体を仕様書にする。

判断基準

• スキルを別のプラグイン・マーケットプレイスで配る案は、ツール本体との版不一致と二重の配布管理を生む。ツールが自分で設置する方が自己完結。
• 重い依存（ブラウザ・動画ライブラリ等で GB 級）を持つツールは、エージェントのプラグイン/スキルにコード同梱しない（プラグインキャッシュはバージョン別ディレクトリで再インストールが走る）。コードは npm 等のパッケージマネージャに任せ、スキルは「使い方の薄い層」に限定する。
• TS 等のコードエスケープハッチを提供する場合、例示が自パッケージの import を要求しないか確認する。npx 実行のみの環境では利用側 node_modules にパッケージが存在しないため、型補助は任意層（依存に持つ場合の identity ヘルパー）に分離する。

検証

スキル未設置の素のエージェントに「このツールで○○して」と指示し、help と $schema だけから正しい入力を一発で書けるかを見る。書けなければ help の語彙説明かスキーマの制約記述が不足している。