| name | ai-friendly-cli |
| description | AI向けCLIツールをAIエージェントが理解・操作しやすいように整備するスキル。 コードベースを分析し、構造化出力・ドキュメント・エラーハンドリング・Claude Code統合などを 段階的に追加・改善する。「AIフレンドリーにして」「AI向けに整備して」「エージェントが使いやすいようにして」 「CLIをAI対応にして」「--jsonを追加して」「AGENT_INSTRUCTIONSを作って」「Claude Codeから使えるようにして」 といった場面で積極的に使うこと。AI向けのCLIやツールを開発している文脈であれば、 明示的に整備を頼まれなくても、改善提案を出すために使って良い。
|
AI-Friendly CLI
AI向けCLIツールを、AIエージェントが確実に理解・操作できるように整備するスキル。
基本方針
AIエージェントがCLIツールを使うとき、人間とは根本的に異なる制約がある:
- 画面が見えない → 構造化出力（JSON）が必須
- キーボードがない → インタラクティブ操作は不可能
- コンテキストウィンドウが有限 → 出力の情報量を制御する必要がある
- エラーの意味を推測できない → エラーメッセージにヒントが必要
- 初見でツールを使う → ドキュメントとヘルプが唯一の手がかり
このスキルは、これらの制約に対応する改善を段階的に適用する。
起動時の手順
1. コードベースを分析する
まず対象リポジトリを探索し、以下を把握する:
- 言語・フレームワーク
- 既存のコマンド一覧
- 現在の出力形式（human-readable only? JSON対応あり?）
- ドキュメントの有無（README、--help の充実度）
- Claude Code統合の有無（.claude/ ディレクトリ）
2. 診断レポートを出す
分析結果を以下の形式でユーザーに提示する:
## 診断結果: {ツール名}
### 現状
- 言語: Go (Cobra)
- コマンド数: 12
- JSON出力: ❌ なし
- ドキュメント: README.md のみ
- Claude Code統合: ❌ なし
### 改善プラン（優先度順）
1. [HIGH] Claude Code SKILL.md の作成
2. [HIGH] 構造化出力の追加
3. [HIGH] AGENT_INSTRUCTIONS.md の作成
4. [MED] 非インタラクティブ設計の徹底
5. [MED] エラーハンドリングの改善
6. [LOW] コンテキスト最適化
ユーザーと相談して、どこから着手するか決める。
一度に全部やるのではなく、優先度の高いものから段階的に進める。
3. 改善を適用する
以下のパターンカタログから適切なものを選び、実際にコードとドキュメントを書く。
各パターンの詳細は references/patterns.md を参照。
パターンカタログ（概要）
改善パターンは大きく6つのカテゴリに分かれる。
それぞれの実装方法・テンプレート・具体例は references/patterns.md にまとめてある。
1. Claude Code SKILL.md [HIGH]
リポジトリ内に skills/{tool-name}/SKILL.md として配置し、ユーザーに配布する。
ユーザーは npx skills add owner/repo や手動コピーで ~/.claude/skills/ にインストールする。
ルートに直接SKILL.mdを置いてはいけない。必ず skills/{tool-name}/ ディレクトリを作ること。
my-tool/
├── src/
├── skills/
│ └── my-tool/
│ ├── SKILL.md # AIが最初に読むファイル
│ ├── README.md # インストール手順（人間向け）
│ └── references/ # 詳細ドキュメント（必要に応じて）
└── README.md
SKILL.mdは必ずYAMLフロントマターから始めること。これがないとスキルとして認識されない:
---
name: my-tool
description: >
ツールの説明。トリガー条件のフレーズも含める。
---
name と description は必須。# 見出し から始めてはいけない。
フロントマターの後に、ツールの目的、コマンド一覧、ワークフロー、注意点をまとめる。
テンプレートと詳細は references/patterns.md のセクション1を参照。
2. 構造化出力 [HIGH]
すべてのコマンドに --json フラグを追加し、機械可読な出力を提供する。
エラー出力もJSON化する。成功時・エラー時の両方で一貫したスキーマを保つ。
3. AI向けドキュメント [HIGH]
AGENT_INSTRUCTIONS.md（AIエージェント向けの操作マニュアル）を作成する。
CLIヘルプも「AIが読んで即使える」レベルに整える。
4. 非インタラクティブ設計 [MED]
エディタ起動、対話的プロンプト、ページャーなど、AIが操作できないUIを排除する。
すべての入力をフラグまたはstdinで受け付ける。
5. エラーハンドリング [MED]
エラーを3段階（Fatal / Warn / Silent）に分類し、JSON出力時にはヒントを含める。
AIが「次に何をすべきか」わかるエラーメッセージにする。
6. コンテキスト最適化 [LOW]
出力の情報量を段階的に制御する仕組み（brief/normal/full）を提供する。
大量のデータを返すコマンドにはコンパクション機能を追加する。
改善の進め方
- 一度に全パターンを適用しようとしない。1-2パターンずつ着手する
- 各パターン適用後、実際にCLIを叩いて動作確認する
- ユーザーの開発フローを壊さないよう、既存の動作を維持しつつ拡張する
- 既存コードの規模やスタイルに合わせた実装をする（過剰な抽象化をしない）
パターンの実装詳細が必要になったら references/patterns.md を読むこと。
