--- name: cli-reference-writing description: CLI を利用するための Skill を新規作成または更新するための規範。Git、GitHub CLI、D2 などの CLI について、ユースケース指向の `references/` を構成し、公式文書とローカル CLI で検証し、更新可能な情報源とシナリオ試験を整備するときに使う。 --- # CLI Reference Writing CLI リファレンス Skill は、宣言済みのユースケースをヘルプの事前参照なしで安全に完了できる状態にする。 CLI 全体のマニュアルを転載しない。 ## 成果物 - `SKILL.md`：対象範囲、判断規則、通常のワークフロー、各参照ファイルへの導線を置く。 - `references/`：必ず作成する。 少なくとも1つの CLI 操作リファレンスを置き、すべてのユースケースをいずれかのファイルへ対応付ける。 関連するユースケースを1ファイルにまとめ、`SKILL.md` から一段で参照できるようにする。 - `references/validation.md`：シナリオ試験の記録を残す。 このファイルは CLI の操作リファレンスではないため、情報源の形式は適用しない。 - `agents/openai.yaml`：Skill の役割に合わせて更新する。 ユースケースごとに別ファイルを強制しない。 1つのファイルに無関係な操作を集めない。 ## 対象範囲を固定する 既存 Skill を更新する場合は、現在の description と本文から対象ユースケースを列挙する。 新規 Skill では、利用者が求める仕事を完了するためのユースケースだけを列挙する。 各ユースケースについて、含める操作、含めない操作、開始前に必要な状態を決める。 便利そうという理由だけで操作を追加しない。 対象 CLI が独自の言語や設定形式を入力に取る場合は、そのユースケースを完了する最小の記法も対象に含める。 対象範囲と参照ファイルの構成は、更新する `SKILL.md` に明示する。 [作成と監査のチェックリスト](references/authoring-checklist.md) で漏れを確認する。 ## 一次情報を確定する 公式ドキュメントで操作の意味、安全上の注意、推奨される手順を確認する。 インストール済み CLI のバージョン、対象サブコマンドのヘルプ、必要な実行結果で構文を確認する。 各 CLI 操作リファレンスの先頭に、次を記録する。 - 公式ドキュメントの直接 URL - 検証した CLI の完全なバージョン - 構文確認に使ったコマンド 公式文書を転載しない。 対象ユースケースに必要な判断と最小のコマンド列へ要約する。 ## リファレンスを構成する 各ユースケースには、次の項目を置く。 1. **目的**：完了状態を示す。 2. **前提条件**：確認する状態、権限、入力を示す。 3. **推奨コマンド**：安全な順序と必要なオプションを示す。 4. **結果の確認**：成功を確認するコマンドまたは観察を示す。 5. **停止条件**：自動で進めず利用者へ確認する条件を示す。 6. **代表的な失敗**：症状、原因の切り分け、次の確認を示す。 危険な変更、状態依存の操作、失敗時の回復が必要な操作では、停止条件を具体的に書く。 安全な操作を原則だけで済ませず、実行前後の確認も書く。 ## ヘルプのフォールバックを限定する 記録済みバージョンで検証済みのユースケースは、事前に `--help` を読まずリファレンスに従う。 次の場合だけ、必要なサブコマンドのヘルプを参照する。 - 要求された操作が対象ユースケースに含まれない。 - インストール済み CLI のバージョンが記録と異なり、対象コマンドの構文や挙動を確認できない。 - 実行結果が、未対応オプションや変更された構文を示す。 既知のサブコマンドがある場合は、` --help` のように範囲を絞る。 念のために CLI 全体のヘルプを読むことはしない。 確認した差分がリファレンスの内容を変える場合は、情報源、検証バージョン、確認コマンドを更新する。 ## 検証する 実装後は [作成と監査のチェックリスト](references/authoring-checklist.md) に従い、静的確認を済ませて Agent のシナリオを試験する。 シナリオ試験の結果は、対象 Skill の `references/validation.md` に追記する。 構造検査のスクリプトは、複数の CLI Skill で同じ機械判定を繰り返すことが確認できるまで作らない。 反復可能な規則が固まった時点で、その最小の検査だけを自動化する。