create-skill

スキルの作成

このスキルは、Agent Skills 仕様および dotnet/skills リポジトリの規約に準拠した新しいエージェントスキルのひな形を作成します。

使用する場面

• 新しいスキルを一から作成するとき
• 適切なフロントマターを含む SKILL.md ファイルを生成するとき
• 任意のフォルダーを含むスキルのディレクトリ構造を設定するとき
• agentskills.io 仕様への準拠を確認するとき

使用しない場面

• 既存のスキルを変更するとき（直接編集してください）
• 評価に失敗するスキルの診断や修正を行うとき（improve-skill-quality を使用してください）
• スキルの eval.yaml を作成するとき（create-skill-test を使用してください）
• カスタムエージェントを作成するとき（agents/ ディレクトリのパターンを使用してください）

入力

入力	必須	説明
スキル名	はい	小文字の英数字とハイフンのみ（例：code-review、ci-triage）
説明	はい	スキルの内容と、エージェントが使用すべき場面（1～1024 文字）
目的	はい	成果を説明する 1 段落
ワークフローの手順	推奨	エージェントが従うべき番号付きの手順

ワークフロー

ステップ 1：スキル名を検証する

名前が次の条件を満たしていることを確認します。

• 小文字、数字、ハイフンのみを含む
• ハイフンで始まったり終わったりしない
• ハイフンが連続していない
• 1～64 文字である

ステップ 2：説明を書く — 説明が振り分けの役割を担います

実行時にスキルを読み込むかどうかを判断する際、ランタイムが見るテキストは description だけです。 説明が弱ければ、その後ろに完璧な本文があっても実行されません。

---
name: <skill-name>
description: <what it does>. USE FOR: <symptoms, error codes, artifact names, quoted user requests>. DO NOT USE FOR: <nearby-but-wrong intents, with the skill that owns them>.
---

• 動作を表す動詞から始め、ユーザー自身の言葉を使います。症状、エラーコード（CS1501、 MSTEST0014）、成果物の名前（.testsettings、binlog）、そして開発者が入力するような表現のリクエストを含めます。
• トピックではなく、実際の判別基準に基づいて、兄弟スキルとの振り分けを明確にします。「その抽象化はすでに存在するか？」なら 2 つのスキルを区別できますが、「テスト」では区別できません。両方の兄弟スキルに対応する除外条件を追加します。
• なければ兄弟スキルに振り分けられてしまう、曖昧な語句を自分のスキルの対象として明示します。プロンプトで「テストをレビューして」と言われる可能性があり、兄弟スキルが「レビュー」を対象としているなら、そのことを明記します。
• DO NOT USE FOR の各項目が、そのスキルが対応するシナリオと矛盾しないか確認します。「すでに v3 である」といった除外条件によって、そのスキルの目的であるアップグレード後の修正まで対象外にしてしまう場合があります。
• 文字数の上限は、説明ごとに 1,024 文字です。プラグイン全体でレンダリングされるスキルメニューにも文字数の上限があります。ヘルパーやリファレンスのカタログでは、disable-model-invocation: true を設定すると、メニューの文字数を節約できます。この場合も読み取り可能なリソースとして残り、モデルが名前で呼び出せるスキルにはなりません。利用者は、指定されたカタログパス（ネイティブ評価ではステージングされたパス）を使って、カタログまたは同梱ファイルを直接読み込みます。同梱ファイルのパスは、プロジェクトのワークスペースではなくカタログを基準に解決します。
• XML タグは使用しません。Claude（claude.ai および Claude Code マーケットプレイスの同期機能）は、Vector<T> や <Import> のようなタグに見えるテキストを含む説明を拒否します。「ジェネリックな Vector 型」や「Import 要素」のように、言葉で表現してください。skill-validator check はこのような記述があると失敗します。

Step 3: ベースラインモデルとの差分を意識して書く

各スキルは、スキルを読み込んでいない同じモデルと直接比較して評価されます。モデルが何も手助けされずにすでに出力できる内容には価値がありません。回答を遅くしたり、必要以上に慎重にしたりする内容は、価値がマイナスになります。根拠の全容については、 improve-skill-quality/references/writing-for-baseline-delta.md を参照してください。

推奨事項	代わりに避けること
モデルが誤る判断を明示する	すでに再現できる API シグネチャを言い換える
「A の場合は B を行い、C は決して行わず、D を検証する」形式の表を使う	もっともらしい選択肢のリスト
具体的な出力契約（正確なコマンド、判定行、所見の表）を定める	「検討してください」「そうするとよいかもしれません」
入力の規模に合わせて出力の構成を調整する	8 件のテストスイートに 12 セクションのダッシュボードを用意する
過剰な適用を防ぐ停止条件を設ける	測定前に動く、動作するコードを書き直す
エージェントにリポジトリ内のパスを見つけるよう指示する	簡単に見つけられるパスを必須入力として指定する
復元／ビルド／テストの失敗を正直に報告する	コマンドの失敗後に成功したと主張する
コンパイルまたは調査によって、重要な API に関する主張を検証する	ソースを読んだだけで信頼する
まれにしか使わない処理やコストの高い処理は references/ に分ける	あらゆる処理を 1 つの大きな SKILL.md に詰め込む

過剰に修正しないでください。熟練者の回答がベースラインより短くても、実行可能性が低ければ、やはり評価は下がります。

Step 4: スキルディレクトリを作成する

plugins/<plugin>/skills/<skill-name>/
└── SKILL.md

Step 5: フロントマターを付けて SKILL.md を作成する

ステップ 2 で作成したフロントマターを使ってファイルを作成します。

Step 6: 本文のセクションを追加する

次の推奨セクションを含めます。

1. 目的：成果を説明する 1 段落
2. 使用する場合：適切なシナリオの箇条書き
3. 使用しない場合：適用範囲と対象外
4. 入力：必須入力と任意入力の表
5. ワークフロー：チェックポイントを含む番号付き手順
6. 検証：スキルが正しく機能したことを確認する方法
7. よくある落とし穴：既知の問題と回避方法

Step 7: 必要に応じてオプションのディレクトリを追加する

plugins/<plugin>/skills/<skill-name>/
├── SKILL.md
├── scripts/       # Executable code agents can run
├── references/    # Additional documentation loaded on demand
└── assets/        # Templates, images, data files

同梱ファイルは、references/details.md や scripts/validate.ps1 のように、SKILL.md を含むディレクトリからの相対パスで参照します。エージェントにスキルのインストールディレクトリを検索するよう指示しないでください。同梱ファイルが見つからないことで結果の品質が低下する場合は、既知の同梱ファイルのディレクトリを 1 回だけ一覧表示できるようにし、カバー範囲が縮小したことをエージェントに報告させます。

Step 8: CODEOWNERS を更新する

新しいスキルとそのテストディレクトリのエントリーを .github/CODEOWNERS に追加します。

/plugins/<plugin>/skills/<skill-name>/  @owner-team
/tests/<plugin>/<skill-name>/           @owner-team

同じプラグイン内の関連スキルで使われているオーナーパターンに合わせてください。

Step 9: スキルを検証する

• フロントマターのフィールドが有効であることを確認する
• SKILL.md が 500 行未満であることを確認する
• ファイル参照に相対パスが使われていることを確認する
• 指示が具体的で、実行可能であることを確認する
• dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin> を実行する

Step 10: 評価を追加する

eval.yaml のないスキルには、ベースラインを上回る効果があることを示す根拠がありません。同じプルリクエストで create-skill-test を使って評価を追加し、統計的検出力を確保できる規模にしてください。異なる刺激が 5 件未満の評価では、合格判定が出ることはありません。

例外は、disable-model-invocation: true が設定されたヘルパー／リファレンスカタログです。モデルから呼び出せないため、直接評価では同一の 2 条件を比較することになります。そのリソースを読む利用側スキルの成果評価でカバーしてください。

SKILL.md テンプレート

新しいスキルを作成する際は、このテンプレートを使用します。

---
name: <skill-name>
description: <1-1024 char description of what the skill does and when to use it>
---

# <Skill Title>

<One paragraph describing the skill's purpose and outcome.>

## When to Use

- <Scenario 1>
- <Scenario 2>

## When Not to Use

- <Exclusion 1>
- <Exclusion 2>

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| <input-name> | Yes/No | <description> |

## Workflow

### Step 1: <Action>

<Instructions for this step>

### Step 2: <Action>

<Instructions for this step>

## Validation

- [ ] <Verification step 1>
- [ ] <Verification step 2>

## Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| <Problem> | <How to avoid or fix> |

検証チェックリスト

スキルの作成後、次の項目を確認してください。

• スキル名がディレクトリ名と完全に一致している
• スキル名が小文字とハイフンのみで構成されている
• 説明が空でなく、1024 文字未満である
• 説明に XML のようなタグ（例：Vector<T>）が含まれていない
• SKILL.md の本文が 500 行未満である
• 指示が具体的で、実行可能である
• バンドルファイルのパスが、SKILL.md を含むディレクトリを基準とした相対パスである
• バンドルファイルが見つからない場合に、気付かないまま機能が低下することがない
• ワークフローに、明確なチェックポイントを含む番号付きの手順がある
• 検証セクションがあり、観察可能な成功基準が示されている
• シークレット、トークン、内部 URL が含まれていない
• .github/CODEOWNERS に、新しいスキルとそのテストディレクトリのエントリーがある
• 説明に具体的なトリガーが記載され、最も近い兄弟スキルが対象外として明示されている
• すべてのセクションが、スキルを使わないモデルが誤る判断を変える内容になっている
• スキルに、行動すべきでない場合と、誠実な失敗報告の形式が記載されている
• eval.yaml が存在し、異なる刺激の最低基準を満たしている（そうでない場合、スキルが disable-model-invocation: true に設定され、利用元を通じて評価されている）

よくある落とし穴

落とし穴	解決策
名前に大文字が含まれている	小文字のみを使用します。Code-Review ではなく code-review とします
説明が曖昧である	何をするものか、いつ使うかの両方を記載します
指示が曖昧である	具体的な行動を含む番号付きの手順を使います
検証手順がない	成功を確認できるチェックポイントを追加します
SKILL.md が長すぎる	詳細な内容を references/ ファイルに移します
環境についての前提がハードコードされている	compatibility フィールドに要件を記載します
CODEOWNERS のエントリーがない	兄弟スキルのオーナーパターンに合わせて、/plugins/<plugin>/skills/<skill-name>/ と /tests/<plugin>/<skill-name>/ の両方にエントリーを追加します
スキルがモデルの既知の内容を繰り返している	削除します。スキルは、スキルを使わないモデルとの差分として評価されます
検出可能なパスが必須入力として列挙されている	エージェントにパスを検出するよう指示します。そうしないと、エージェントは停止してユーザーに尋ねます
兄弟スキルとの棲み分けがトピック別になっている	実際の判別基準で棲み分け、双方で対象外の条件を明示します
除外条件がスキル自体のユースケースを妨げている	「次の場合には使用しない」という各条件を、実際のワークフローの各段階に照らして再確認します
eval を追加せずにスキルを追加している	同じ PR で eval.yaml を追加します。評価されていないスキルには根拠がありません

参考資料

• Agent Skills 仕様
• リポジトリの README
• コントリビューションガイドライン
• create-skill-test — スキルの eval.yaml を作成する
• improve-skill-quality — ベースラインに劣るスキルを改善する