cli-builder について
エージェント向けコマンドラインインターフェースの設計とレビューに使うワークフロースキルです。予測しやすいコマンド、機械可読な出力、安全な変更、契約テストを重視します。
主な機能
- 01サービスの実動作に基づくコマンド定義
- 02動詞、フラグ、ヘルプの一貫性
- 03安定した JSON 出力と終了コード
- 04変更の承認ゲートと冪等性
- 05エラー、ドライラン、ヘルプのテスト
活用シーン
- 01エージェント向け CLI の新規設計
- 02曖昧なコマンドや出力の改修
- 03ドライランと承認ガードの追加
- 04リリース前の CLI 動作レビュー
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/cli-builderを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
README.mdevals/evals.jsonreferences/advanced-patterns.mdagent-readiness-checklist.mdimprovement-cycle.mdmcp-vs-cli.mdpython-api-client.mdskill-wrapper-example.mdtemplates/bash-cli-scaffold.sh詳細
CLI ビルダー
CLI は、ツールとエージェントの間の契約として扱います。この契約には、
コマンド名、--help、フラグ、出力スキーマ、終了コード、stderr、プレビューが含まれます。
このファイルはワークフローとして保ち、専門的なガイダンスが必要な場合にのみ、
リンク先のリファレンスを読み込みます。
使用するタイミング
- エージェントが検出して呼び出す新しい CLI を構築するとき。
- プロンプト、曖昧なコマンド、パーサーに適さない出力、誤った成功コードをリファクタリングするとき。
--json、--dry-run、--yes、冪等性、遅延認証を追加またはレビューするとき。
1 つのワークフロー
1. 実際の契約を把握する
（ベンダー認証を共有するサービスを除き）サービスごとに 1 つの CLI を定義します。 コーディング前に実際のヘルスチェック以外の読み取りエンドポイントを調べ、 実際の認証ヘッダーとレスポンスの形式を確認し、コマンドツリーと失敗ケースを記録します。 API ドキュメントだけを根拠にフラグを考案しないでください。HTTP クライアントの場合は、 Python API クライアントのパターンを参照してください。
ローカルのラッパーやファイルシステムのパイプラインには Bash を選びます。HTTP、 JSON、認証状態、または 3 階層のコマンドツリーには Python を選びます。
2. 予測可能なインターフェースを構築する
一貫した動詞／リソースの規則を使います。すべてのコマンドは非対話型で
フラグ駆動とし、不明なフラグを拒否して、具体例を含む役立つサブコマンドのヘルプを提供します。
通常の出力は人が読みやすい形式にしつつ、安定した厳選スキーマ、正規化された型、
決定的な順序を備え、stdout にそれ以外の内容を出さない --json をサポートします。
診断メッセージは stderr に出力し、実態に即したゼロ以外の終了コードを返します。
状態を変更する場合は、データ取得や変更より前に --dry-run を実装し、
破壊的な操作には明示的な --yes／--force の確認を必須にします。作成、
更新、削除を保護し、再実行しても安全にします。認証は遅延させる必要があります。
--help と安全なドライランは、認証情報がなくても動作するようにします。
連鎖するドライラン、サードパーティの JSON、バージョン依存の動作、テキスト照合には、 高度なパターンを使います。ローカルのシェルラッパーが適している場合は、 Bash のひな形を使います。
3. 契約を検証する
構文チェックを実行し、すべてのコマンドで --help を確認し、すべての --json レスポンスを解析し、
引数不足と不明なフラグを確認し、エラーが stderr に出力されることを確かめます。
認証情報なしでドライランを実行し、同一の実行を 2 回行うと 2 回目が何も変更しないことを証明します。
稼働中のサービスに対しては、実際に認証された読み取りをテストし、各変更操作のドライランを実行します。
最終レビューにはエージェント対応チェックリストを使います。
4. ラップして保守する
エントリーポイントのスキルは簡潔に保ち、条件に応じた詳細はリファレンスに記載します。 ラッパーでは、CLI の用途、セットアップ、よく使うコマンド、出力の意味、注意点を説明し、 すべてのフラグを重複して説明しないようにします。 スキルラッパーの例を参照してください。実際の使用後は、 失敗を記録し、改善サイクルに従って修正の優先順位を付けます。
中核となる契約
--helpは発見可能なスキーマであり、使用例を含みます。--jsonは stdout のみで解析でき、エラーには安定した機械可読コードがあります。--dry-runは予定している変更を正確に説明し、書き込みや前提条件の照会を行いません。- 変更操作は明示的に許可され、冪等で、意味のある状態を報告します。
- 終了ステータスで、成功、使用方法の誤り、実行時エラーを区別します。
使用しないタイミング
一度限りの対話型の人間向けコマンド、GUI／TUI や Web UI の設計、会話型エージェントツール、 MCP サーバーには、このスキルを使用しないでください。ツールの境界の選択については、 MCP と CLI の判断ガイドを参照し、一般的な API 契約設計は api-design-and-evolutionに振り分けてください。