skill-creator

スキル作成ガイド

AI エージェントの機能を拡張するスキルの作成ガイドです。Azure SDK と Microsoft Foundry に重点を置いています。

必須コンテキスト： SDK または API のスキルを作成する際、ユーザーはスキルの基盤とする SDK パッケージ名、ドキュメント URL、またはリポジトリへの参照を必ず指定する必要があります。

スキルについて

スキルは、汎用エージェントを専門家へと変えるモジュール式のナレッジパッケージです。

1. 手順に関する知識 — 特定の分野における複数ステップのワークフロー
2. SDK の専門知識 — Azure サービスの API パターン、認証、エラー処理
3. ドメインコンテキスト — スキーマ、ビジネスロジック、企業固有のパターン
4. 同梱リソース — 複雑なタスク向けのスクリプト、リファレンス、テンプレート

---

基本原則

1. 簡潔さが重要です

コンテキストウィンドウは共有リソースです。各項目について、「このトークンコストに見合う価値があるか」を問い直してください。

ドメイン／手順スキルの場合：エージェントはすでに高い能力を備えています。既知の情報は追加せず、まだ知らない情報だけを加えてください。

SDK／API スキルの場合：ユーザーは SDK パッケージ名、ドキュメント URL、またはリポジトリへの参照を必ず指定する必要があります。このコンテキストなしではスキルを作成できません。

2. 最新のドキュメントを最優先する

Azure SDK は常に変更されています。 スキルでは、エージェントにドキュメントの確認を指示してください。

## Before Implementation

Search `microsoft-docs` MCP for current API patterns:

- Query: "[SDK name] [operation] python"
- Verify: Parameters match your installed SDK version

3. 自由度の調整

実装上の制約に合わせて具体性を調整してください。アプローチが多様な場合は自由度を高くし、厳密な実行が必要な場合は低くします。

自由度	使用する場面	例
高	有効なアプローチが複数ある場合	テキストのガイドライン
中	変化を許容する推奨パターン	擬似コード
低	厳密な指定が必要な場合	特定のスクリプト

4. 段階的な開示

スキルは次の 3 つのレベルで読み込まれます。

1. メタデータ（約 100 語）— 常にコンテキストに含まれます
2. SKILL.md の本文（5,000 語未満）— スキルが呼び出されたときに読み込まれます
3. リファレンス（無制限）— 必要に応じて読み込まれます

SKILL.md は 500 行未満にしてください。 この上限に近づいたら、リファレンスファイルに分割してください。

---

スキルの構成

クイックリファレンス：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      — Executable code
    ├── references/   — Documentation loaded as needed
    └── assets/       — Output resources (templates, images)

Azure SDK スキルの場合は、以下のスキルセクションの順序に従ってください。ドメインスキルの場合は、論理的に整理する方法を判断してください。

SKILL.md の必須項目

• フロントマター：name と description（スキルを呼び出す条件を指定する説明）
• 本文：500 行未満にしてください。大きなスキルはリファレンスファイルに分割してください

同梱リソース（任意）

種類	含める場面	例
scripts/	再利用するコードパターン	認証の設定、CLI スクリプト
references/	機能の詳細解説や補足例	capabilities.md のインデックス、non-hero-scenarios.md、API ドキュメント
assets/	出力テンプレート	ボイラープレートコード、画像

---

Azure SDK スキルの作成

Azure SDK のスキルを作成する際は、以下のパターンに一貫して従ってください。

トークン数のガイドライン（必須）

すべての Azure SDK スキルは、以下のトークン数の上限内に収める必要があります。

セクション	目標	絶対上限
インストール + 環境変数	100 トークン	150
認証とライフサイクル	200 トークン	300
コアワークフロー（例 1 つ）	300 トークン	400
機能テーブル	200 トークン	300
ベストプラクティス（6～8 項目）	200 トークン	250
参考資料（reference/ リンク）	100 トークン	150
合計 SKILL.md	約 1100 トークン	約 1500 トークン

適用ルール：

• 上限を超える場合 → /references/ サブディレクトリに分割します
• 500 行に近づいたら → セクション全体を参考資料ファイルに移動します
• スキルの H1 の直後に `` を記載します

---

参考資料への切り出しガイド（必須）

以下の判断基準を使って、SKILL.md に記載する内容と /references/ に移動する内容を決定します。

判断基準	/references/ に移動する内容	SKILL.md に残す内容
使用頻度	一般的な使用の 20% 未満	ワークフローの約 80% 以上
認知負荷	高度なパターン、複数の選択肢	単一の基本的な手順
例の長さ	10 行を超える、複数のパス	1～5 行、単一のパス

コンテンツの切り出しルール：

• バッチ操作 → /references/batch-operations.md
• エラー処理（try-except を超える内容）→ /references/error-handling.md
• パフォーマンス調整 → /references/performance.md
• 代替ワークフロー → /references/workflows-comparison.md
• ストリーミング／イベント → /references/streaming.md
• 高度な認証 → /references/auth-strategies.md
• ツール連携 → /references/tools.md
• 破壊的変更 → /references/migration.md

判断： 一般的なケースは SKILL.md に残し、例外的なケースは /references/ に移動します。

---

コアワークフローの指針（必須）

すべての Azure SDK スキルでは、どのワークフローを記載するかを明確にする必要があります。

ケース 1：明確な「コアワークフロー」が 1 つある場合（大半のサービス）

1 つのパターンでユースケースの約 80％に対応できる場合：

1. そのパターンをコアワークフローに指定します
2. SKILL.md にはこのワークフローのみを記載します（実行可能な完全な例を 1 つ）
3. 代替案は /references/ に記載します：
   • 一括操作 → /references/batch-operations.md
   • エラー処理 → /references/error-handling.md
   • パフォーマンスのチューニング → /references/performance.md
   • 代替ワークフロー → /references/workflows-comparison.md

例：Azure Key Vault Secrets（コアワークフロー：マネージド ID を使用してシークレットを取得する）。代替の認証ワークフローとして、DefaultAzureCredential を使ったローカル開発、ワークロード ID、サービスプリンシパルの認証情報（クライアントシークレットまたは証明書）を /references/ に記載します。

ケース 2：「コアワークフロー」として同等に有効なものが複数ある場合（認証方法やデプロイ先など）

特定のパターンが突出していない場合：

1. 複数のワークフローが同等に有効になるとしても、主要なシナリオをすべて SKILL.md に含めます
2. SKILL.md では、主要なシナリオごとに実行可能な完全な例を 1 つ示します
3. メインファイルが過度に長くならないよう、トレードオフ、その他のバリエーション、詳しい背景情報は /references/workflows-comparison.md に記載します
4. 有効な代替案を、実際の使用における主要な選択肢であるにもかかわらず「高度な機能」として扱わないでください。これらは同等に有効であり、適用される状況が異なるだけです

例：Azure Identity SDK には、主要なシナリオがいくつかあります。ローカル開発向けの主要な認証情報フローと本番環境に安全な認証情報フローを SKILL.md に記載し、AzureCliCredential、ワークロード ID、サービスプリンシパルの各種認証情報、その他の補助的な認証情報の選択肢について詳しく比較する場合は /references/credential-types.md を使用します。

判断基準：迷ったときは、「別の方法を選んだユーザーが、ここに書いた内容を間違いだと思うだろうか」と考えてください。そうであれば、それは別の主要なシナリオであり、SKILL.md に記載します。そうでなければ、概要を説明して /references/ へのリンクを掲載できます。

---

スキルのセクション順

既存の Azure SDK スキルに基づき、次の構成に従ってください。

1. タイトル — # SDK Name
2. インストール — pip install、npm install など
3. 環境変数 — 必須の設定と、その設定が必要となる状況を説明するインラインコメント。DefaultAzureCredential を本番環境で使用する場合は、AZURE_TOKEN_CREDENTIALS（prod または <specific_credential> に設定）を含めます
4. 認証とライフサイクル — Python スキルでは、DefaultAzureCredential の使用を推奨します。ローカル開発ではそのまま使用し、本番環境では AZURE_TOKEN_CREDENTIALS を prod（または特定の対象認証情報名）に設定して制限します。代わりに、ManagedIdentityCredential や WorkloadIdentityCredential などの特定の Microsoft Entra Token 認証情報を直接使用することもできます。Python スキルでは、このセクションを標準のコールアウトブロックで必ず開始します（下記の必須の認証とライフサイクルのコールアウト（Python）を参照）。
5. コアワークフロー — 最小限の実用例（上記のコアワークフローの指針に従う）
6. 機能テーブル — クライアント、メソッド、ツール
7. ベストプラクティス — 番号付きリスト
8. 参考リンク — /references/*.md へのリンクを掲載したテーブル（Azure SDK スキルの場合は、capabilities.md と non-hero-scenarios.md を含めます）

必須の認証とライフサイクルに関する注意喚起 (Python)

対象範囲: Python スキル (-py サフィックス) のみ。その他の言語は独自の慣習に従う場合があります。

すべての Python Azure SDK スキルは、## Authentication & Lifecycle セクションの冒頭に、コードサンプルより前に、以下の注意喚起ブロックを一字一句そのまま記載しなければなりません。これにより、ユーザーがクライアント設定のコードを読んだりコピーしたりする前に、2 つの譲れないルールが可視化されます。

## Authentication & Lifecycle

> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
>    - Local dev: `DefaultAzureCredential` works as-is.
>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
>    - Sync: `with <Client>(...) as client:`
>    - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.

配置ルール:

• ## Authentication & Lifecycle 見出しの直下、最初のコードサンプルの前に挿入します。
• 文言を言い換えたり再構成したりしないでください。スキル間での一貫性が重要です。
• SDK が Entra ID をまったくサポートしていない場合 (稀なケース — たとえば一部のレガシーな Speech REST エンドポイントや、サブスクリプションキーを必要とする websocket API)、ルール #2 (コンテキストマネージャー) は維持し、ルール #1 は「この SDK は API キー認証を必要とし、Entra がまだ利用できない理由」を説明する 1 文に置き換えます。
• SDK が非同期専用の場合 (例: azure-ai-voicelive)、両方のルールを維持しつつ、箇条書きでは非同期形式のみを示します。
• クライアントのライフサイクルを持たない非 Azure の Python スキル (例: pydantic-models-py) では、注意喚起を完全に省略します。

コードサンプルの徹底。 スキル本文内のすべてのクライアント構築は、両方のルールを実演しなければなりません:

• 使用例のすべてのクライアントインスタンス化で with / async with を示します (認証セクションだけではありません)。
• 主要な認証例で DefaultAzureCredential を示します。キーが今も公式にサポートされている SDK では、API キーの例を削除しないでください — 多くの既存ユーザー (特に Entra への移行をまだ完了していない規制環境のユーザー) は、コピーしてそのまま使える動作するサンプルを必要としています。キーを使うスニペットは、同じ ## Authentication & Lifecycle セクション内で主要な DefaultAzureCredential ブロックの_後_に配置した、明確にラベル付けされた ### Legacy: API Key (existing keyed deployments) サブセクションに降格させます。新しいコードでは DefaultAzureCredential を使うべきであり、キーを使う経路は既存のデプロイ向けであることを示す 1 行の注記を含めます。また、<SERVICE>_KEY 環境変数を Environment Variables ブロックに戻し、# Only required for the legacy API-key auth path below というコメントを付けます。
• 一部のサービスには、Legacy サブセクションで言及する価値のあるキー固有の癖があります (例: azure-ai-translation-text では、グローバルエンドポイントに対してキーを使う場合に region= パラメーターが必要です。トークン資格情報による認証にはカスタムサブドメインのエンドポイントが必要なためです)。こうした点は、例を削除するのではなく、降格させたブロックで明示します。
• 非同期の例では、azure.identity.aio の DefaultAzureCredential を、クライアントと並べて async with credential: でラップします。

認証パターン (すべての言語)

ローカル開発では、複数の認証方法をサポートする DefaultAzureCredential を使用します。本番環境では、特定の資格情報の種類を使用するか、環境変数 AZURE_TOKEN_CREDENTIALS を prod に設定して DefaultAzureCredential を構成するか、対象の資格情報を指定します。

Rust スキルを構成する場合は、ローカル開発には DeveloperToolsCredential を、本番環境には ManagedIdentityCredential を使用します。Rust SDK は DefaultAzureCredential をサポートしていないため、各環境で適切な資格情報を明示的に使用してください。

# Python — note: client is wrapped in `with` for deterministic cleanup
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
# Local dev: DefaultAzureCredential works as-is.
credential = DefaultAzureCredential()
# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.
# credential = DefaultAzureCredential(require_envvar=True)
# Or use a specific credential directly in production:
# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
with ServiceClient(endpoint, credential) as client:
    client.do_thing()

// C#
using Azure.Identity;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
var client = new ServiceClient(new Uri(endpoint), credential);

// Java
import com.azure.identity.AzureIdentityEnvVars;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
TokenCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes
// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

// TypeScript
import {
  DefaultAzureCredential,
  ManagedIdentityCredential,
} from "@azure/identity";
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({
  requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"],
});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();
const client = new ServiceClient(endpoint, credential);

// Go
import (
  "context"

  "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
  "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

ctx := context.Background()

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  panic(err)
}

// Or use a specific credential directly in production:
// cred, err := azidentity.NewManagedIdentityCredential(nil)

client, err := azblob.NewClient("https://<account>.blob.core.windows.net/", cred, nil)
if err != nil {
  panic(err)
}

_ = client
_ = ctx

// Rust
use azure_identity::DeveloperToolsCredential;
use azure_storage_blob::BlobServiceClient;

let credential = DeveloperToolsCredential::new(); // Local dev
let client = BlobServiceClient::new(
    "https://<account>.blob.core.windows.net/",
    credential,
    None,
)?;

資格情報を決してハードコードしないでください。環境変数を使用してください。

アンチパターン: やってはいけないこと (必読)

これらのパターンは肥大化と非効率を引き起こします。すべてのスキル作成者は、書く前にこのセクションを確認しなければなりません。

アンチパターン 1: 「網羅的な API リファレンス」

• ❌ しないこと: すべての 50 個の SDK メソッドを機能表に列挙し、あらゆるバリエーションのコードサンプルを付ける
• ✅ すること: 3〜5 個の主要メソッドを表に示し、網羅的な一覧は公式の Azure API リファレンスへリンクする
• トークンコスト: すべてのメソッドと例を列挙すると 400〜600 トークンを浪費します
• ユーザーへの影響: 認知負荷が過大になり、ユーザーは何を使えばよいか分からなくなります

アンチパターン 2：「1 つの問題を解決する方法が複数ある」

• ❌ 避ける：メインの本文で「結果をページ分割する方法として、A、B、C、D のアプローチがあります」と説明する
• ✅ 推奨：「同期ページ分割には ItemPaged を使用します」と説明する（主要な例）。代替案は /references/ にリンクする
• トークンコスト：代替アプローチ 1 つにつき 50～100 トークン。5 つのアプローチを載せると、スキルが非効率になります
• ユーザーへの影響：選択に迷い、ユーザーはすべてを読み直すことになります

アンチパターン 3：「初級者向け・中級者向け・上級者向けの内容を 1 つのスキルにまとめる」

• ❌ 避ける：「クライアントとは何か？」から「カスタムの再試行ポリシー」、さらに「サーキットブレーカーパターン」まで扱うスキル
• ✅ 推奨：主要なワークフローでユースケースの 80％をカバーし、高度なパターンは /references/ に記載する
• トークンコスト：スキルのレベルが 1 つ増えるごとに 200～300 トークン追加されます。3 レベルでは 600～900 トークン増えます
• ユーザーへの影響：エキスパートは退屈し、初心者は圧倒され、誰も必要な情報を得られません

アンチパターン 4：「公式ドキュメントの内容をそのまま言い直す」

• ❌ 避ける：「CosmosClient コンストラクターは、エンドポイント（文字列）と認証情報（TokenCredential）を受け取ります。エンドポイントは Azure Cosmos リソースを識別します……」
• ✅ 推奨：コードを示します：client = CosmosClient(endpoint, credential)。公式ドキュメントへのリンクには microsoft-docs MCP を使用します。
• トークンコスト：冗長な説明はパラメーター 1 つにつき 50～100 トークンかかります。大規模な API では 300 トークン以上が無駄になります
• ユーザーへの影響：内容が重複します。公式ドキュメントが信頼できる情報源であり、スキルでは説明を繰り返すのではなく、使い方を示すべきです

アンチパターン 5：「例で十分なのに、冗長な説明をする」

• ❌ 避ける：「クライアントを作成するには、まずコンストラクターを使用してクラスのインスタンスを作成し、エンドポイントと認証情報のパラメーターを渡します。エンドポイントはリソースを識別する文字列です……」
• ✅ 推奨：すぐにコードを示します：with CosmosClient(endpoint, credential) as client:

効率性の検証（必須 — フェーズ 2）

作成中にスキルの効率性を手動で検証し、そのスキルに tests/scenarios/<skill-name>/vally/ の下に Vally eval がある場合は実行します。

1. トークン数を測定します：

トークンカウンターまたはモデルプレイグラウンドを使って、各セクションを測定します。上記のトークン予算ガイドラインの目標と比較してください。セクションがいずれかの上限を超える場合は、内容を /references/ に移動します。

2. アンチパターンのチェックリストを実行します：

• API リファレンスを網羅していない（メソッドは 50 個ではなく、主要な 3〜5 個を示す）
• SKILL.md に 1 つの問題に対する複数の解決策がない
• 初級・中級・上級の内容が混在していない
• 公式ドキュメントの内容を言い換えていない（まずコードを示し、microsoft-docs にリンクする）
• 冗長な文章がない（まず例を示し、文章は最小限にする）

3. 例の数を確認します：

• SKILL.md に記載した主要なシナリオ／コアワークフローごとに、完全な例が 1 つある。同期と非同期の両方をサポートする Python SDK では、同じワークフローの同期例と非同期例の組み合わせは、2 つではなく 1 つのワークフローとして数えます。
• 機能テーブルには主要なメソッドが 3〜5 個含まれている（API 全体を網羅しない）
• ベストプラクティスの箇条書きごとに例は最大 1 つ

4. フロントマターの検証：

• name が .github/skills/<name>/SKILL.md と一致する
• description にトリガーキーワードが含まれている
• description が簡潔である（約 200 文字が目安。スキーマの上限は 1,024 文字）
• 任意の benchmark_tokens_* および benchmark_quality_* メタデータフィールドを含める場合、それらが metadata の下にフラットな文字列として記述されている

4b. 認証ガイダンスの検証（すべての資格情報で重要）：

• スキルで Azure Identity の資格情報を使う場合、対象言語／パッケージの最新の公式資格情報ドキュメント（利用可能であれば Microsoft Learn、それ以外の場合は上流の SDK リポジトリまたはパッケージドキュメント）に照らしてガイダンスを確認する
• Python スキルの場合、開発時のガイダンスでは DefaultAzureCredential を推奨してもよい（複数の開発用資格情報タイプをサポート）
• Python スキルの場合、本番環境向けのガイダンスでは、DefaultAzureCredential を制約なしで単独使用するのは不十分。チェーンを制約するには、AZURE_TOKEN_CREDENTIALS=prod（または特定の対象資格情報）を必須とするか、特定の資格情報（例：ManagedIdentityCredential）を直接使用する
• Rust スキルの場合、開発／本番環境向けのガイダンスが、実際にサポートされている資格情報を反映している（ローカル開発には DeveloperToolsCredential、本番環境には ManagedIdentityCredential などの特定の資格情報）
• 本番環境での資格情報の選択については、/references/auth-strategies.md または公式ドキュメントにリンクする

4c. Vally の lint／eval を実行します（スキルに tests/scenarios/<skill-name>/vally/ の下に仕様がある場合）：

# If the eval spec uses the shared Rust custom grader plugin, build it first.
(cd tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure && npm install && npm run build)

vally lint --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \
  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure \
  --strict

vally eval --eval-spec tests/scenarios/<skill-name>/vally/eval.yaml \
  --grader-plugin tests/scenarios/_shared/vally/grader-plugins/rust-cargo-build-failure

• vally lint がエラーなしで成功する
• COPILOT_TOKEN が利用可能な場合、vally eval が成功する（エラー重大度の指摘なし）。それ以外の場合は、Vally Evaluation ワークフローの動作に合わせて lint のみでも可
• vally/ 仕様がないスキルはこの手順を省略する — これはスキルごとに任意であり、すべてのスキルに必須ではない

5. 抜き取り確認：

• ユーザーがコアワークフローをコピーして、すぐに実行できるか？
• すべての例がベストプラクティス（コンテキストマネージャー、適切な資格情報など）に従っているか？
• すべての環境変数が説明されているか？

出力： 検証後、測定したトークン数をスキルのヘッダーに注記します：

# Azure Service SDK

---

標準的な動詞パターン

Azure SDK では、すべての言語で一貫した動詞を使用します：

動詞	動作
create	新規作成。すでに存在する場合は失敗
upsert	作成または更新
get	取得。見つからない場合はエラー
list	コレクションを返す
delete	対象が存在しなくても成功
begin	長時間実行される操作を開始

言語固有のパターン

詳細なパターンについては、references/azure-sdk-patterns.md を参照してください。内容は次のとおりです。

• Python：ItemPaged、LROPoller、コンテキストマネージャー、Sphinx docstrings。SDK が同期クライアントと非同期クライアントの両方を提供する場合は、どちらかを優先することなく、両方を同等の選択肢として提示してください。SDK が同期のみ、または非同期のみの場合は、利用可能なモードのみを記載してください。1 つのコード例で同期処理と非同期処理を混在させないでください。必ず with / async with コンテキストマネージャーを示してください。
• .NET：Response<T>、Pageable<T>、Operation<T>、モックのサポート
• Java：Builder パターン、PagedIterable/PagedFlux、Reactor 型
• TypeScript：PagedAsyncIterableIterator、AbortSignal、ブラウザーに関する考慮事項
• Go：第 1 引数としての context.Context、New*Pager() + More()/NextPage(ctx) による runtime.Pager[T]、Begin* + PollUntilDone(ctx, nil) による runtime.Poller[T]、to.Ptr(...) ヘルパー、型付きの *azcore.ResponseError
• Rust：cargo add によるインストール、azure_core の依存関係ルール、Response<T>、Pager<T>、RequestContent::from()、.into_model()、明示的な認証情報の型、Entra ID 認証での RBAC ロール

すべてのスキルにおける必須のベストプラクティス（ユーザー向け）

Python、.NET、Java、TypeScript、Go の各言語

この 2 つのルールは、スキル自体の作成規則にとどまりません。スキルに従うエンドユーザーが自身のコードに適用できるよう、生成されるすべてのスキルの ## Best Practices セクションに、必ず明記してください。

ベストプラクティスのリストの最初の 2 項目として、次の両方を原文どおり追加してください（言語や SDK 固有の内容に合わせた調整のみ可）。例（Python）：

1. **Do not mix sync and async clients in the same call path.** Use either `azure.xxx` sync clients or `azure.xxx.aio` async clients within a single call path — do not combine both.
2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.
3. **Use `DefaultAzureCredential`** for code that runs locally. For code that runs in Azure, either constrain `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS=prod` (or a specific target credential) or use a specific token credential directly (e.g. `ManagedIdentityCredential`, `WorkloadIdentityCredential`).

SDK の構成が異なる場合に適用するバリエーション：

スキルの種類	項目 #1 を次のように調整する	項目 #2 を次のように調整する
非同期専用 SDK（例：voicelive）	"この SDK は非同期専用です。全体を通して .aio 名前空間を使用してください。"	標準のまま
非同期指向のフレームワークガイダンス（例：一部のエージェントフレームワーク）	"必要に応じて、フレームワークで文書化されている非同期パターンを使用してください。ただし、Azure Python SDK では非同期が全般的に推奨されると主張しないでください。"	標準のまま
プロバイダーパターン（OpenTelemetry exporters/distro）	標準のまま	"プロセス終了時に provider.shutdown() / flush() を呼び出してテレメトリをフラッシュしてください。プロバイダーはコンテキストマネージャーではありません。"
REST-over-httpx スキル	標準のまま	"接続をプールし、確実にクローズするため、with httpx.Client(...) as client:（同期）または async with httpx.AsyncClient(...) as client:（非同期）を使用してください。"
Identity スキル	標準のまま	"トークンキャッシュやクリーンアップが必要な HTTP トランスポートを管理する認証情報は、コンテキストマネージャーとして使用してください（with DefaultAzureCredential() as credential:）。非同期の場合は、azure.identity.aio の認証情報に async with を使用してください。"
FastAPI（Azure 以外）	"非同期 I/O を呼び出すかどうかに応じて、エンドポイントごとに def または async def を選択してください。1 つのハンドラー内で同期呼び出しとブロッキング呼び出しを混在させないでください。"	"長期間利用するリソース（DB プール、HTTP クライアント）は lifespan で管理し、Depends を使って注入してください。リクエストごとのリソースには with / async with を使用してください。"
純粋なモデル／スキーマのスキル（I/O なし、例：pydantic）	両方ともスキップ — 該当しません	スキップ
コード例での強制。 スキル内のすべてのコード例は、それ自体が両方のルールに従わなければなりません。これにより、スキルは自身が規定する内容を実演します。

• 1 つの例の中で同期呼び出しと非同期呼び出しを混在させないでください。SDK が同期クライアントと非同期クライアントの両方を提供する場合は、各モードをそれぞれ完全で自己完結した例として示してください — ### Sync サブセクションと ### Async サブセクション — 両方を同等に目立たせます。SDK が同期専用または非同期専用の場合は、利用可能なモードのみを示してください。
• すべての例におけるすべてのクライアントのインスタンス化は、with / async with でラップしなければなりません。唯一許可される例外は、必須の認証スニペット（資格情報 + クライアント構築のパターンを示すもの）と、クライアントがアプリによって所有されるフレームワークのライフスパンパターン（例: FastAPI の lifespan）です。
• 例の中に azure.identity.aio からの非同期資格情報が現れる場合は、クライアントと並べて async with credential: でラップしてください。

Rust 言語

これらのルールは、すべての Rust スキルの ## Best Practices セクションに最初の項目として明示的に記載しなければなりません:

1. 依存関係の管理には cargo add を使用し、Cargo.toml を直接編集しないでください。 マニフェストファイルを手動で変更する代わりに、常に cargo add <crate> または cargo remove <crate> を使用してください。公式クレートは crates.io で公開されており、cargo 経由で追加する必要があります。

2. azure_core の型を直接インポートする場合にのみ、azure_core を Cargo.toml に追加してください。 コードが azure_core::http::Url、azure_core::http::RequestContent、azure_core::error::ErrorKind のような型をインポートする場合は、azure_core を依存関係に明示的に追加してください。サービス クレートによって再エクスポートされた型のみを使用する場合（例: use azure_storage_blob::BlobClient 経由）、azure_core への直接の依存関係は任意です。

3. ローカル開発には DeveloperToolsCredential を、本番環境には ManagedIdentityCredential を使用してください。 Rust SDK は DefaultAzureCredential をサポートしていないため、各環境で適切な資格情報を明示的に使用してください。

4. アップロードデータのラップには RequestContent::from() を使用してください。 データ（例: BLOB）をアップロードする場合は、SDK による適切な処理を確実にするために、コンテンツを RequestContent::from(your_data) でラップしてください。

5. Entra ID 認証に適切な RBAC ロールを割り当ててください。 Entra ID を使用した本番環境の認証では、ID に必要な RBAC ロールが割り当てられていることを確認してください（例: BLOB 書き込みアクセスには「Storage Blob Data Contributor」）。

6. 常に crates.io を使用してパッケージのバージョンを確認してください。 パッケージを使用する前に、crates.io でそのバージョンを確認し、安定したサポート対象のリリースを使用していることを確実にしてください。

7. #[non_exhaustive] のモデル構造体と列挙型を将来に備えさせてください。 Azure Rust SDK のリクエスト/レスポンスモデルは、しばしば #[non_exhaustive] です。Default も派生する外部から構築可能な構造体では、初期化子を ..Default::default() で終わらせてください（現在知られているすべてのフィールドが設定されている場合でも）。必要に応じて、#[allow(clippy::needless_update)] でそのリントをローカルに抑制してください。真に #[non_exhaustive] な構造体（Rust が外部の構造体リテラルを禁止し、E0639 を生成するもの）では、提供されているコンストラクターまたはビルダーを使用するか、まずデフォルト値を構築してから必要なフィールドを変更してください。SDK の列挙型をマッチングする場合は、将来サービスによって追加されるバリアントがマッチを壊さないように、ワイルドカード（_）アームを含めてください。スキルがモデルの構築について記載している場合、そのコード例はこのパターンを実演しなければなりません。完全な例については references/azure-sdk-patterns.md（Model Types）を参照してください。

効果的なスキルの例（ベンチマーク専用の構造準拠スキル）

必須の references/ レイアウト（references/capabilities.md と references/non-hero-scenarios.md）をすでに使用している Azure SDK スキルのみをベンチマークしてください。この構造が導入される前の古いスキルも、スタイルの参考にはなりますが、準拠するように更新するまでは、そのまま模倣しないでください。

有効なベンチマークスキルは、以下の条件を満たす必要があります。

1. 1,500 トークン以下の絶対上限を守る（上記のトークン予算ガイドラインを参照）
2. すべての機能バリエーションではなく、主要なワークフロー（CRUD または主な操作）を網羅する
3. 各概念につき例を1～2個示し、3～5個は示さない
4. API の概要には表を使う（認証情報の種類、RBAC ロール、クライアントの階層）
5. 内容を重複させるのではなく、microsoft-docs MCP を通じて公式ドキュメントにリンクする
6. 高度なパターンは /references/ に移す
7. references/capabilities.md と references/non-hero-scenarios.md を含める

スキルを作成する前に：上記のチェックリストをそのまま適用し、ユースケースに合った構造パターンのみを取り入れてください。

---

非推奨またはブランド変更された SDK の取り扱い

Azure SDK が非推奨になった場合、またはブランド変更された場合は、下位互換性を維持しながら、現在のパッケージをユーザーに案内するようスキルを更新してください。

1. スキルの先頭に移行に関する通知を追加します：

> **⚠️ MIGRATION NOTICE**: The [Old Service Name] has been rebranded to **[New Service Name]**. While the package `old-package-name` remains available for compatibility, **new projects should use `new-package-name`** which provides the latest features and updates.
>
> **For new projects**: Use the `new-package-name` package instead.
>
> **This skill remains valid** for existing projects using `old-package-name`, but be aware you're using the legacy package name. The API patterns shown here are compatible with both packages.

2. 2つのインストール方法を示します：

## Installation

### Legacy Package (Old Name)

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-old-package</artifactId>
<version>4.2.0</version>
</dependency>
\`\`\`

### Recommended Package (New Name)

**For new projects, use the rebranded package:**

\`\`\`xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-new-package</artifactId>
<version>1.0.0</version>
</dependency>
\`\`\`

> **Note**: The API patterns in this skill apply to both packages. Replace package names and imports as needed when using `azure-new-package`.

3. 新しいスキルを作成する場合と、既存のスキルを更新する場合：

• **API に概ね互換性がある場合（クラス名やメソッド名が同じ、または類似している場合）**は既存のスキルを更新します
• API が大きく変更された場合は、新しいスキルと移行ガイドを作成します（references/migration.md を使用）
• 古いスキルと新しいスキルの間には、必ず相互参照を追加します

例：

• azure-ai-formrecognizer-java → azure-ai-documentintelligence（サービスのブランド変更）
• azure-communication-callingserver-java → azure-communication-callautomation（移行ガイド付きで非推奨）

例：Azure SDK スキルの構成

---
name: skill-creator
description: |
  Azure AI Example SDK for Python. Use for [specific service features].
  Triggers: "example service", "create example", "list examples".
---

# Azure AI Example SDK

## Installation

\`\`\`bash
pip install azure-ai-example
\`\`\`

## Environment Variables

\`\`\`bash
AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
\`\`\`

## Authentication & Lifecycle

> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential` for local development.** It works as-is with Azure CLI / VS Code / Developer CLI. For production, either constrain `DefaultAzureCredential` to production-safe credentials or use a specific credential directly. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
>    - Local dev: `DefaultAzureCredential` works as-is.
>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
>    - Sync: `with <Client>(...) as client:`
>    - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.

\`\`\`python
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.ai.example import ExampleClient

# Local dev: DefaultAzureCredential works as-is.
credential = DefaultAzureCredential()

# Production alternative: constrain DefaultAzureCredential with AZURE_TOKEN_CREDENTIALS.
# credential = DefaultAzureCredential(require_envvar=True)

# Or use a specific credential directly in production:

# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes

# credential = ManagedIdentityCredential()

with ExampleClient(
endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],
credential=credential,
) as client:
item = client.get_item("example")
\`\`\`

## Core Workflow

\`\`\`python
with ExampleClient(endpoint=endpoint, credential=credential) as client: # Create
item = client.create_item(name="example", data={...})

    # List (pagination handled automatically)
    for item in client.list_items():
        print(item.name)

    # Long-running operation
    poller = client.begin_process(item.id)
    result = poller.result()

    # Cleanup
    client.delete_item(item.id)

\`\`\`

## Reference Files

| File                                                                 | Contents                                               |
| -------------------------------------------------------------------- | ------------------------------------------------------ |
| [references/capabilities.md](references/capabilities.md)             | Capability index (hero coverage + links to deep-dives) |
| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Concrete non-hero examples                             |
| [references/tools.md](references/tools.md)                           | Tool integrations                                      |
| [references/streaming.md](references/streaming.md)                   | Event streaming patterns                               |

---

スキルの作成プロセス

1. SDK のコンテキストを収集 — ユーザーが SDK/API のリファレンスを提供します（必須）
2. 理解 — 公式ドキュメントを調査して SDK のパターンを把握します
3. 計画 — 再利用可能なリソースと製品分野のカテゴリを特定します
4. 作成 — .github/skills/<skill-name>/ に SKILL.md を作成します
5. 分類 — skills/<language>/<category>/ にシンボリックリンクを作成します
6. テスト — 受け入れ基準とテストシナリオを作成します
7. ドキュメント化 — README.md のスキルカタログを更新します
8. 反復 — 実際の使用状況に基づいて改善します

ステップ 1：SDK のコンテキストを収集（必須）

SDK スキルを作成する前に、ユーザーは必ず以下を提供する必要があります：

必須項目	例	目的
SDK パッケージ	azure-ai-agents、Azure.AI.OpenAI、azblob	正確な SDK を特定します
ドキュメント URL	https://learn.microsoft.com/en-us/azure/ai-services/...	主な情報源
リポジトリ（任意）	Azure/azure-sdk-for-python、Azure/azure-sdk-for-go	コードパターンの確認

提供されていない場合はユーザーに確認します：

To create this skill, I need:
1. The SDK package name (e.g., azure-ai-projects)
2. The Microsoft Learn documentation URL or GitHub repo
3. The target language (py/dotnet/ts/java/go)

まず公式ドキュメントを検索します：

# Use microsoft-docs MCP to get current API patterns
# Query: "[SDK name] [operation] [language]"
# Verify: Parameters match the latest SDK version

ステップ 2：スキルを理解する

具体例を収集します：

• 「このスキルでどの SDK 操作を扱う必要がありますか？」
• 「どのようなトリガーでこのスキルを有効にしますか？」
• 「開発者がよく遭遇するエラーは何ですか？」

タスクの例	再利用可能なリソース
毎回同じ認証コードを使う	SKILL.md のコード例
複雑なストリーミングパターン	references/streaming.md
ツールの構成	references/tools.md
エラー処理のパターン	references/error-handling.md

ステップ 3: 製品領域カテゴリを計画する

スキルは skills/ ディレクトリ内で、シンボリックリンクを介して 言語 と 製品領域 によって整理されます。

製品領域カテゴリ:

カテゴリ	説明	例
foundry	AI Foundry、エージェント、プロジェクト、推論	azure-ai-agents-py、azure-ai-projects-py
data	ストレージ、Cosmos DB、Tables、Data Lake	azure-cosmos-py、azure-storage-blob-py
messaging	Event Hubs、Service Bus、Event Grid	azure-eventhub-py、azure-servicebus-py
monitoring	OpenTelemetry、App Insights、クエリ	azure-monitor-opentelemetry-py
identity	認証、DefaultAzureCredential	azure-identity-py
security	Key Vault、シークレット、キー、証明書	azure-keyvault-py
integration	API Management、App Configuration	azure-appconfiguration-py
compute	Batch、ML コンピューティング	azure-compute-batch-java
container	Container Registry、ACR	azure-containerregistry-py

カテゴリを決定する 基準は次のとおりです:

1. Azure サービスファミリー（Storage → data、Event Hubs → messaging）
2. 主なユースケース（AI エージェント → foundry）
3. 同じサービス領域にある既存のスキル

ステップ 4: スキルを作成する

場所: .github/skills/<skill-name>/SKILL.md

命名規則:

• azure-<service>-<subservice>-<language>
• 例: azure-ai-agents-py、azure-cosmos-java、azure-storage-blob-ts、azure-storage-blob-go
• ドキュメントの本文で Go スキルを扱う場合は、短いパッケージ名（たとえば azblob）を使用します。
• 完全なモジュールインポートパスは、コード/インポートの例（たとえば github.com/Azure/azure-sdk-for-go/sdk/storage/azblob）でのみ使用します。

Azure SDK スキルの場合:

1. microsoft-docs MCP で現在の API パターンを検索する
2. インストールされている SDK バージョンと照合する
3. 上記のセクション順序に従う
4. 例にクリーンアップコードを含める
5. 機能比較表を追加する

バンドルされたリソースを先に書き、その後 SKILL.md を書きます。

確定する前の品質保証:

1. 書きながらセクションのトークン数を測定する（モデルプレイグラウンドのトークンカウンターを使用）
2. トークン予算ガイドラインの目標値と比較する
3. アンチパターンチェックリストに対して検証する（アンチパターンのセクションを参照）
4. セクションが最大トークン数を超える場合は /references/ に抽出する
5. 効率性検証チェックリストを実行する。スキルにスペックがある場合は vally lint/vally eval も含める（効率性検証を参照）
6. 任意で、frontmatter の metadata マッピングの下に benchmark_tokens_* および benchmark_quality_* フィールドを追加する（フラットな文字列値）
7. 今後のメンテナンスのために、スキルのヘッダーにトークン数のコメントを追加する

Frontmatter（ベンチマークメタデータで拡張）:

---
name: azure-service-py
description: |
  Azure Service SDK for Python. Use for [specific features].
  Triggers: "service name", "create resource", "specific operation".
metadata:
  benchmark_tokens_estimated: "1180"
  benchmark_tokens_target: "1100"
  benchmark_tokens_max: "1500"
  benchmark_quality_single_core_workflow: "true"
  benchmark_quality_examples_focused: "true"
  benchmark_quality_no_prose_bloat: "true"
  benchmark_quality_anti_patterns_checked: "true"
---

メタデータフィールド:（Agent Skills の metadata 仕様に従い、すべての値は文字列です — 文字列キーに文字列値がマッピングされます）

• benchmark_tokens_estimated — 実際に測定されたトークン数
• benchmark_tokens_target — 目標効率（通常は 1100）
• benchmark_tokens_max — 絶対的な上限（1500。超える場合は分割）
• benchmark_quality_* — 個々のアンチパターンチェック。それぞれ "true"/"false" の文字列（例: benchmark_quality_single_core_workflow）

ステップ 5: シンボリックリンクで分類する

.github/skills/ にスキルを作成した後、適切なカテゴリにシンボリックリンクを作成します:

# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>

# Example for azure-ai-agents-py in python/foundry:
cd skills/python/foundry
ln -s ../../../.github/skills/azure-ai-agents-py agents

# Example for azure-cosmos-db-py in python/data:
cd skills/python/data
ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

# Example for azure-storage-blob-go in go/data:
cd skills/go/data
ln -s ../../../.github/skills/azure-storage-blob-go blob

シンボリックリンクの命名:

• 短く説明的な名前を使用する（例: agents、cosmos、blob）
• azure- プレフィックスと言語サフィックスを削除する
• カテゴリ内の既存のパターンに合わせる

シンボリックリンクを検証する:

ls -la skills/python/foundry/agents
# Should show: agents -> ../../../.github/skills/azure-ai-agents-py

ステップ 6: テストを作成する

すべてのスキルには、受け入れ基準とテストシナリオが必須です。

6.1 受け入れ基準の作成

場所: tests/scenarios/<skill-name>/acceptance-criteria.md

受け入れ基準は tests/ ツリー内に保管してください（スキルフォルダ内の SKILL.md の隣には絶対に置かないでください）。

ソース資料（優先順）:

1. 公式の Microsoft Learn ドキュメント（microsoft-docs MCP 経由）
2. リポジトリの SDK ソースコード
3. スキル内の既存の参照ファイル

フォーマット:

# Acceptance Criteria: <skill-name>

**SDK**: `package-name`
**Repository**: https://github.com/Azure/azure-sdk-for-<language>
**Purpose**: Skill testing acceptance criteria

---

## 1. Correct Import Patterns

### 1.1 Client Imports

#### ✅ CORRECT: Main Client

\`\`\`python
from azure.ai.mymodule import MyClient
from azure.identity import DefaultAzureCredential
\`\`\`

#### ❌ INCORRECT: Wrong Module Path

\`\`\`python
from azure.ai.mymodule.models import MyClient # Wrong - Client is not in models
\`\`\`

## 2. Authentication Patterns

#### ✅ CORRECT: DefaultAzureCredential + context manager

\`\`\`python
credential = DefaultAzureCredential()
with MyClient(endpoint, credential) as client:
client.do_thing()
\`\`\`

#### ❌ INCORRECT: Hardcoded Credentials

\`\`\`python
client = MyClient(endpoint, api_key="hardcoded") # Security risk
\`\`\`

#### ❌ INCORRECT: Connection string / account key when Entra is supported

\`\`\`python
client = MyClient.from_connection_string(os.environ["CONNECTION_STRING"]) # Bypasses Entra audit/rotation
\`\`\`

#### ❌ INCORRECT: Bare client without context manager

\`\`\`python
client = MyClient(endpoint, credential) # Leaks HTTP transport on exception / interpreter exit
client.do_thing()
\`\`\`

文書化すべき重要なパターン:

• インポートパス（Azure SDK 間で大きく異なります）
• 認証パターン
• クライアントの初期化
• 非同期版（.aio モジュール）
• よくあるアンチパターン

6.2 テストシナリオの作成

場所: tests/scenarios/<skill-name>/scenarios.yaml

config:
  model: gpt-4
  max_tokens: 2000
  temperature: 0.3

scenarios:
  - name: basic_client_creation
    prompt: |
      Create a basic example using the Azure SDK.
      Include proper authentication and client initialization.
    expected_patterns:
      - "DefaultAzureCredential"
      - "MyClient"
      - "with MyClient" # enforce context manager
    forbidden_patterns:
      - "api_key="
      - "hardcoded"
      - "from_connection_string" # prefer Entra over connection strings
    tags:
      - basic
      - authentication
    mock_response: |
      import os
      from azure.identity import DefaultAzureCredential
      from azure.ai.mymodule import MyClient

      credential = DefaultAzureCredential()
      with MyClient(
          endpoint=os.environ["AZURE_ENDPOINT"],
          credential=credential,
      ) as client:
          # ... rest of working example
          pass

シナリオ設計の原則:

• 各シナリオは 1 つの特定のパターンまたは機能をテストします
• expected_patterns — 必ず出現しなければならないパターン
• forbidden_patterns — 出現してはならないよくある間違い
• mock_response — すべてのチェックに合格する、完全で動作するコード
• tags — フィルタリング用（basic、async、streaming、tools）

6.3 テストの実行

cd tests
pnpm install

# Check skill is discovered
pnpm harness --list

# Run in mock mode (fast, deterministic)
pnpm harness <skill-name> --mock --verbose

# Run with Ralph Loop (iterative improvement)
pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85

成功基準:

• すべてのシナリオが合格すること（合格率 100%）
• 偽陽性がないこと（モックレスポンスは常に合格します）
• パターンが実際の間違いを検出できること

ステップ 7: ドキュメントの更新

スキルを作成した後:

1. README.md を更新する — スキルカタログの該当する言語セクションにスキルを追加します

   • スキル総数を更新する（約 73 行目: > N skills in...）
   • Skill Explorer のリンク数を更新する（約 15 行目: Browse all N skills）
   • 言語数テーブルを更新する（約 77〜83 行目）
   • 言語セクションの件数を更新する（例: > N skills • suffix: -py）
   • カテゴリ件数を更新する（例: <summary><strong>Foundry & AI</strong> (N skills)</summary>）
   • カテゴリ内でアルファベット順にスキルの行を追加する
   • テストカバレッジのサマリーを更新する（約 622 行目: **N skills with N test scenarios**）
   • テストカバレッジテーブルを更新する — スキル数、シナリオ数、その言語のトップスキルを更新します

2. GitHub Pages のデータを再生成する — スコープを限定した 1 つのディレクトリ変更から抽出スクリプトを実行し、ドキュメントサイトを再ビルドします

   (cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)
   

   これにより Astro ベースのドキュメントサイトにデータを供給する docs-site/src/data/skills.json が更新され、その後サイトが docs/ に再ビルドされ、GitHub Pages によって配信されます。

3. AGENTS.md を確認する — スキル数が正確であることを確認します

---

ステップ 8: 最新の SDK ソースから既存スキルを再生成する

既存のスキルに古い例、時代遅れの API シグネチャ、または変更されたパッケージガイダンスがある場合に、このワークフローを使用します。

1. まず正規のソースファイルを特定する

Azure SDK の言語スキルでは、公式のアップストリームソースドキュメントと例を信頼できる情報源として使用します:

• Go: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/<service>/<module>/README.md
• Go の例: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/<service>/<module>/
• Rust: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/<service>/<crate>/README.md
• Rust の例: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/<service>/<crate>/examples/
• .NET/Java/Python/TS/Go: 現在の Microsoft Learn パッケージドキュメント + 公式 SDK リポジトリを使用する

2. スキルの内容を外科的に更新する

• コードスニペットを現在のコンストラクタ／メソッドのシグネチャに合わせて更新する
• クレート／パッケージ名を公式の発行元ガイダンスに合わせて維持する
• 意図的に動作を変更しない限り、スキルの構造／フロントマターを保持する
• アップストリームの推奨事項が変更された場合は、「ベストプラクティス」と「参照リンク」を更新する
• Rust の場合、コードが azure_core の型／インポートを直接使用しているなら、Cargo.toml に azure_core が存在することを確認する。サービス向けクレートの再エクスポートのみを使用している場合は、azure_core への直接依存は任意です

API サーフェスの同等性ゲート（再生成するすべてのスキルで必須）

再生成したスキル内のすべてのスニペットについて、言語ごとの権威あるソースを仕様として使用します。

• Python、.NET、Java、TypeScript、Go：最新の Microsoft Learn API リファレンスを仕様として扱います。
• Rust：公式 SDK リポジトリ（https://github.com/Azure/azure-sdk-for-rust）と crates.io のドキュメントを仕様として扱います。Rust パッケージには Learn API リファレンスのページがありません。

再生成したスキルを確定する前に、次のことを行います。

1. スニペットに示されている各 SDK の型／メソッド（クライアント、操作グループ、モデルのコンストラクター、列挙型のメンバー、begin_* のような長時間実行メソッド）を特定します。
2. その言語／パッケージの権威あるソース（上記を参照）と照合して、各シンボルとシグネチャを検証します。
3. 権威あるソースに異なる形式（たとえば、ネストされた properties=... モデル、名前が変更されたメソッド、begin_* の LRO メソッド）が示されている場合は、それに合わせてスニペットを更新します。
4. インポートを再確認し、モデル／クライアントのモジュールが権威あるソースと完全に一致するようにします。
5. 主要なスニペットでは、権威ある例に反する互換性のための簡略化を残さないでください。

シナリオ網羅性ゲート（すべての言語で、再生成するすべてのスキルに必須）

スニペットがコンパイルできるだけでは、再生成は完了していません。スキルで実際の利用シナリオを幅広く示して初めて完了となります。

再生成したスキルを確定する前に、次のことを行います。

1. その SDK の最新の権威あるドキュメント／サンプル（入手できる場合は Microsoft Learn、それ以外の場合はアップストリーム SDK リポジトリとパッケージのドキュメント）から、主要なシナリオを特定します。
2. 各主要シナリオが、コピーしてすぐに使えるスニペット（または、サイズが大きすぎる場合は同梱のリファレンスファイルへの明示的なリンク）とともにスキルに含まれていることを確認します。
3. 主要なフローをハーネスのパターンで検証できるよう、テストシナリオを追加／更新します。
4. SDK がサポートする場合、重要な主要シナリオ以外のシナリオも少なくとも1つ追加します（たとえば、更新／パッチ、削除／クリーンアップ、エクスポート／インポート、高度な認証モード、ページング／フィルタリング、リトライ／エラー処理、LRO の監視）。同期クライアントと非同期クライアントの両方をサポートする Python SDK では、両方を同等の優先度で示します。どちらか一方を常に推奨するものとして扱わないでください。
5. Azure SDK スキルでは、references/ を次のように構成します。
   • references/capabilities.md は簡潔な索引とし、各主要シナリオとその記載場所（SKILL.md または同梱のリファレンス）を記録します。また、主要シナリオ以外の詳細なリファレンスにもリンクします。過去の経緯や移行に関する説明は含めません。
   • references/non-hero-scenarios.md には、メインの SKILL.md には含めない具体的な主要シナリオ以外の例を記載します。
   • 操作グループ、ツール、評価マトリックスなどの専門的な詳細には、追加の references/*.md ファイルを使用します。
6. 広範な操作グループを扱う SDK（管理 SDK でよく見られます）では、操作グループの表を含め、スニペットで扱うグループと、参照のみのグループを明記します。
7. すべての主要な操作グループをスキルで実際に示していない限り、「API サーフェス全体」と謳わないでください。その場合は、スキルが主要なワークフローと選択した二次的なシナリオに最適化されていると記載します。

再生成ワークフローのステップ3：再生成したスキルの動作を検証する

(cd tests && pnpm harness <skill-name> --mock --verbose)

スキルに Vally のシナリオがある場合は、確定前にその評価も実行します（ローカルまたは CI で）。

Rust 再生成ゲート（Rust スキルで必須）：

Rust スキルを再生成する場合は、生成された ## Best Practices セクションの最初の2つのルールが次の内容と完全に一致することを確認します。

1. Use cargo add to manage dependencies, never edit Cargo.toml directly
2. Add azure_core only when importing azure_core types directly

確定前にコンテンツをチェックします。

rg -n "Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly|Add `azure_core` only when importing `azure_core` types directly" .github/plugins/azure-sdk-rust/skills/**/SKILL.md

該当する各 Rust スキルにこの2行が含まれていない限り、再生成は完了していません。

再生成ワークフローのステップ4：更新後にドキュメントの生成物を再生成する

(cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)

再生成ワークフローのステップ 5：変更内容を記録する

PR／コミットのメモに、以下を記載します。

• 使用した上流のドキュメント／サンプル
• 修正したスニペット／シグネチャ
• 実施したテスト／評価とその結果

Python プラグインの一括処理レシピ：azure-sdk-python

「azure-sdk-python 配下のすべての Python スキルを再生成する」という依頼では、これを使用します。

1. まず正確な対象範囲を決めます

# Canonical source of truth for Python plugin skills
ls .github/plugins/azure-sdk-python/skills/*/SKILL.md

• .github/plugins/azure-sdk-python/skills/ を正とします。
• 編集後に .github/skills/<name> のリンクも同期します（以下のシンボリックリンクの確認／修正手順を参照）。

2. 各スキルについて、信頼できる情報源を基に更新します

• 最新の Microsoft Learn API ガイダンスを確認するには、まず必ず microsoft-docs MCP を使用します。
• pip show <package> でインストール済みパッケージのバージョンを確認し、インストール済みパッケージまたは公式 API リファレンスを調べて、スニペットで使用されているすべてのシンボルとシグネチャを検証します。
• Azure SDK スキルでは、パッケージの概要と公式 SDK リポジトリのサンプルを優先します。
• このプラグイン内の Azure 以外の Python スキル（例：fastapi-router-py、pydantic-models-py）では、言語固有のベストプラクティスのバリエーションを維持し、ライフサイクル／認証が該当しない場合は Azure 固有の認証に関する説明を省略します。

3. Python の適用ルールを一貫して適用します

• Azure SDK Python スキルでは、標準のセクション順序を維持します。
• 該当する場合は、## Authentication & Lifecycle が必須の注意喚起ブロック（原文どおり）で始まるようにします。
• すべてのクライアントの例で、ライフサイクルパターンとして with／async with を使用します。
• ## Best Practices が、必須のユーザー向けルール 2 つ（または非同期のみ／プロバイダーパターンのスキルについて文書化されたバリエーション）で始まるようにします。
• 再生成した Azure SDK Python スキルにはそれぞれ、references/capabilities.md（インデックス）と references/non-hero-scenarios.md（具体的な非ヒーロー事例）が含まれていることを確認します。
• 古くなっているか、誤っている場合を除き、既存のリファレンス／アセット／スクリプトを維持します。

4. 再生成したすべての Python スキルを検証します

# Fast frontmatter/structure validation for every Python skill
python .github/skills/skill-creator/scripts/quick_validate.py .github/plugins/azure-sdk-python/skills/<skill-name>

# Run Python skill harness in mock mode (all *-py scenarios)
(cd tests && pwsh ./run-harness-by-language.ps1 -Language py -Mock)

5. スキルリンクとドキュメントの成果物を同期します

# Ensure .github/skills links point at plugin canonical skills
python .github/scripts/sync_skill_links.py --plugin azure-sdk-python --check
python .github/scripts/sync_skill_links.py --plugin azure-sdk-python --apply

# Refresh docs site data after content changes
(cd docs-site && npx tsx scripts/extract-skills.ts && npm run build)

6. 一括再生成の完了基準

• 対象となる .github/plugins/azure-sdk-python/skills/*/SKILL.md がすべて更新されているか、最新であることが明示的に確認されています。
• -py スキルのハーネスモック実行が、リグレッションなしで成功します。
• azure-sdk-python のスキルリンクが同期されています。
• PR メモに、使用した上流ドキュメント、修正したシグネチャ、検証結果が記載されています。

---

段階的開示のパターン

パターン 1：リファレンス付きの概要ガイド

# SDK Name

## Quick Start

[Minimal example]

## Advanced Features

- **Streaming**: See [references/streaming.md](references/streaming.md)
- **Tools**: See [references/tools.md](references/tools.md)

パターン 2：言語別のバリエーション

azure-service-skill/
├── SKILL.md (overview + language selection)
└── references/
    ├── python.md
    ├── dotnet.md
    ├── go.md
    ├── java.md
    └── typescript.md

パターン 3：機能別の構成

azure-ai-agents/
├── SKILL.md (core workflow)
└── references/
    ├── tools.md
    ├── streaming.md
    ├── async-patterns.md
    └── error-handling.md

---

デザインパターンのリファレンス

リファレンス	内容
references/workflows.md	順次ワークフローと条件付きワークフロー
references/output-patterns.md	テンプレートとサンプル
references/azure-sdk-patterns.md	Azure SDK の言語固有のパターン

アンチパターン

やってはいけないこと	理由
SDK のコンテキストなしでスキルを作成する	ユーザーがパッケージ名やドキュメントの URL を提供しなければならなくなる
「いつ使うか」を本文に書く	本文はトリガーされた後に読み込まれる
認証情報をハードコードする	セキュリティリスク
認証セクションを省略する	エージェントが不適切にその場で対処してしまう
古い SDK のパターンを使う	API は変化するため、まずドキュメントを検索する
README.md を含める	エージェントにメタドキュメントは不要
参照を深くネストする	1 階層までに抑える
受け入れ基準を省略する	テストのないスキルは検証できない
シンボリックリンクの分類を省略する	スキルがカテゴリ別に発見できなくなる
誤ったインポートパスを使う	Azure SDK は特定のモジュール構造を持つ
Python スキルのベストプラクティスから同期/非同期およびコンテキストマネージャーの箇条書きを省略する	エンドユーザーは書かれていないルールに従わない。サンプルだけでは不十分
同じ Python の例で同期と非同期を混在させる	そのスキルが防ぐべきアンチパターンを示してしまう
テストシナリオがゼロの状態で再生成されたスキルを提供する	主要なワークフローとリグレッションを検証できない
単一のハッピーパスのサンプルから完全な API カバレッジを主張する	本番環境でユーザーが必要とする操作グループや非主要部分のギャップを隠してしまう
非主要機能に対する references/*.md のカバレッジを省略する	高度な機能をコンテキストの外に追いやり、API の広がりが文書化されないままになる

---

チェックリスト

スキルを完成させる前に：

前提条件：

• ユーザーから SDK パッケージ名またはドキュメント URL が提供されている
• microsoft-docs MCP を使用して SDK のパターンを確認している
• すべてのコードスニペットの API サーフェスを、その SDK の最新の公式言語別 API リファレンスと照合している（利用可能な場合は Microsoft Learn、それ以外の場合は上流の SDK リポジトリ。上記の正式な情報源を参照）

スキルの作成：

• 説明に、内容と使用するタイミング（トリガーフレーズ）の両方が含まれている
• SKILL.md が 500 行未満である
• 認証が言語ごとのルールに従っている（Python／.NET／Java／TS／Go のローカル開発では DefaultAzureCredential、Rust のローカル開発では DeveloperToolsCredential、本番環境では ManagedIdentityCredential）
• 例にクリーンアップ／削除が含まれている
• リファレンスが機能ごとに整理されている（capabilities.md のインデックスと、機能ごとの詳細ファイル）
• 現行の権威あるドキュメント／サンプルにある主要シナリオが、スニペットとテストで明示的に扱われている
• SDK が独自の主要でないシナリオに対応している場合、少なくとも 1 つの価値の高い主要でないシナリオが含まれている（該当しない場合は、独自の主要でないシナリオがないことを明記）
• Azure SDK のスキルでは、references/capabilities.md に主要／主要でないシナリオの対応状況が記載され、主要でないシナリオの専用ドキュメントへのリンクがある
• Azure SDK のスキルでは、references/non-hero-scenarios.md に主要シナリオのスニペットとは異なる、具体的な主要でないシナリオの例が含まれている
• 幅広い SDK（特に管理 SDK）では、操作グループの対応範囲が明示されている（スニペットで対応するか、リファレンスのみか）
• （Python スキルのみ）ベストプラクティスのセクションに、ユーザー向けの 2 つのルールが含まれている（同期／非同期の一貫性、およびクライアントと非同期認証情報でのコンテキストマネージャーの使用。スキルの種類に合ったバリエーションを使用）
• Rust スキルでは、## Best Practices の冒頭に cargo の依存関係ルールと azure_core の直接インポートルールが記載されている

分類：

• .github/skills/<skill-name>/ にスキルが作成されている
• skills/<language>/<category>/<short-name> にシンボリックリンクが作成されている
• シンボリックリンクの参照先が ../../../.github/skills/<skill-name> である

テスト：

• 正しいパターンと誤ったパターンを記載した tests/scenarios/<skill-name>/acceptance-criteria.md が作成されている
• tests/scenarios/<skill-name>/scenarios.yaml が作成されている
• SDK が主要シナリオと主要でないシナリオの両方に対応している場合、少なくとも各 1 つがテストでカバーされている
• すべてのシナリオが成功する（pnpm harness <skill> --mock）
• インポートパスが正確に記載されている

ドキュメント：

• README.md のスキルカタログが更新されている
• 最新の API を確認するため、microsoft-docs MCP を検索するよう案内している