Azure AI Foundryでエージェントを運用しているチームにとって、今回の「Use skills with Microsoft Foundry agents」のポイントは、エージェントごとに埋め込んでいた指示・運用ルール・チェックリストを、SKILL.mdとして共通部品化し、バージョン管理しながら配布できるようになることです。
これにより、サポート対応ポリシー、コードレビュー基準、営業トークの禁止事項、社内ナレッジの使い方などを、複数のAIエージェントやCopilot系ワークフローで再利用しやすくなります。
一方で、この機能はプレビュー扱いです。Microsoft Learnでは、プレビュー機能はSLAなしで提供され、本番ワークロードでの利用は推奨されない旨が明記されています。導入を急ぐ場合でも、いきなり本番反映するのではなく、検証用プロジェクトでSKILL.mdの設計、Skills REST API、Toolbox連携、Hosted agentへの注入方式を確認してから段階展開するのが安全です。(Microsoft Learn)
Azure AI FoundryのSkills更新で何が変わるのか
今回の更新で重要なのは、Azure AI Foundry、現在のMicrosoft Foundryにおけるエージェント開発が「プロンプトを個別に書き換える運用」から「スキルを部品として管理する運用」に近づく点です。Microsoft Learnでは、MicrosoftのAIプラットフォーム名称がAzure AI Studio、Azure AI Foundryを経てMicrosoft Foundryへ進化していることも説明されています。記事内では、検索されやすい呼び方としてAzure AI Foundryも併記します。(Microsoft Learn)
従来、複数のエージェントに同じ行動ルールを適用する場合、各エージェントのsystem promptやアプリケーションコードに同じ内容をコピーするケースがありました。たとえば、問い合わせ対応エージェントに「返金判断は必ず管理者へエスカレーションする」、コードレビューエージェントに「SQLインジェクション、認証、例外処理を必ず確認する」といった指示をそれぞれ埋め込む形です。
Skillsでは、このような行動指針をSKILL.mdとして切り出し、Foundry内でバージョン管理します。Microsoft Learnでは、Skillは一度作成して中央管理し、Skills APIを通じて保存し、Toolboxにアタッチするか、Hosted agentやローカルのagent projectへダウンロードして利用する流れが説明されています。(Microsoft Learn)
変更点の要約
| 観点 | これまで起きやすかった課題 | Skillsで変わること |
|---|---|---|
| 指示の再利用 | 複数エージェントに同じルールをコピーしがち | SKILL.mdとして共通化できる |
| 変更管理 | ルール変更時に各エージェントを個別修正 | Skillの新バージョンを作成し、default_versionを切り替える |
| ロールバック | 修正前のプロンプトに戻しにくい | 既存バージョンへ戻しやすい |
| 配布方法 | 実装ごとに指示の読み込み方式がばらつく | Toolbox経由、またはHosted agentへの直接注入を選べる |
| ガバナンス | 誰がどのルールを使っているか見えにくい | Foundryプロジェクト単位でSkillと参照先を管理しやすい |
Skillsは「エージェントの振る舞い」を管理するための部品
Skillsは、外部APIを呼び出す「ツール」とは役割が異なります。Toolが「何を実行できるか」を増やす仕組みだとすると、Skillは「どのように判断・応答すべきか」を補強する仕組みです。
たとえば、以下のような用途に向いています。
| 活用シーン | Skillに書く内容の例 |
|---|---|
| カスタマーサポート | 返金、謝罪、エスカレーション、個人情報の扱い |
| コードレビュー | セキュリティ、可読性、テスト観点、禁止ライブラリ |
| 社内ヘルプデスク | 回答できる範囲、参照すべき社内ドキュメント、曖昧な質問への確認手順 |
| 営業支援 | 訴求表現、競合比較時の禁止事項、誇張表現の回避 |
| 法務・コンプライアンス補助 | 断定を避ける条件、専門部署へ回す基準、記録すべき項目 |
実務では、Skillを「長いプロンプトの置き場」として使うだけでは効果が出にくくなります。おすすめは、1つのSkillに1つの目的を持たせることです。
たとえば、support-escalation、security-review-checklist、brand-tone-guideのように分けると、変更範囲が明確になり、テストもしやすくなります。
SKILL.mdの基本構造と作成ルール
SkillはMarkdownファイルで作成します。先頭にYAML front matterを置き、nameとdescriptionを定義します。Microsoft Learnでは、nameとdescriptionは必須で、本文はエージェントへ注入される追加指示になると説明されています。nameは小文字、数字、ハイフンのみで、先頭・末尾のハイフンや連続ハイフンは不可、最大64文字という制約があります。(Microsoft Learn)
---
name: support-escalation
description: Guide support agents to identify cases that require human escalation.
---
## Purpose
Use this skill when a user asks about refunds, account suspension, billing disputes, legal requests, or safety-related complaints.
## Instructions
- Do not promise refunds unless the policy clearly allows it.
- Ask for the minimum information needed to identify the case.
- Escalate to a human operator when the request involves legal claims, personal data deletion, or repeated billing failures.
- Keep the response concise and avoid blaming the user.注意したいのは、nameとdescriptionを引用符で囲まない点です。公式ドキュメントでは、この2つをYAML front matter内でunquotedにする必要があるとされています。名前の形式が不正な場合は、Skill version作成時にinvalid_payloadエラーになります。(Microsoft Learn)
SKILL.md設計で失敗しやすいポイント
| 失敗例 | 問題 | 改善策 |
|---|---|---|
| 1つのSkillに全社ルールを全部詰め込む | 変更影響が大きく、テストしづらい | 業務・目的ごとにSkillを分ける |
descriptionが曖昧 | エージェントや利用者が用途を判断しにくい | 「いつ使うか」が分かる一文にする |
| 禁止事項だけを書く | 代替行動が分からず、回答品質が落ちる | 「禁止」と「代わりに行うこと」をセットで書く |
| バージョン番号をGitだけで管理する | Foundry上のdefault_versionとずれる | Gitのタグ、PR、FoundryのSkill versionを対応付ける |
| 本番Skillを直接編集する運用にする | 影響確認前に全エージェントへ反映される可能性がある | 新バージョン作成、検証、昇格の流れにする |
Skills REST APIでバージョン管理できること
Skills APIでは、Skillを作成・取得・一覧表示・削除し、Skill versionも管理できます。公式ドキュメントでは、Skill作成時に親となるSkillが存在しなければ自動作成され、各更新はimmutableなSkillVersionとして作られると説明されています。また、親のSkillオブジェクトは有効なバージョンを示すdefault_versionと、最新バージョンを示すlatest_versionを持ちます。(Microsoft Learn)
REST APIを使う場合の基本は以下です。
| 項目 | 内容 |
|---|---|
| エンドポイント | {FOUNDRY_PROJECT_ENDPOINT}/skills |
| 認証 | DefaultAzureCredentialなどで取得したBearer token |
| スコープ | https://ai.azure.com/.default |
| 必須プレビューheader | Foundry-Features: Skills=V1Preview |
| API version | 例としてapi-version=v1を使用 |
Skills APIの呼び出しでは、プレビューheaderの付け忘れが実装時の典型的なつまずきになります。SDK、RESTクライアント、CI/CDスクリプトのどこから呼び出す場合でも、headerを共通処理として入れる設計にしておくと、環境差分による失敗を減らせます。
Skill versionの作成方法は2種類
Skill versionは、主に2つの方法で作成できます。公式ドキュメントでは、JSONでinline_contentを渡す方法と、SKILL.mdを含むZIPファイルをアップロードする方法が示されています。(Microsoft Learn)
| 方法 | 向いているケース | 注意点 |
|---|---|---|
| JSON inline content | 短い指示をAPIから直接登録したい場合 | Git上のSKILL.mdと乖離しないよう管理が必要 |
| ZIPアップロード | SKILL.mdと関連ファイルをまとめて管理したい場合 | パッケージ構成と検証ルールをCIで確認したい |
実務では、SKILL.mdをGitリポジトリで管理し、Pull RequestでレビューしてからZIP化・登録する運用が扱いやすいです。Skillはエージェントの振る舞いを変えるため、コードと同じようにレビュー、承認、履歴管理の対象にするべきです。
Toolboxにアタッチする方法とHosted agentへ直接入れる方法の違い
Skillsの配布方法は、大きく2つあります。
1つ目は、SkillをToolboxにアタッチし、MCP endpoint経由でエージェントやMCPクライアントに発見させる方法です。2つ目は、Skill contentをダウンロードし、Hosted agentやローカルのagent projectに配置して、セッション開始時に追加指示として読み込ませる方法です。公式ドキュメントでは、ToolboxにアタッチしたSkillsはMCP Resourcesとして公開され、Hosted agentではSKILL.mdをプロジェクト内に配置して直接注入する流れが説明されています。(Microsoft Learn)
| 比較項目 | Toolbox経由 | Hosted agentへの直接注入 |
|---|---|---|
| 主な用途 | 複数のMCP対応クライアントやエージェントで共有したい | 特定のagent projectにSkillを同梱したい |
| 配布単位 | Toolbox version | agent project内のskills/ディレクトリ |
| 発見方法 | MCP Resourcesのresources/list、resources/read | 起動時にローカルのSKILL.mdを読み込み |
| バージョン管理 | Skill versionとToolbox versionの両方を意識する | ダウンロードしたSkill versionをコード側で固定しやすい |
| 適した組織 | 複数チームで共通基盤を使う組織 | アプリごとに厳密に挙動を固定したいチーム |
Toolbox経由を選ぶべきケース
Toolbox経由は、複数のエージェントやクライアントから同じSkillを参照したい場合に向いています。たとえば、GitHub Copilot、Claude Code、自社のagent harnessなど、MCP Resourcesに対応したクライアントから共通のSkillを読み込ませたい場合です。
ただし、SkillをToolboxにアタッチする場合、Skillは同じFoundryプロジェクト内に存在する必要があります。公式ドキュメントでは、クロスプロジェクト参照はサポートされないと明記されています。プロジェクトを部門別に分けている組織では、Skillの配置先とToolboxの配置先を先に設計しておく必要があります。(Microsoft Learn)
Hosted agentへの直接注入を選ぶべきケース
Hosted agentへの直接注入は、特定のエージェントに決まったSkill versionを同梱したい場合に向いています。公式ドキュメントでは、Foundry Skills APIからSkillをダウンロードし、agent projectのディレクトリに配置すると、起動時にSKILL.mdを読み込み、各セッションの追加system instructionsとして注入されると説明されています。(Microsoft Learn)
本番運用では、以下のようなケースで直接注入が扱いやすくなります。
- リリース時点のSkillをアプリケーションと一緒に固定したい
- Skill変更を自動反映せず、アプリのデプロイ単位で管理したい
- エージェントごとに検証済みのSkillだけを同梱したい
- 障害時に、アプリケーションとSkillの組み合わせを再現したい
管理者が確認すべき設定と権限
Skillsを導入する前に、管理者はRBAC、プロジェクト設計、プレビュー機能の扱い、CI/CDの権限を確認する必要があります。
Microsoft Learnでは、Skills利用の前提として有効なMicrosoft Foundry projectと、Foundry project上のFoundry Userロールが示されています。また、Foundry RBACロールは最近名称変更されており、Foundry User、Foundry Owner、Foundry Account Owner、Foundry Project Managerは、以前のAzure AI User、Azure AI Owner、Azure AI Account Owner、Azure AI Project Managerに対応すると説明されています。ロールIDと主要な権限は変更されていません。(Microsoft Learn)
管理者向けチェックリスト
| 確認項目 | 見るべきポイント |
|---|---|
| Foundryプロジェクト | Skill、Toolbox、Hosted agentを同じプロジェクトで管理するか |
| RBAC | 開発者、CI/CD実行ID、agent identityに必要な権限があるか |
| プレビュー利用方針 | 本番利用可否、検証範囲、障害時の責任分界を決めているか |
| Skill命名規則 | 小文字、数字、ハイフン、最大64文字の制約に沿っているか |
| 変更承認 | default_version変更を誰が承認するか |
| ロールバック | 直前の安定バージョンへ戻す手順があるか |
| 監査 | どのToolbox、Hosted agentがどのSkill versionを使うか記録するか |
特に重要なのは、default_versionを誰が切り替えられるかです。Skill本文の変更は、エージェントの回答方針を変えます。軽微な文言修正に見えても、問い合わせ対応、セキュリティレビュー、契約関連の判断では影響が大きくなる可能性があります。
開発者が押さえるべき実装・移行手順
既存のAzure AI FoundryエージェントへSkillsを導入する場合、最初からすべてのプロンプトをSkill化する必要はありません。まずは変更頻度が高く、複数エージェントで重複している指示から切り出すのが現実的です。
移行の進め方
| 手順 | 作業内容 | 判断基準 |
|---|---|---|
| 既存指示の棚卸し | system prompt、コード内プロンプト、運用ドキュメントを確認 | 複数箇所に重複している指示を優先 |
| Skill候補を分割 | 目的別にSKILL.md化 | 1つのSkillが1つの役割を持つか |
| Git管理 | skills/<skill-name>/SKILL.mdの形で保存 | PRレビューできる構成か |
| Foundryへ登録 | Skills APIまたはazdでversion作成 | name、description、headerを確認 |
| 検証 | テスト用エージェントで期待応答を確認 | 禁止事項、エスカレーション、例外時の挙動を見る |
| 配布 | Toolboxにアタッチ、またはHosted agentへダウンロード | 共有重視か、固定同梱重視かで選ぶ |
| 昇格 | default_versionまたはToolbox versionを切り替え | 承認済みのversionだけを反映 |
| 監視 | 応答ログ、評価、利用者フィードバックを確認 | Skill変更前後で品質が落ちていないか |
default_versionの扱いは慎重にする
Skillsでは、新しいversionを作成してからdefault_versionを変更できます。公式ドキュメントでは、ToolboxやagentがSkill versionを固定せずに参照する場合、default_versionが使われると説明されています。また、--set-default-versionはメタデータ上の参照先変更であり、新しいコンテンツのアップロードや新version作成を伴わないため、ロールバックやロールフォワードに使えます。(Microsoft Learn)
便利な反面、default_versionを参照しているエージェントが多いほど影響範囲は広くなります。本番では、以下のどちらかを明確に選びましょう。
| 方針 | メリット | 注意点 |
|---|---|---|
default_version追従 | 共通ルールを一括更新しやすい | 影響範囲が広いため検証と承認が必須 |
| version固定 | 挙動を再現しやすい | 更新時に各参照先の変更が必要 |
全社共通の軽微な文体ルールならdefault_version追従でも運用しやすいですが、返金判断、医療・金融・法務に関わる応答、セキュリティレビュー基準などはversion固定を検討した方が安全です。
Toolbox連携で注意すべき展開上のポイント
ToolboxにSkillをアタッチすると、MCP endpoint経由でSkillを配布できます。公式ドキュメントでは、Skill referenceはnameを必須とし、versionは任意で指定できると説明されています。versionを省略するとSkillのdefault_versionを使い、指定すると特定のimmutable snapshotに固定されます。(Microsoft Learn)
Toolbox運用では、SkillそのもののversionとToolbox versionの2段階を意識する必要があります。
たとえば、support-escalationをv1からv2へ更新しても、Toolbox側がどのversionを参照しているかによって、クライアントが読み込む内容は変わります。さらに、azdでskill addやskill removeを実行した場合、それぞれ新しいToolbox versionが作られますが、その変更はazd ai toolbox publishで新versionをdefaultへ昇格するまでMCPクライアントから見えません。(Microsoft Learn)
Toolbox展開時の確認表
| 確認項目 | 理由 |
|---|---|
| Skillが同じFoundryプロジェクト内にあるか | クロスプロジェクト参照はサポートされないため |
versionを省略するか固定するか | 自動追従か再現性重視かが変わるため |
resources/listでSkillが見えるか | MCP Resourcesとして正しく公開されたか確認するため |
| Toolbox versionをpublishしたか | 新しいSkill参照がクライアントに反映されないため |
| MCP clientがResources protocolに対応しているか | 対応していないとSkillを自動発見できないため |
Foundry-Features: Toolboxes=V1Previewを付けているか | プレビューheaderが必要なため |
ZIPアップロードとazd運用で見落としやすい注意点
SKILL.mdをZIPでアップロードする場合、関連ファイルをまとめやすい一方、更新手順には注意が必要です。公式ドキュメントでは、CLIで単一の.zipアーカイブを受け付ける一方、azd ai skill updateは.zipを拒否し、既存Skillを新しいパッケージで置き換えるにはcreate --forceを使うと説明されています。ただし、この操作は既存Skillとすべてのversionを削除してから新しいv1をアップロードする挙動です。(Microsoft Learn)
これは運用上かなり重要です。create --forceを安易に使うと、過去versionを使ったロールバックや監査が難しくなる可能性があります。ZIPパッケージで複数ファイルを扱う必要がある場合でも、履歴を残す方針なら、事前に削除影響を確認し、必要に応じてパッケージを成果物として保管しておきましょう。
本番展開前に確認したいテスト観点
Skillsは、単にAPIが成功するかだけでなく、エージェントの応答品質まで確認する必要があります。以下の観点でテストケースを作ると、導入後のトラブルを減らせます。
| テスト観点 | 確認例 |
|---|---|
| 正常系 | Skillの目的に合う質問で、期待する指示が反映されるか |
| 境界条件 | エスカレーションすべきか迷う質問で安全側に倒れるか |
| 禁止事項 | 返金確約、法的断定、機密情報の開示などを避けるか |
| 競合指示 | 既存system promptとSkillの指示が矛盾しないか |
| version差分 | v1とv2で変わるべき応答だけが変わっているか |
| Toolbox反映 | resources/listで表示され、publish後にクライアントへ反映されるか |
| ロールバック | default_versionを戻したときに旧挙動へ戻るか |
特に見落としやすいのが、既存system promptとの競合です。たとえば、system promptでは「必ず簡潔に回答する」と書き、Skillでは「判断理由を詳しく説明する」と書いていると、モデルの応答が不安定になることがあります。Skill化する前に、既存プロンプトから重複・矛盾する指示を取り除く作業が必要です。
導入判断の目安
Azure AI FoundryのSkillsは、すべてのエージェントにすぐ必要な機能ではありません。以下に当てはまる場合、導入メリットが大きくなります。
| 状況 | 導入優先度 |
|---|---|
| 複数エージェントで同じ行動ルールを使っている | 高い |
| プロンプト変更のたびに複数アプリを再デプロイしている | 高い |
| コンプライアンスやブランド表現の統一が必要 | 高い |
| まだ単一の検証用エージェントしかない | 中程度 |
| プロンプトが短く、変更頻度も低い | 低め |
| 本番SLAが必須でプレビュー機能を使えない | 慎重に検討 |
プレビュー段階では、まず社内向けエージェント、検証環境、限定ユーザー向けのPoCから始めるのが現実的です。本番に近い用途で使う場合は、Skillの変更承認、影響範囲の記録、ロールバック手順を先に整備しておきましょう。
まず何をすべきか
最初に行うべきことは、既存エージェントのプロンプトから「再利用できる行動ルール」を洗い出すことです。次に、1つだけ小さなSKILL.mdを作り、検証用FoundryプロジェクトでSkills APIから登録し、Hosted agentまたはToolbox経由で読み込ませます。
おすすめの最初の題材は、サポート対応のエスカレーション基準やコードレビューのチェックリストです。どちらも期待する応答をテストしやすく、Skill化による効果が分かりやすいからです。
Azure AI FoundryのSkillsは、AIエージェントの運用を「個別プロンプト管理」から「再利用可能な行動ルール管理」へ進める機能です。プレビューの制約を理解したうえで、SKILL.mdの設計、Skills REST APIによるversion管理、ToolboxまたはHosted agentへの配布方法を小さく試すことが、安定した展開への近道です。
コメント