AgentSkillsCN

create-cli

CLI 参数与用户体验设计：包括参数、标志、子命令、帮助文本、输出格式、错误信息、退出码、提示符、配置与环境变量的优先级，以及安全模式与“试运行”功能的设置。适用于 CLI 规范设计（在正式实现之前）或对现有 CLI 进行重构优化。

SKILL.md
--- frontmatter
name: create-cli
description: CLI パラメータと UX 設計：引数、フラグ、サブコマンド、ヘルプテキスト、出力形式、エラーメッセージ、終了コード、プロンプト、設定/環境変数の優先順位、安全/dry-run 動作。CLI 仕様設計（実装前）や既存 CLI のリファクタに使用。

Create CLI

CLI 設計（構文 + 動作）、人間優先、スクリプトフレンドリー。

最初にやること

  • •agent-kit/skills/create-cli/references/cli-guidelines.md を読んでデフォルト基準として適用
  • •上流/完全ガイドライン: https://clig.dev/
  • •インターフェースを決めるのに必要な最小限の確認質問のみ

確認（高速）

質問し、ユーザーが不明な場合はベストゲスのデフォルトで進む:

  • •コマンド名 + 一文の目的
  • •主なユーザー: 人間、スクリプト、または両方
  • •入力ソース: 引数 vs stdin、ファイル vs URL、シークレット（フラグ経由は禁止）
  • •出力契約: 人間用テキスト、--json、--plain、終了コード
  • •対話性: プロンプト許可？--no-input 必要？破壊的操作の確認？
  • •設定モデル: フラグ/環境変数/設定ファイル、優先順位、XDG vs リポジトリローカル
  • •プラットフォーム/ランタイム制約: macOS/Linux/Windows、単一バイナリ vs ランタイム

成果物（出力するもの）

CLI 設計時、ユーザーが実装できるコンパクトな仕様を作成:

  • •コマンドツリー + USAGE 概要
  • •引数/フラグ表（型、デフォルト、必須/任意、例）
  • •サブコマンドの意味（各動作、冪等性、状態変更）
  • •出力ルール: stdout vs stderr、TTY 検出、--json/--plain、--quiet/--verbose
  • •エラー + 終了コードマップ（主な失敗モード）
  • •安全ルール: --dry-run、確認、--force、--no-input
  • •設定/環境変数ルール + 優先順位（フラグ > 環境変数 > プロジェクト設定 > ユーザー設定 > システム）
  • •シェル補完（該当する場合）
  • •5-10 の実行例（一般的なフロー、パイプ/stdin 例を含む）

デフォルト規約

  • •-h/--help は常にヘルプを表示し他の引数を無視
  • •--version はバージョンを stdout に出力
  • •主要データは stdout、診断/エラーは stderr
  • •機械出力用に --json を追加、安定した行ベーステキスト用に --plain を検討
  • •プロンプトは stdin が TTY の時のみ、--no-input でプロンプト無効化
  • •破壊的操作: 対話的確認 + 非対話的は --force または明示的 --confirm=... が必要
  • •NO_COLOR、TERM=dumb を尊重、--no-color を提供
  • •Ctrl-C: 高速終了、制限付きクリーンアップ、可能なら crash-only

テンプレート

CLI 仕様スケルトン

code
1. **名前**: `mycmd`
2. **一文説明**: `...`
3. **USAGE**:
   - `mycmd [global flags] <subcommand> [args]`
4. **サブコマンド**:
   - `mycmd init ...`
   - `mycmd run ...`
5. **グローバルフラグ**:
   - `-h, --help`
   - `--version`
   - `-q, --quiet` / `-v, --verbose`
   - `--json` / `--plain`
6. **I/O 契約**:
   - stdout:
   - stderr:
7. **終了コード**:
   - `0` 成功
   - `1` 一般的な失敗
   - `2` 無効な使用法（パース/検証）
8. **環境変数/設定**:
   - 環境変数:
   - 設定ファイルパス + 優先順位:
9. **例**:
   - …