add-skill

ユーザー向けスキルの追加

AI エージェントに cx CLI コマンドの使い方を教えるスキルを skills/ に作成するためのエンドツーエンドのワークフローです。このスキルは add-command のステップ 6 から呼び出されることが多いですが、既存のコマンドをドキュメント化する際に単独で使用することもできます。

contributing/adding-a-skill.md に、完全なリファレンスガイドとコピーして使えるテンプレートがあります。このワークフローと併せて読んでください。

ステップ 0：対象領域を理解する

何かを書く前に、次の質問に答えてください。

1. ドキュメント化する cx コマンドは何ですか？ コマンドとすべてのサブコマンドを特定します（例：cx alerts list、cx alerts get、cx alerts create）。
2. ユーザーはそのコマンドで何ができますか？ 主な操作、フラグ、対応する出力形式を一覧にします。
3. 対象読者は誰ですか？ スキルを使用するのは AI エージェントであり、人間が直接使用するものではありません。ユーザーの目標を達成できるよう、エージェントが順を追って実行できる指示を書いてください。
4. 情報量の多いリファレンス資料はありますか？ スキーマ、列挙値の一覧、フィールドリファレンス、または約 100 行を超える言語構文は、別の references/ ファイルに含めてください。

ステップ 1：既存のスキルを読む

スキルを書く前に、既存のスキルを読んで、プロジェクトのパターンを把握してください。まず既存のスキルを調べるエージェントは、新しい形式を独自に考案するのではなく、一貫性のある高品質な成果を生み出します。

必ず読むこと：

• contributing/adding-a-skill.md - ディレクトリ構造、フロントマターの規約、リファレンスファイルのルール、コピーして使えるテンプレートを含む完全なガイド
• skills/README.md - ステップ 4 で更新する公開カタログ

既存のスキルを少なくとも 2 つ調べてください：

スキル	調べる理由
skills/cx-alerts/SKILL.md	豊富な例、JSON ペイロード、調査ワークフローを含む REST ベースのコマンドです。共有リファレンスファイルとスキル固有のリファレンスファイルの両方を使用しています
skills/cx-telemetry-querying/SKILL.md	ピラーごとに共有リファレンスファイルを読み込むゲートウェイスキルです。ピラーをまたぐルーティングとリファレンス読み込みのパターンを学ぶのに適しています
skills/cx-dashboards/SKILL.md	複雑な複数ステップのワークフローです。共有リファレンス（dataprime、promql、logs、spans）に加え、スキル固有のリファレンスも使用しています
skills/cx-cost-optimization/SKILL.md	「コスト削減」という意図のもとに 5 つのコマンドをまとめたワークフロースキルです。複数コマンドを扱うスキルの参考になります

作成するスキルに最も近いものを 2 つ選び、最後まで読んでください。

ステップ 2：ディレクトリを作成して SKILL.md を書く

skills/cx-<domain-name>/SKILL.md を作成します。すべてのスキルディレクトリには cx- プレフィックスを付けます。contributing/adding-a-skill.md の「Directory Structure」から「Complete Template」（単一コマンドの場合）、または「Workflow Skills」（複数コマンドの場合）までのセクションにあるディレクトリ構造、フロントマター形式、テンプレートを使用してください。

効果的なトリガー説明を書く

フロントマターの description フィールドは、エージェントがスキルを有効にするかどうかを判断するための主要なトリガー機構です。ファイル内で最も重要な一文です。次の内容を網羅する10 個以上のトリガーフレーズを書いてください。

• 明示的なコマンド名（"list alerts"、"get alert by ID"）
• ユーザーの意図（"investigate alert failures"、"debug noisy alerts"）
• 同義語や表現の違い（"check"、"find"、"search"、"analyze"）
• 分野固有の用語（"SLO breach"、"error budget"）

本文の構成

次の順序に従ってください（たたき台としては contributing/adding-a-skill.md の「Complete Template」セクションを参照してください）。

1. タイトルと導入 - このスキルの対象範囲と使用する cx コマンドを説明する一文
2. CLI Commands テーブル - すべてのサブコマンドについて、| Command | Purpose | Key flags | の形式で記載します。-o json／-o toon と -p <profile> に関する注記も含めます。
3. ワークフロー／調査手順 - エージェントが従うべき手順を番号付きで記載します。情報の確認から始め、検証で終わるようにします。
4. 主な原則 - -o json と jq の使用、複数プロファイルの動作、必ず検証することなどを、4～6 項目で箇条書きにします。
5. 追加リソース - references/ ファイルおよび関連スキルへのリンク

スタイルガイドライン

• AI エージェント向けに記述し、実行する内容と順序を明確にします
• すべての CLI 呼び出しにコードブロックを使用します
• プレースホルダーではなく、実際のフラグ値を使った現実的な例を含めます
• コマンドが -o json に対応している場合は、jq によるフィルタリングの例を示します
• SKILL.md は約200行以内に収め、詳細な内容は references/ に移します

ステップ3：リファレンスファイルを追加して README を更新する

references/ ファイルを作成するタイミングと方法については、contributing/adding-a-skill.md §「Reference Files」に従ってください。また、スキルを公開カタログに追加する方法については、§「Updating skills/README.md」に従ってください。

共通リファレンスとスキル固有のリファレンス

新しいリファレンスファイルを作成する前に、その内容が言語レベルのものか、テレメトリの柱に関するものかを確認してください。

• 言語ガイド（DataPrime の構文、PromQL のガイドライン）→ skills/shared/
• テレメトリの柱に関するハウツー（ログのクエリ、スパンのクエリ、メトリクスのワークフロー、RUM）→ skills/shared/
• スキル固有のスキーマやテンプレート（アラート JSON スキーマ、ダッシュボードウィジェットのテンプレート）→ skills/cx-your-domain/references/

スキルで skills/shared/ のファイルが必要な場合：

1. スキル名とファイル一覧を scripts/sync-shared-references.sh に追加します
2. bash scripts/sync-shared-references.sh を実行します。ファイルが references/ にコピーされます
3. 同期スクリプトの変更と生成された references/ のコピーを一緒にコミットします

新しい共通リファレンスを追加する場合：

1. skills/shared/ に作成します
2. 使用するすべてのスキルについて、同期スクリプトに登録します
3. スクリプトを実行してコピーを生成し、すべてをコミットします

ステップ4：検証する

1. Frontmatter - name がディレクトリ名と一致し、description に10個以上のトリガーフレーズがあり、metadata.version が "0.1.0" であること
2. 本文の完全性 - CLI Commands の表、ワークフローの手順、主要な原則、および追加リソース（リファレンスがある場合）が含まれていること
3. リファレンスへのリンク - SKILL.md 内の references/ パスが、実在するファイルを指していること
4. README の更新 - skills/README.md に新しい行が追加されていること
5. 肥大化していないこと - SKILL.md に、references/ に含めるべき内容が100行を超えて重複していないこと
6. 共通リファレンスの同期 - スキルが skills/shared/ のファイルを使用する場合、bash scripts/sync-shared-references.sh が実行され、生成された references/ のコピーがコミットされていることを確認します
7. エージェントにとっての読みやすさ - AI エージェントはこのスキルを読んだ後、何をすべきか正確に理解できますか？理解できない場合は、不足している手順や例を追加します

高度なトリガー最適化には、/skill-creator スキルを使用して、評価に基づく説明のテストを実行し、トリガーフレーズを反復的に改善してください。

PR の説明には、contributing/adding-a-skill.md §「PR Checklist」の PR チェックリストを使用してください。