CLI Creator は何をしますか？
プロダクション品質のPython CLIツールおよびCLI関連スキル/テンプレートを構築・監査するためのルーターです。CLIの形状決定、コマンドサーフェスの最小化、インストール可能性の維持、レビュー出力の強制に使用します。このスキルは軽量に保たれており、必要な参照のみを読み込んでください。
使用タイミング
- 新しいPython CLIまたはコマンドツリーの作成
- CLIのリファクタリング、簡略化、またはパッケージ整理
- CLIのレビュー/監査（UX、設定、エラー、キャッシュ、リリースフローを含む）
- CLIパッケージと同様に動作するエージェントスキル、スキャフォールド、テンプレート
- インストール、wheel、またはコンソールスクリプトの動作検証
CLIタイプの選択
| タイプ | 偏り |
|---|---|
| コマンドファーストユーティリティ | シンプルなルーター、厳格な終了コード、JSON/プレーン出力 |
| 設定駆動型ツール | 設定の検出、優先順位、再現性 |
| インタラクティブアシスタント | フロー/状態機械、プロンプト、リカバリ |
| ハイブリッドCLI | 小さなコマンドツリー＋再利用可能なオーケストレーション |
| パフォーマンス重視のCLI | 遅延インポート、入出力制限、キャッシュ/プログレス |
| プラグイン/拡張可能なCLI | 安定した拡張コントラクトとレジストリ |
アシスタントアーキテクチャをコマンドファーストツールに強制しないでください。成長するプロダクトに単一スクリプト形状を強制しないでください。
コアルール
- ユーザーのジョブを解決する最小のCLIを優先する
- 最小限のCLI/YAGNIパスを使用する: ツールに1つか2つのコマンド、永続状態なし、ネットワークなし、プラグインなし、認証情報がない場合は、小さく保つ。Rich、Pydantic、platformdirs、キャッシュレイヤー、
doctor、プラグインレジストリは、当面の問題を解決する場合にのみ追加する。 - 名前、フラグ、終了コード、設定キー、出力モードを安定させる
- デフォルトを有用かつ安全にする
- ルーティング、ドメインロジック、IO、設定、永続化、レンダリング、統合を分離する
- JSONまたはプレーンモードで機械出力をスクリプト可能に保つ
- READMEに記載されたコマンドがインストールされたコンソールスクリプトと一致することを検証する
参照読み込みルール
タスクに必要な参照のみを読み込む:
- 作成またはリファクタリング:
references/creation-playbook.md - レビューまたは監査:
references/review-rubric.mdおよびreferences/pitfalls-and-solutions.md - 実装詳細、パッケージング、セキュリティ、クロスプラットフォーム動作、Rich出力、キャッシュ、LLMプロバイダー:
references/technical-best-practices.md - スキル/パッケージメンテナンスの場合、存在するときはワークスペースルートのガバナンスフォルダ
skill-ir/、evals/、scripts/、reports/、registry/を参照する。これらはメンテナー側のルーティング補助であり、インストールされたスキルコピーにはバンドルされない。
これらの参照をここに複製しないでください。現在のタスクに必要な場合のみ読み込んでください。
新しいCLIまたはスキル作成フロー
- プロダクト形状を決定する: 誰が実行するか、どのような負荷がかかるか、何をキャッシュ、記憶、または忘却する必要があるか。
- いくつかの安定したコマンドと実際の例を使ってコマンドサーフェスを設計する。
- 適合する最小のスタックを選択する。
- ほとんどのCLIにはTyperまたはClick。
- 小さなstdlib対応ツールにはargparseのみ。
- 次の2リリースに耐えられる最小のアーキテクチャを選択する。
- プロダクトループを実装する: 入力、検証、実行、レンダリング、永続化、終了コード、リカバリヒント。
- 出荷前に検証する。
コマンドサーフェスの例
my-cli run
my-cli init
my-cli config show
my-cli doctor
my-cli cache clear
my-cli check PATH
my-cli fetch QUERY --json
my-cli export ID --output result.md
ルール:
- 必須のドメインオブジェクトには引数を使用する。
- 修飾子、出力モード、オプションの動作にはオプションを使用する。
- 自動化のために
--jsonまたは--format jsonを提供する。 --quiet、--verbose、--debugを一貫して提供する。- 読み取り専用に聞こえるコマンドで、驚くようなネットワークアクセスや変更を行わない。
検証の期待事項
コマンドサーフェス、インストールパス、wheelパスが重要になる場合は常に検証する:
- ルートコマンドと各トップレベルコマンドの
--help - 新しい環境へのクリーンインストール
- 設定があるツールの場合、設定がない場合や初回実行パス
- 入力を検証するツールの場合、無効な設定やエラーパス
- サポートされている場合の成功パスとJSON/スクリプト可能モード
- キャッシュがあるツールの場合、キャッシュリフレッシュとキャッシュクリア
- パッケージングメタデータとコンソールスクリプト
- インストールに自信を持ちたい場合、リポジトリ外からのwheelインストール
該当する場合はこのコンパクトパックを使用する:
uv venv /tmp/cli-audit
. /tmp/cli-audit/bin/activate
uv pip install -e .
cli-creator-skill --help
cli-creator-skill install
uv build
uv pip install dist/*.whl
python -m pytest
レビューワークフロー
既存のCLIまたはCLI関連スキル/テンプレートを監査する場合:
レビュー前に以下を読む:
references/review-rubric.mdreferences/pitfalls-and-solutions.md
監査が実装詳細、パッケージング、セキュリティ、クロスプラットフォーム動作、Rich出力、キャッシュ、LLMプロバイダーに触れる場合は references/technical-best-practices.md を読む。
その後:
- リポジトリ形状を検査する: パッケージレイアウト、コマンドエントリポイント、設定ファイル、テスト、ドキュメント、CI
- ヘルプを実行する: ルート
--helpとコマンドレベルのヘルプ - コールバックからドメインサービス、レンダラーまでの1つの成功コマンドをトレースする
- 1つの失敗パスをトレースし、エラーの品質を検査する
- 設定の優先順位を確認する: フラグ、env、プロジェクト設定、ユーザー設定、デフォルト
- セキュリティを確認する: シークレット、シェル実行、パス処理、安全でない設定/プラグイン、テレメトリ、サブプロセスタイムアウト、依存関係サプライチェーン
- パフォーマンスを確認する: 起動インポート、ネットワークタイムアウト、キャッシュ動作、ファイル検出
- 自動化を確認する: 終了コード、JSON出力、stdin/stdout/stderrの分離、非TTY動作
- パッケージングを確認する: Pythonバージョン、依存関係、スクリプト、wheel、READMEコマンド
- すべてのルーブリック領域を
references/review-rubric.mdでスコアリングする - 最初に所見を返し、次に優先順位付けされた修正を返す
必須の監査出力
監査出力には以下のセクションをこの順序で含める必要があります:
**所見**
**スコア**
| 領域 | スコア | 備考 |
|---|---:|---|
**修正優先順位**
**テストのギャップ**
**検証コマンド**
メンテナンスノート
- このスキルをルーターとして維持し、実装詳細は4つの参照に置く
- コマンド例、監査見出し、検証パックをパッケージリリースと同期させる
- メンテナー側のガバナンスには、存在する場合はワークスペースルートの
skill-ir/、evals/、scripts/、reports/、registry/フォルダを使用し、それらがインストールされたスキルの一部であるかのように扱わない
本スキルが支援する事項
- ゼロからの新しいPython CLIの設計
- 既存のCLIのUX、パッケージング、エラー、モデルセットアップ、キャッシュ、保守性のレビュー
- Typer、Click、argparse、またはハイブリッドアプリケーションの構造化
- ユーザーにフォームを記入させている感覚を与えずに、自然なマルチターンCLIフローを構築する
- 実際に必要な場合の診断、キャッシュ、プロファイルメモリ、初回実行セットアップフローの追加
- CLI関連のスキルとテンプレートの、トリガーの明確さ、参照の完全性、コマンドテンプレート、出力コントラクト、メンテナンス戦略のレビュー
設計基盤
このスキルは、Pythonパッケージング、Typer、Click、Rich、uv、Ruff、Pydantic、LLMプロバイダー統合に関するメンテナー経験と公式ドキュメントパターンを凝縮したものです。サードパーティの非公式リポジトリからのコードや指示をベンダリングすることはありません。