cli-creator

CLI クリエーター

将来の Codex スレッドが、どの作業ディレクトリからでもコマンド名で実行できる、本格的な CLI を作成します。

このスキルは、長期的に使うツール向けであり、その場限りのスクリプト向けではありません。現在のリポジトリに短いスクリプトを書けばタスクを解決できる場合は、代わりにそのリポジトリにスクリプトを書いてください。

開始

対象のツール、その情報源、最初に実行する実際の作業を指定します。

• 情報源：API ドキュメント、OpenAPI JSON、SDK ドキュメント、curl の例、ブラウザーアプリ、既存の内部スクリプト、記事、または動作するシェル履歴。
• 作業：list drafts、download failed job logs、search messages、upload media、read queue schedule など、具体的な読み取り／書き込み操作。
• インストール名：ci-logs、slack-cli、sentry-cli、buildkite-logs など、短いバイナリ名。

ユーザーが個人用ツールを希望していて、リポジトリを指定していない場合は、~/code/clis/<tool-name> の下に新しいフォルダーを作成することをおすすめします。

ひな形を作成する前に、提案されたコマンドがすでに存在するか確認します。

command -v <tool-name> || true

存在する場合は、より明確なインストール名を選ぶか、ユーザーに確認してください。

ランタイムを選ぶ

選択する前に、ユーザーのマシンと情報源を確認します。

command -v cargo rustc node pnpm npm python3 uv || true

次に、最も自然なツールチェーンを選びます。

• どのリポジトリからでも Codex が実行できる、長期的に使う CLI には、Rust を標準として選びます。高速な単一バイナリ、優れた引数解析、使いやすい JSON 処理を備え、~/.local/bin へのコピーやインストールも簡単です。
• 公式 SDK、認証ヘルパー、ブラウザー自動化ライブラリ、または既存リポジトリのツール群を使うことで CLI が優れたものになる場合は、TypeScript/Node を使用します。
• 情報源がデータサイエンス、ローカルファイル変換、ノートブック、SQLite/CSV/JSON の分析、または長期的に使うコマンドとしてインストールできる Python 中心の管理ツールである場合は、Python を使用します。

CLI が実質的に改善されない限り、セットアップの手間が増える言語は選ばないでください。最適な言語がインストールされていない場合は、ユーザーの承認を得て不足しているツールチェーンをインストールするか、次善のインストール済みの選択肢を使ってください。

ひな形を作成する前に、選択した理由と確認できたインストール済みのツールチェーンを含め、選択内容を一文で伝えます。

コマンドの仕様

コーディングを始める前に、チャットでコマンドの構成案を示します。バイナリ名、探索コマンド、名前解決または ID 検索コマンド、読み取りコマンド、書き込みコマンド、低レベル操作用の手段、認証／設定方法、PATH への追加／インストールコマンドを含めます。

コマンドの構成を設計する際は、期待される組み合わせ可能な CLI の形式について、references/agent-cli-patterns.md を読んでください。

次の構成を目指します。

• tool-name --help で主要な機能をすべて確認できます。
• tool-name --json doctor で設定、認証、バージョン、エンドポイントへの到達性、不足しているセットアップを確認できます。
• 環境変数だけでの認証が不便な場合は、tool-name init ... でローカル設定を保存できます。
• 探索コマンドで、アカウント、プロジェクト、ワークスペース、チーム、キュー、チャンネル、リポジトリ、ダッシュボード、その他の最上位コンテナーを見つけられます。
• 名前、URL、スラッグ、パーマリンク、顧客からの入力、ビルドリンクを安定した ID に変換する解決コマンドを用意し、後続のコマンドで広範な検索を繰り返さずに済むようにします。
• 読み取りコマンドで、正確なオブジェクトを取得し、コレクションの一覧表示や検索ができます。ページ分割された一覧では、上限を設けた --limit、カーソル、オフセット、または明確に文書化されたデフォルト値に対応します。
• 書き込みコマンドは、作成、更新、削除、アップロード、スケジュール、再試行、コメント、下書きなど、名前が明確な操作をそれぞれ一つだけ実行します。最も範囲を絞れる安定したリソース ID を受け取り、サービスが対応している場合は、まず --dry-run、draft、または preview を利用できます。また、fix、debug、auto のような広範なコマンドの中に書き込み操作を隠しません。
• --json で安定した機械可読形式の出力を返します。
• request、tool-call、api、または実態に最も合った名前で、低レベル操作用の手段を用意します。

汎用的な request コマンドだけを公開しないでください。繰り返し行う作業には、Codex が使える高レベルの動詞を用意します。

CLI の README または同等の文書に、API のパススルー形式と CLI のエンベロープ形式のどちらを使うか、成功時の形式、エラー時の形式、各コマンド群の例を記載します。--json でのエラーは機械可読形式とし、認証情報を含めてはいけません。

認証と設定

まずは基本的な方法を、次の優先順位でサポートしてください。

1. GITHUB_TOKEN など、サービスで標準的に使われている名前の環境変数。
2. ~/.<tool-name>/config.toml または、別途簡潔に説明したパスにあるユーザー設定。
3. --api-key やツール固有のトークンフラグは、明示的な一度限りのテストに限って使用してください。通常の利用では環境変数や設定ファイルを優先してください。フラグはシェルの履歴やプロセス一覧に漏れる可能性があるためです。

トークン全体を表示しないでください。doctor --json では、トークンが利用可能かどうか、認証元のカテゴリ（flag、env、config、プロバイダーのデフォルト、または未設定）、不足しているセットアップ手順を示してください。

CLI がネットワークや認証なしで実行できる場合は、そのことを doctor --json ではっきり示してください。フィクスチャ／オフラインモードかどうか、フィクスチャデータが見つかったかどうか、そのモードで認証が不要かどうかを報告してください。

DevTools の curl から情報を得た社内 Web アプリでは、実装前にサニタイズ済みのエンドポイント情報を作成してください。リソース名、メソッド／パス、必須ヘッダー、認証方式、CSRF の挙動、リクエスト本文、レスポンスの ID フィールド、ページネーション、エラー、機密情報を伏せたレスポンスのサンプルを 1 つ記載します。コピーした Cookie、Bearer トークン、顧客の秘密情報、または本番環境のペイロード全体を絶対にコミットしないでください。

スクリーンショットは、ワークフロー、UI の用語、フィールド、確認ポイントの推測に使用してください。ネットワークリクエスト、エクスポート、ドキュメントページ、またはフィクスチャと組み合わせていない限り、スクリーンショットを API の根拠として扱わないでください。

ビルドのワークフロー

1. リソース、認証、ページネーション、ID、メディア／ファイルのフロー、レート制限、危険な書き込み操作を把握するために必要な範囲で、ソースを確認してください。ドキュメントで OpenAPI が公開されている場合は、コマンド名を決める前にダウンロードするか、内容を調べてください。
2. コマンド一覧をチャットで草案として作成してください。名前は短く、シェルで使いやすいものにしてください。
3. README など、リポジトリ利用者向けの説明を添えて CLI のひな型を作成してください。
4. doctor、探索、解決、読み取りコマンド、要望がある場合は範囲を絞った下書きまたはドライランの書き込み経路を 1 つ、そして生のエスケープハッチを実装してください。
5. CLI を PATH にインストールし、ソースフォルダーの外でも tool-name ... が動作するようにしてください。
6. cargo run やパッケージマネージャーのラッパーだけに頼らず、別のリポジトリまたは /tmp からスモークテストを実施してください。command -v <tool-name>、<tool-name> --help、<tool-name> --json doctor を実行してください。
7. フォーマット、型チェック／ビルド、リクエストビルダーのユニットテスト、ページネーション／リクエスト本文ビルダー、認証なしの doctor、ヘルプ出力、そしてフィクスチャ、ドライラン、または読み取り専用 API の実呼び出しを少なくとも 1 つ実行してください。

信頼性を確かめるために実際の書き込みが必要な場合は、先に許可を求め、取り消し可能な方法にするか、下書きのみで実行してください。

ソースが既存のスクリプトまたはシェル履歴の場合は、動作する呼び出しを実際のフェーズに分割してください。セットアップ、探索、ダウンロード／エクスポート、変換／インデックス作成、下書き、アップロード、ポーリング、実際の書き込みです。ユーザーがすでに利用しているフラグ、パス、環境変数を維持し、繰り返し実行するフェーズを、安定した ID、サイズを制限した JSON、ファイル出力でラップしてください。

生のエスケープハッチは、まず読み取り専用の呼び出しをサポートしてください。ユーザーから特定の書き込みを依頼されていない限り、稼働中のサービスに対して、生の非 GET／HEAD リクエストを実行しないでください。

メディア、成果物、または署名付きアップロード URL を使うフローでは、各フェーズを個別にテストしてください。アップロードの作成、バイト列の転送、処理状況のポーリング／読み取り、そして生成された ID の紐付けまたは参照です。

フィクスチャを利用するプロトタイプでは、フィクスチャを予測しやすいプロジェクト内のパスに配置し、インストール後も CLI から見つけられるようにしてください。ソースフォルダー内でしか動作しないバイナリを検出するため、/tmp からスモークテストを実施してください。

ログ中心の CLI では、決定的なスニペット抽出とモデルによる解釈を分離してください。ファイル名、行番号またはバイト範囲、一致したルール、短い抜粋を出力するコマンドを優先してください。

Rust のデフォルト設定

Rust でビルドする場合は、独自のパーサーを作るのではなく、定評のあるクレートを使用してください。

• コマンドとヘルプには clap
• HTTP には reqwest
• ペイロードには serde／serde_json
• 小規模な設定ファイルには toml
• CLI に適したエラーコンテキストには anyhow

make install-local などの Makefile ターゲットを追加し、release をビルドして、バイナリを ~/.local/bin にインストールしてください。

TypeScript/Node のデフォルト

TypeScript/Node で開発する場合は、CLI を通常のコマンドとしてインストールできる状態にしてください。

• コマンドとヘルプには commander または cac
• API 呼び出しには、ネイティブの fetch、公式 SDK、またはユーザーが既に使用している HTTP ヘルパー
• 外部ペイロードの検証によって実際の不具合を防げる場合に限り zod
• インストールするコマンドには package.json の bin エントリ
• リポジトリの既存の規約に従って tsup、tsx、または tsc

pnpm install、pnpm build、pnpm link --global などのインストール手順、または小さなラッパーを ~/.local/bin にインストールする Makefile ターゲットを追加してください。

Python のデフォルト

Python で開発する場合は、ワークフローで追加のものが必要でない限り、シンプルな標準ライブラリを優先してください。

• コマンドとヘルプには argparse、サブコマンドが煩雑になる場合は typer
• HTTP には、既にインストール済み、または近くのコードで既に使われているものに合わせて urllib.request / urllib.parse、requests、または httpx
• ローカルファイル、エクスポート、データベース、既存のスクリプトには json、csv、sqlite3、pathlib、subprocess
• インストールするコマンドには pyproject.toml のコンソールスクリプト、または小さな実行可能ラッパー
• 依存関係が実際に必要な場合に限り uv または仮想環境

コマンドを PATH 上にインストールする make install-local などの Makefile ターゲットを追加し、uv、仮想環境、またはシステムの Python のみのどれに依存するかをドキュメントに記載してください。

コンパニオンスキル

CLI が動作したら、その CLI 用の小さなスキルを作成するか、更新してください。利用可能な場合は $skill-creator を使用してください。ユーザーがリポジトリ内の .codex/skills/... パスや別のスキルリポジトリを指定していない限り、個人用コンパニオンスキルには $CODEX_HOME/skills/<tool-name>/SKILL.md を使用してください。

コンパニオンスキルは、すべての機能を紹介するのではなく、今後の Codex スレッドで CLI を使う順序に沿って記述してください。次の内容を説明してください。

• インストール済みのコマンドが存在することを確認する方法。
• 最初に実行するコマンド。
• 認証の設定方法。
• 共通 ID を特定する検索コマンド。
• 安全な読み取り手順。
• 想定される下書き／書き込み手順。
• 直接操作するための代替手段。
• ユーザーの明示的な承認なしに行ってはいけないこと。
• コピーして実行できるコマンド例を 3 つ。

API リファレンスの詳細は、CLI のドキュメントまたはスキルのリファレンスファイルに記載してください。スキルは、今後の Codex スレッドで実際に使う手順、安全性、例に焦点を絞ってください。