ai-create-skill

ai-create-skill

Agent Skills 形式に準拠し、このリポジトリのカテゴリ構成に合った新しい AI エージェントスキルを作成します。

使用する場面

次のような場合に、このスキルを使用します。

• ゼロから新しいスキルを作成する
• プラクティス、パターン、またはツールについて、ユーザーがエージェント向けの指示を定義するのを支援する
• 既存のスキルが正しい形式に従っているか確認する

手順

1. 適切なカテゴリを選択します。 最も具体的に当てはまるカテゴリの下にスキルを配置します。

   • ai/ — あらゆるプロジェクトに適用できる横断的なスキル
   • common/ — あらゆるプロジェクトに適用できる横断的なスキル
   • operations/ — DevOps、CI/CD、デプロイ、インフラストラクチャに関するスキル
   • frontend/ — 一般的なフロントエンドスキル
   • frontend/*/ — 特定の技術に関するスキル
   • backend/ — 一般的なバックエンドスキル
   • backend/*/ — 特定の技術に関するスキル

2. スキルディレクトリを作成します。 スキルの内容が明確にわかる kebab-case の名前を使用します。

   skills/<category>/<skill-name>/
   

3. フロントマターを含む SKILL.md を作成します。 すべてのスキルには、name と description を含む YAML フロントマターを記述した SKILL.md ファイルが必要です。

   ---
   name: <category>-<skill-name>
   description: A single sentence describing what this skill does.
   ---
   

   • name はリポジトリ内で一意である必要があります。

   • description は簡潔にします。スキルの発見とマッチングに使用されます。

4. スキル本文を記述します。 次のセクションを含む Markdown 本文を作成します。

   必須セクション：

   • # <name> — フロントマターの名前と一致するタイトル。その後に1行の概要を記述します。
   • ## When to use — このスキルを有効にすべき状況を箇条書きで示します。
   • ## Instructions — エージェントが従うべき手順を番号付きで記述します。

   任意のセクション：

   • ## Prerequisites — このスキルを適用する前に必要な他のスキルやツール。
   • ## Core concepts — エージェントが正しく推論するために必要な基礎知識。
   • ## Examples — 正しい動作を示す具体的なコード例や出力例。
   • ## References — 外部ドキュメントや規格へのリンク。

5. 人間ではなく、AI エージェント向けの指示を記述します。

   • 明示的で曖昧さのない表現を使います。読み手はドキュメントをざっと読む開発者ではなく、言語モデルです。
   • 命令形を使います。「X を実行する」「Y を決して行わない」「常に Z を行う」のように記述します。
   • 複数の経路がある場合は、判断フローを示します（A の場合は B、それ以外の場合は C）。
   • エージェントが自分で評価できる検証項目を含めます（「Y がなくても X は成り立つか？」と確認する）。
   • 「ベストプラクティスを使う」のような曖昧な指針は避け、具体的な行動を明示します。

6. スキルの対象を絞ります。 1つのスキルは1つの関心事を扱います。スキルが約150行を超える場合は、複数のスキルに分割し、相互に前提条件を参照することを検討します。

7. 必要に応じて、任意の補助ファイルを追加します。

   • scripts/ — エージェントが実行できるヘルパースクリプト（shell、Node.js、Python）。
   • references/ — 補足ドキュメント、チェックリスト、参照表。

8. カテゴリの README を更新します。 skills/<category>/README.md の箇条書きに新しいスキルを追加します。

   - <skill-name>/SKILL.md
   

9. スキルを検証します。

   • フロントマターは有効な YAML として解析できますか？
   • name はリポジトリ内で一意ですか？
   • 「When to use」セクションには、スキルのマッチングに十分な判断材料がありますか？
   • 外部のコンテキストがなくても、指示を実行できますか？
   • AI エージェントはこのファイルだけを読んで、次に何をすべきか正確に理解できますか？

テンプレート

新しいスキルを作成する際のひな形として、次のテンプレートを使用します。

---
name: <category>-<skill-name>
description: A brief description of what this skill does.
---

# <category>-<skill-name>

One-line summary of what this skill accomplishes.

## When to use

Use this skill when:

- Situation A
- Situation B
- Situation C

## Instructions

1. First actionable step.
2. Second actionable step.
3. Additional steps as needed.