Azure SDK documentation update: Migration waza skills to vally は、Azure SDKのライブラリAPIやアプリケーション実装を変更する更新ではありません。要点は、Azure SDK Toolsリポジトリ内のスキル評価基盤を、非推奨の azd waza 拡張から @microsoft/vally-cli ベースへ移行することです。
そのため、まず確認すべきなのは「自分たちがAzure SDKを使ってアプリを開発しているだけなのか」「Azure SDK関連のスキル、評価、CI/CD、プラグイン配布を管理しているのか」です。前者であれば影響は限定的です。一方で、.github/skills、評価用YAML、GitHub Actions、Azure DevOps Pipeline、Copilot連携の評価ジョブを管理しているチームは、設定ファイル・認証方式・評価実行場所を見直す必要があります。公式PRでは、.waza.yaml から .vally.yaml への置き換え、waza形式のタスク評価からVallyのstimulus/grader形式への変換、GitHub Actionsのlint専用化、Azure DevOpsでの評価実行が整理されています。(GitHub)
Azure SDK documentation update: Migration waza skills to vally の位置づけ
今回の更新は、Azure SDKそのものの利用方法を変えるものではなく、Azure SDK Tools側で使われる「スキル評価」の仕組みを更新するものです。
ここでいうスキル評価とは、Azure SDK関連の作業を支援するエージェントスキルが、期待したタイミングで呼び出され、期待した回答やツール利用を行うかを検証するための仕組みです。たとえば「SDKのリリース準備」「APIViewフィードバック対応」「ローカルでのSDK生成」などのスキルが、適切な入力に反応し、不適切な入力には反応しないことを確認します。
2026年5月20日には、前日のPRで行われた変更をプラグイン側のスキルにも再同期する必要があるとして、関連Issue「Resync Plugin Skills」が開かれています。さらに、プラグイン配下の plugins/azure-sdk-tools/skills/ へスキル内容を同期するPRも作成され、8つの一致するスキルについて SKILL.md と references/ の同期が行われています。(GitHub)
実務上は、次のように整理すると判断しやすくなります。
| 立場 | 影響 | 最初に確認すること |
|---|---|---|
| Azure SDKを利用するアプリ開発者 | 低い | SDKパッケージ、アプリコード、Azureリソース設定に変更が必要か |
| Azure SDK Toolsやスキルを保守する開発者 | 高い | .github/skills 配下の評価ファイル形式、旧waza関連ファイルの残存 |
| CI/CD管理者 | 高い | GitHub ActionsとAzure DevOps Pipelineの役割分担、Node.jsとVally CLIの導入 |
| セキュリティ・管理者 | 中〜高 | Copilot API用のPAT、変数グループ、シークレット管理、監査 |
| プラグイン配布担当 | 中〜高 | .github/skills と plugins/azure-sdk-tools/skills の内容差分 |
何が変わったのか
公式PRの内容を実務目線で分解すると、主な変更点は「設定ファイル」「評価仕様」「CI/CD」「認証」「旧ファイル削除」の5つです。
| 項目 | 旧構成 | 新構成 | 実務上の意味 |
|---|---|---|---|
| プロジェクト設定 | .waza.yaml | .vally.yaml | 評価プロジェクトの入口がVally用設定に変わる |
| 評価仕様 | wazaのtaskベース | Vallyのstimulus/grader形式 | 入力プロンプトと採点ルールを同じ評価仕様に整理する |
| トリガー評価 | trigger_tests.yaml や個別task | trigger.eval.yaml | スキルを呼ぶべき入力・呼ばない入力を明示的に評価する |
| GitHub Actions | 評価実行を含む構成 | vally lint のみ | PRやpush時は構文・参照チェック中心になる |
| 評価実行 | GitHub Actions中心 | Azure DevOps Pipeline | Copilot API認証の都合でADO側に移す |
| 認証 | GitHub Actionsの既定トークン | ユーザースコープPAT | Copilot API向けの認証設計が必要になる |
| 旧成果物 | waza関連YAML、taskディレクトリ | 削除 | 古い評価ファイルに依存した運用は見直しが必要 |
PRでは、.waza.yaml の削除、ルートレベルの eval.yaml、tasks/、trigger_tests.yaml、evals/tasks/ などの旧waza成果物の削除が明記されています。また、8つのスキルファイルで compatibility frontmatterをネストしたYAMLオブジェクトからプレーンな文字列へ平坦化したことも示されています。(GitHub)
.waza.yaml から .vally.yaml へ移行
.vally.yaml は、Vallyで評価対象や実行環境を定義する中心的な設定ファイルです。
Azure SDK Toolsの現在の設定では、評価対象のパスとして skill-authoring/evals/、azsdk-common-pipeline-troubleshooting/evals/、markdown-token-optimizer/evals/、sensei/evals/、azsdk-common-generate-sdk-locally/evals/ などが指定されています。また、評価ファイル名として eval.yaml と *.eval.yaml が扱われる構成になっています。(GitHub)
管理者が確認すべきポイントは、単にファイル名を変えることではありません。実際には、次の3点を合わせて確認する必要があります。
| 確認項目 | 見る場所 | 失敗しやすいポイント |
|---|---|---|
| 評価ファイルの探索パス | .vally.yaml の paths.evals | 実際のディレクトリ名と不一致で評価が検出されない |
| 評価ファイル名 | evalFilenames | trigger.eval.yaml などが対象外になる |
| 実行環境 | environments | eval側の environment 名と一致せず実行できない |
特にMCPサーバーを起動する設定では、dotnet の実行パスや --project の相対パスが重要です。ローカルでは動くのにCIで失敗する場合、カレントディレクトリが想定と違うケースがよくあります。
評価仕様はtaskベースからstimulus/grader形式へ
waza形式では、個別のtaskファイルやtaskディレクトリに評価内容が分散しやすい構成でした。Vally形式では、評価入力を stimuli、採点条件を graders としてまとめる構成に変わっています。
この変更により、1つの評価仕様の中で「どの入力を与えるか」「何を期待するか」「どのスキルが呼ばれるべきか」を読み取りやすくなります。たとえば、スキル作成に関するプロンプトでは skill-authoring が呼ばれるべきです。一方、Azure AD認証のような一般的な開発質問では、SKILL.md 作成支援のスキルが不用意に呼ばれないことも評価できます。
Vallyの評価仕様では、次のような観点を明確に分けて考えると移行しやすくなります。
| 観点 | 例 | 目的 |
|---|---|---|
| stimulus | 「SDKをローカルで生成したい」などの入力 | ユーザーが実際に投げる依頼を再現する |
| grader | 期待する文字列、禁止する文字列、スキル呼び出し条件 | 出力や挙動が期待通りか判定する |
| trigger | そのスキルが呼ばれるべき入力 | 必要な場面でスキルが起動するか確認する |
| anti-trigger | そのスキルが呼ばれるべきでない入力 | 誤作動や過剰なスキル起動を防ぐ |
| tag | area、type=ci-gate、priority など | CIで評価範囲を絞り込む |
公式PRでは、すべてのeval specsをwazaのtaskベース形式からVallyのstimulus/grader形式へ変換し、各スキルに対して trigger.eval.yaml を追加したことが説明されています。(GitHub)
GitHub Actionsはlint中心、評価実行はAzure DevOpsへ
今回の更新で特に注意したいのが、CI/CDの役割分担です。
GitHub Actions側の .github/workflows/skill-eval.yml は、.github/skills/** の変更を契機に動作し、Node.js 22をセットアップしたうえで @microsoft/[email protected] をインストールし、vally lint . を実行する構成になっています。つまり、GitHub Actionsは主に「評価仕様やスキル定義が壊れていないか」を確認するlint用途です。(GitHub)
一方、実際の評価実行は eng/pipelines/skill-eval.yml として追加されたAzure DevOps Pipeline側に移されています。このPipelineでは、Node.js 22、@microsoft/[email protected]、@github/copilot-sdk をインストールし、変更されたスキル領域を検出したうえで vally eval --tag "type=ci-gate" を実行し、結果をPipeline Artifactとしてアップロードします。(GitHub)
なぜAzure DevOpsで評価を実行するのか
理由は認証です。
公式PRでは、Vallyの copilot-sdk executorが @github/copilot-sdk を使い、GitHub CLI経由で認証すること、GitHub Actionsの既定 GITHUB_TOKEN はGitHub Appのserver-to-serverトークンであり、Copilot APIでは受け付けられないことが説明されています。そのため、Azure DevOps Pipelineでは AzSDK_Eval_Variable_group からユーザースコープPATを参照する構成になっています。(GitHub)
この点は、管理者にとって最も重要な確認ポイントです。単に「GitHub Actionsで同じコマンドを実行すればよい」と考えると、Copilot API認証で失敗する可能性があります。
| 管理項目 | 推奨される確認 |
|---|---|
| PATの保管場所 | Azure DevOpsの変数グループやシークレット管理に格納する |
| PATの権限 | 評価に必要な最小権限に絞る |
| PATの期限 | 無期限にせず、更新手順を決める |
| ログ出力 | トークン値や認証ヘッダーが出力されないようにする |
| 利用主体 | 個人PATに依存しすぎず、組織の運用ルールに合わせる |
| 監査 | いつ、誰が、どのPipelineで使ったか追跡できるようにする |
開発者が確認すべき移行手順
自分たちのリポジトリやフォークで同様の構成を使っている場合は、次の順序で移行すると失敗を減らせます。
| 手順 | 作業 | 確認ポイント |
| -: | ————————- | —————————————————————— |
| 1 | 旧waza構成を棚卸しする | .waza.yaml、tasks/、trigger_tests.yaml、evals/tasks/ が残っていないか |
| 2 | .vally.yaml を作成・確認する | evalパス、結果出力先、環境名、MCPサーバー設定が正しいか |
| 3 | eval specをVally形式へ変換する | stimuli と graders に分け、期待値を明確にする |
| 4 | trigger.eval.yaml を追加する | triggerとanti-triggerを両方入れる |
| 5 | tagを整理する | area、type=ci-gate、必要に応じて priority を付ける |
| 6 | GitHub Actionsをlint用に調整する | vally lint . が安定して通るか |
| 7 | 評価実行Pipelineを用意する | Copilot API用PAT、変数グループ、Artifact出力を確認する |
| 8 | plugin側のコピーを同期する | plugins/azure-sdk-tools/skills/ など二重管理がないか |
| 9 | 旧ファイルを削除する | 新形式で評価が検出・実行できることを確認してから削除する |
| 10 | 運用ルールに反映する | レビュー観点、CI失敗時の対応、PAT更新手順を文書化する |
ローカルで最低限確認するなら、次のような流れが分かりやすいです。
cd .github/skills
npm install -g @microsoft/[email protected]
vally lint .評価まで実行する場合は、対象areaを絞ると調査しやすくなります。
cd .github/skills
vally eval --tag "type=ci-gate" --tag "area=skill-authoring" --output-dir ".vally/results"ただし、Copilot SDKを使う評価では認証要件があります。ローカルや独自CIで実行する場合も、GitHub Actionsの既定トークンで代替できるとは限りません。
移行時に起きやすいトラブルと対策
evalファイルが検出されない
最も多いのは、.vally.yaml の paths.evals と実際のディレクトリ構成が一致していないケースです。
たとえば、評価ファイルを skills/foo/evals/ に置いたつもりでも、.vally.yaml 側が foo/evals/ を見に行っていなければ、lintやevalの対象になりません。ファイル名も重要です。evalFilenames に *.eval.yaml が含まれていない環境では、trigger.eval.yaml が対象外になる可能性があります。
対策は、移行直後に「評価が通るか」だけでなく「評価件数が想定通りか」を確認することです。0件のまま成功しているように見えるCIは、実際には何も検証していない可能性があります。
areaタグで期待したスキルだけ実行されない
Azure DevOps Pipelineでは、変更された .github/skills/ 配下のディレクトリ名からareaを検出し、--tag area=... を付けて評価を絞り込む構成になっています。(GitHub)
そのため、eval spec側の tags.area とディレクトリ名の対応がずれていると、変更したスキルの評価が実行されません。
例として、ディレクトリが azsdk-common-sdk-release なのに、eval specのareaが別名になっている場合、差分検出とタグフィルタの整合性が崩れます。移行時は、ディレクトリ名・skill名・areaタグの対応表を一度作ると安全です。
triggerだけを確認してanti-triggerを忘れる
スキル評価では「呼ばれるべきときに呼ばれる」だけでなく、「呼ばれるべきでないときに呼ばれない」ことも重要です。
たとえば、SDKリリース支援スキルが、単なるAzure認証の質問や一般的なパイプライン相談で起動すると、ユーザー体験が悪化します。Vally移行では trigger.eval.yaml を追加して、triggerとanti-triggerの両方を検証する流れが示されています。(GitHub)
移行レビューでは、次のように確認すると抜け漏れを防げます。
| 評価タイプ | 確認すること | 具体例 |
|---|---|---|
| trigger | そのスキルが必要な入力で呼ばれるか | 「SDKをローカル生成したい」で生成支援スキルが起動する |
| anti-trigger | 無関係な入力で呼ばれないか | 「Azure ADで認証したい」でSKILL.md作成スキルが起動しない |
| output | 回答に必要な情報が含まれるか | frontmatter、検証手順、参照ファイルなど |
| not-output | 不要な情報を出していないか | 無関係なSKILL.md説明を混ぜない |
| tool invocation | 必要なスキル・ツールを使うか | 指定されたMCPツールやスキルが呼ばれる |
GitHub Actionsでevalを動かそうとして認証に失敗する
今回の更新では、GitHub Actionsはlint、Azure DevOpsはevalという分担が取られています。
GitHub Actionsの既定 GITHUB_TOKEN は便利ですが、Copilot APIで必要な認証としてそのまま使えるとは限りません。公式PRでも、GitHub App tokenはCopilot APIでサポートされないため、Azure DevOps側でユーザースコープPATを使う理由が説明されています。(GitHub)
独自環境で同じ評価を実行する場合は、次の判断基準を使うとよいでしょう。
| 実行場所 | 向いている用途 | 注意点 |
|---|---|---|
| GitHub Actions | lint、構文チェック、参照チェック | Copilot APIが必要なevalには不向きな場合がある |
| Azure DevOps Pipeline | Copilot SDKを使う評価実行 | PAT管理、変数グループ、監査が必要 |
| ローカル | 評価仕様の試作、デバッグ | 認証状態やカレントディレクトリ差分に注意 |
| 独自CI | 組織ルールに合わせた統合 | トークン種別とログ管理を事前確認する |
古いwaza関連文字列を機械的に全削除してしまう
.waza.yaml や旧taskディレクトリの削除は必要ですが、リポジトリ内のすべての waza 文字列を機械的に削除するのは危険です。
スキル説明や移行メモ、過去互換の案内、検証手順に waza という語が残っている場合、それが削除対象なのか、説明として必要なのかを文脈で判断する必要があります。移行作業では、次のように分類してから対応するのが実務的です。
| 検出対象 | 対応 |
|---|---|
.waza.yaml | 原則削除し、.vally.yaml に移行 |
trigger_tests.yaml | trigger.eval.yaml へ移行 |
tasks/*.yaml | stimuli / graders へ統合 |
evals/tasks/ | 新形式へ変換後に削除 |
ドキュメント中の waza | 説明、移行履歴、古い手順のどれかを確認して判断 |
| CI内のwazaコマンド | Vally CLIへ置き換え |
管理者が見るべき設定チェックリスト
今回の変更は、YAMLファイルの置き換えだけでなく、CI/CD、認証、成果物保存まで含む運用変更です。管理者は次の観点で確認してください。
| チェック項目 | 確認内容 |
|---|---|
| Node.jsバージョン | GitHub ActionsとAzure DevOpsでNode.js 22系を使う構成になっているか |
| Vally CLIバージョン | @microsoft/[email protected] のようにバージョンを固定しているか |
| lint実行場所 | GitHub Actionsで vally lint . が実行されるか |
| eval実行場所 | Azure DevOps Pipelineで vally eval が実行されるか |
| Copilot SDK | 評価実行環境に @github/copilot-sdk が入るか |
| PAT | GITHUB_TOKEN ではなく、評価に必要なユーザースコープPATを安全に参照しているか |
| 変数グループ | AzSDK_Eval_Variable_group 相当の管理単位でシークレットを扱っているか |
| 成果物 | eval結果がPipeline Artifactとして保存されるか |
| skip条件 | 変更スキルが検出されない場合に意図通りskipされるか |
| 手動実行 | runAll や areas パラメータで必要な範囲を実行できるか |
特に注意したいのは、Pipeline上で continueOnError: true が使われている点です。評価結果をArtifactとして残す目的では有効ですが、評価失敗をリリースブロックにするかどうかは別途設計が必要です。評価が失敗してもPipeline全体が止まらない構成にするなら、結果を誰が確認し、どの基準で修正必須にするのかを運用ルールに落とし込んでください。(GitHub)
プラグイン側を管理している場合の注意点
2026年5月20日の関連Issueでは、PR #15376の変更がプラグイン作成前の変更であり、スキルを再同期して一致させる必要があると説明されています。続く同期PRでは、.github/skills から plugins/azure-sdk-tools/skills/ へ、8つの一致するスキルの SKILL.md と references/ がコピーされています。ただし、azure-typespec-author は大きな差分があるためスキップされたと説明されています。(GitHub)
これは、プラグイン側にスキルのコピーを持つ構成では重要です。.github/skills だけを更新しても、配布されるプラグイン側のスキルが古いままなら、利用者が見る説明やエージェントの挙動が一致しません。
確認すべき観点は次の通りです。
| 対象 | 確認ポイント |
|---|---|
SKILL.md | frontmatter、description、compatibilityの形式が一致しているか |
references/ | 参照ファイルの追加・削除・パス変更が反映されているか |
| skill名 | .github/skills 側とplugin側で名前がずれていないか |
| MCP tool名 | azure-sdk-mcp: のような修飾付き識別子に統一されているか |
| 除外スキル | 同期対象外にした理由が明確か |
| レビュー | 自動同期だけでなく、人の目で差分を確認しているか |
プラグインを配布しているチームでは、移行作業の最後に「ソース側のスキル」と「配布側のスキル」の差分を確認する工程を入れるべきです。同期漏れは、CIでは検出できても利用者環境では原因が見えにくいためです。
Azure SDK利用者への影響は限定的
この更新は、Azure SDKを使ってアプリケーションを開発している一般の開発者には、基本的に直接影響しません。
次のような作業は、今回の更新を理由に変更する必要はありません。
| 項目 | 変更要否 |
|---|---|
| Azure SDKパッケージのバージョン | この更新だけを理由に変更不要 |
| アプリケーションコード | 変更不要 |
| Azure Portalのリソース設定 | 変更不要 |
| 認証情報や接続文字列 | 変更不要 |
| SDKのビルド・テスト手順 | 通常のアプリ開発では変更不要 |
一方で、Azure SDKの生成、APIView対応、リリース準備、パイプライントラブルシューティングなどを支援する内部ツールやエージェントスキルを使っている場合は、スキルの起動条件や評価結果の扱いが変わる可能性があります。
つまり、影響範囲は「SDK利用」ではなく「Azure SDK Toolsのスキル評価・運用」にあります。
移行後のレビューで見るべきポイント
Vally移行後のレビューでは、単にlintが通ったかではなく、評価品質が落ちていないかを確認する必要があります。
評価の読みやすさ
旧taskをそのまま機械的に stimuli へ詰め替えるだけでは、評価の意図が分かりにくくなります。
良いeval specは、次の3つが読み取れます。
| 観点 | 良い状態 |
|---|---|
| 何を入力するか | 実際のユーザー依頼に近いpromptになっている |
| 何を期待するか | graderで期待値や禁止事項が明確になっている |
| どの範囲を評価するか | area、type、priorityなどのtagで絞り込める |
誤起動を防ぐanti-trigger
AIエージェントのスキルは、呼ばれないべき場面で呼ばれると使いにくくなります。
たとえば、パイプライン障害の相談にSDKリリーススキルが反応したり、一般的なAzure認証の質問にSKILL.md作成スキルが反応したりすると、回答が遠回りになります。trigger evalには、肯定例だけでなく否定例も必ず入れてください。
タグ設計
area タグは、評価範囲の絞り込みに使われます。CIで変更スキルだけを評価する運用では、タグ設計が壊れると必要な評価が実行されません。
おすすめは、次のようなルールを決めておくことです。
| タグ | 用途 |
|---|---|
area | スキルまたは機能領域を表す |
type=ci-gate | CIで実行する評価を示す |
priority=p0 など | 重要度で絞り込む |
manual など | 手動検証用の重い評価を分ける |
公式PRでは、CIで --tag "priority=p0" や --tag "area=" による評価検出・フィルタリングを確認したことが記載されています。(GitHub)
よくある疑問
Azure SDKのAPI仕様が変わったのですか？
いいえ。今回の更新は、Azure SDK Toolsリポジトリのスキル評価基盤に関する変更です。Azure SDKのクライアントライブラリAPIや、利用者のアプリケーションコードが直接変わる更新ではありません。
wazaを使っていなければ対応不要ですか？
通常のAzure SDK利用だけであれば、対応はほぼ不要です。
ただし、リポジトリ内に .github/skills、.waza.yaml、waza形式のtask、GitHub Actions上のスキル評価ジョブがある場合は確認が必要です。特にフォークや社内ミラーでAzure SDK Tools由来のスキル評価を使っている場合は、旧ファイルが残っていないか確認してください。
GitHub Actionsだけで完結できますか？
lintだけならGitHub Actionsで完結できます。実際に公式のGitHub Actions構成では、vally lint . が実行されています。(GitHub)
一方、Copilot SDKを使うeval実行では、GitHub Actionsの既定 GITHUB_TOKEN ではなくユーザースコープPATが必要になるため、公式構成ではAzure DevOps Pipeline側に分離されています。(GitHub)
いつ移行すべきですか？
公式PRでは、旧 azd waza 拡張がdeprecatedであることを前提にVallyへ移行しています。自分たちの環境でwaza形式の評価を使っている場合は、次の変更タイミングを待たずに棚卸しを始めるべきです。
ただし、いきなり旧ファイルを削除するのではなく、Vally形式でlintとevalが通ること、評価件数が想定通りであること、CI/CDと認証が安定していることを確認してから削除してください。
まず取るべきアクション
Azure SDK documentation update: Migration waza skills to vally を受けて最初にやるべきことは、影響範囲の切り分けです。
Azure SDKを利用するだけのチームであれば、SDK更新やアプリ改修を急ぐ必要はありません。Azure SDK Tools、スキル評価、Copilot連携、プラグイン配布を管理しているチームは、次の順に対応してください。
.github/skills配下に旧waza構成が残っていないか確認する.vally.yamlのevalパス、環境、ファイル名、結果出力先を確認する- eval specをstimulus/grader形式に変換し、trigger/anti-triggerを追加する
- GitHub Actionsはlint中心、Azure DevOpsはeval実行という役割分担を確認する
- Copilot API用PATを安全に管理し、Pipeline Artifactで結果を追跡できるようにする
- plugin側のスキルコピーがある場合は、
.github/skillsとの同期漏れを確認する
今回の移行は、単なるファイル名変更ではありません。評価仕様、CI/CD、認証、配布先の同期まで含めて見直すことで、Vally移行後もAzure SDK関連スキルの品質を安定して保てます。
コメント