ヘッドウォータース
👋

Microsoft Agent Framework の Agent Skills を試してみる

takekawa tomoki
に公開
Skills
Microsoft Agent Framework
tech

執筆日

2026/5/5

参考資料

https://learn.microsoft.com/en-us/agent-framework/agents/skills

はじめに

Microsoft Agent Framework を勉強している中で、GitHub のサンプルを見ていたところ Skills という機能を見つけました。

Agent Skills は、エージェントに専門的な能力や業務知識を追加するための仕組みです。
業務ルール、手順、参考資料、スクリプトなどをひとまとまりのパッケージとして定義し、エージェントが必要に応じて利用できます。
https://learn.microsoft.com/en-us/agent-framework/agents/skills

気になったので、実際にどのようなことができるのか試してみました。

Agent Skills とは

Agent Skills は、エージェントに対して特定領域の知識や処理能力を追加するためのパッケージです。

例えば、以下のような用途で利用できます。

  • 会社情報に関するナレッジを参照させる
  • 経費精算ルールをもとに回答させる
  • コーディング規約を参照させる
  • データ分析や検証処理をスクリプトとして実行させる
  • 業務手順を標準化してエージェントに従わせる

Agent Skills の動作イメージ

Agent Skills の重要な考え方として、Progressive Disclosure があります。

これは、すべての情報を最初からエージェントに渡すのではなく、必要な情報だけを段階的に読み込む仕組みです。

流れは以下です。

  1. Advertise
    Skill 名と description だけがエージェントに共有される

  2. Load
    関連する Skill だと判断された場合、SKILL.md の本文を読み込む

  3. Read resources
    必要に応じて references や assets 配下の資料を読み込む

  4. Run scripts
    必要に応じて Skill に含まれるスクリプトを実行する

この仕組みにより、コンテキストを無駄に消費せず、必要なタイミングで必要な知識だけを利用できます。

Skills の定義方法

Python で Agent Skills を使う場合、大きく以下の2つの方法があります。

  1. ファイルベースで定義する
  2. Python コード上で定義する

この記事では、この2つを試します。

SKILL.md について

ファイルベースで Skill を定義する場合、SKILL.md を作成します。

SKILL.md は、先頭に YAML frontmatter を書き、その後に Markdown 形式で Skill の指示 を書きます。

---
name: <スキル名>
description: <スキルの説明文>
license: Apache-2.0
compatibility: Requires python3
metadata:
  author: your-name
  version: "1.0"
---

主なフィールドは以下です。

フィールド 必須 説明
name はい Skill 名です。最大64文字で、小文字の英字・数字・ハイフンのみ使用できます。先頭または末尾にハイフンは使えません。連続したハイフンも禁止です。また、親ディレクトリ名と一致している必要があります。
description はい Skill が何を行うか、どのような場面で使うかを説明します。最大1024文字です。エージェントが関連タスクを判別しやすいよう、キーワードを含めることが推奨されます。
license 任意 ライセンス名、または同梱したライセンスファイルへの参照を記載します。
compatibility 任意 実行環境の要件を記載します。例として、必要な Python バージョンやシステムパッケージなどを記載できます。
metadata 任意 author や version など、任意のメタデータを key-value 形式で記載できます。

ファイルベースで Skills を定義する

まずは、SKILL.md と参照資料を使って Skill を定義します。

フォルダー構成

.
├── Script
│   └── main.py
└── skills
    └── expert4company
        ├── SKILL.md
        └── references
            └── company.md

MS Learn の例では、補助資料の配置先として references や assets が使われています。
そのため、この記事でも reference ではなく references に統一します。

Python コード

import asyncio
import os
from pathlib import Path

from agent_framework import SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
from dotenv import load_dotenv

load_dotenv()

# skills ディレクトリから Skill を検出する
skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent.parent / "skills"
)

agent = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL"),
    credential=AzureCliCredential(),
).as_agent(
    name="companyagent",
    instructions="会社情報について詳しいエージェントです。",
    context_providers=[skills_provider],
)

async def main() -> None:
    response = await agent.run(
        "株式会社ヘッドウォータースについて教えてください。また参照した資料も提示してください。"
    )
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

SKILL.md

---
name: expert4company
description: 会社情報に関する質問に回答するスキルです。
---

## Usage

会社情報に関する質問が来たら、必ず `references/company.md` を参照して回答すること。

推測は避け、`references/company.md` に記載されている内容を優先すること。

回答の最後に、参照したファイル名を提示すること。

ここで重要なのは、name が親ディレクトリ名と一致している点です。

skills/expert4company/SKILL.md
       └──────────── name: expert4company

name はエージェント名ではなく、Skill 名です。
この点は誤解しやすいので注意が必要です。

参照ファイル

references/company.md
# 会社名

## 基本情報

本社所在地は東京都新宿区西新宿六丁目５番１号で、東京証券取引所（証券コード：4011）に上場しています。

## 事業概要

国内トップクラスのAIテックカンパニーとして、AIの社会実装を目指す企業です。AIの研究開発をはじめ、上流工程のコンサルティングからシステム開発、運用保守までを一気通貫で手掛ける事業モデルを強みとしており、日本マイクロソフトとの強固なパートナーシップなどアライアンス戦略も展開しています。

現在は以下の4つのセグメントで事業展開しています。

1. AIインテグレーションサービス
2. デジタルトランスフォーメーションサービス
3. プロダクトサービス
4. OPSサービス

## 沿革・AIへの取り組み

2014年に Pepper アプリケーション開発を手掛けたことをきっかけに、画像認識や言語認識といった AI 技術の実装ノウハウを蓄積しました。そのノウハウを AI 事業として推進していったところ、ユーザー視点で AI 活用・実装ができる企業が少なかった中で多くの引き合いにつながり、現在に至ります。

## 強み

AI のアセスメントから周辺システムの開発・運用までを1社で完結させ、成果を出せていることを自社の強みとしています。

また、金融系からスマホアプリ、業務システム、EC まで広範囲な受託開発の経験、ソフトバンクのロボット「Pepper」のアプリ開発で培った多様な技術、そして AI 未経験人材を1年で高度なスペシャリストに育てる育成ノウハウも強みとして挙げています。

## 主な実績・サービス

最近の取り組みとしては、音声指示で自律動作ロボットを制御するフィジカル AI の支援、従来型 SaaS の AI エージェント化を支援する改善循環モデルの提供、暗黙知を構造化データへ変換する「SyncLect Data Intelligence」の発表などがあります。

また、大和証券の「AIオペレーター」開発において、プライムベンダーとして AI コアエージェントとアプリケーションを担当するなど、金融業界でも実績があります。

## グローバル展開

グループ企業として、ベトナム・ハノイを拠点とする DATA IMPACT JOINT STOCK COMPANY を持ち、AI モデル開発、データ基盤構築、クラウドソリューション、IoT、エッジ AI 開発などの領域で、日本企業の DX 推進を支援しています。

実行結果

株式会社ヘッドウォータースについてご説明します。

【基本情報】
- 本社所在地：東京都新宿区西新宿六丁目５番１号
- 東京証券取引所（証券コード：4011）に上場しています。

【事業概要】
- 国内トップクラスのAIテックカンパニーで、AIの社会実装を目指しています。
- AIの研究開発から上流工程のコンサルティング、システム開発、運用保守までを一気通貫で手掛ける事業モデルを持っています。
- 日本マイクロソフトとの強固なパートナーシップなどアライアンス戦略を展開しています。

4つのセグメントで事業展開しています。

1. AIインテグレーションサービス
2. デジタルトランスフォーメーションサービス
3. プロダクトサービス
4. OPSサービス

【参照資料】
- references/company.md

instruction_template を指定する

試している中で、Skill の利用ルールをより明示したくなったため、instruction_template も指定してみました。

import asyncio
import os
from pathlib import Path

from agent_framework import SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
from dotenv import load_dotenv

load_dotenv()

SKILLS_PROMPT = """
Skillsは以下のように定義されています。
{skills}

Rules:
- スキルの名前や説明に基づいて関連性を判断すること。
- 関連がある場合は、`load_skill` を呼び出して SKILL.md の指示を読み込むこと。

{runner_instructions}
""".strip()

skills_provider = SkillsProvider(
    skill_paths=[
        Path(__file__).parent.parent / "skills"
    ],
    instruction_template=SKILLS_PROMPT,
)

agent = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL"),
    credential=AzureCliCredential(),
).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant. Follow the skill rules strictly.",
    context_providers=[skills_provider],
)

async def main() -> None:
    response = await agent.run(
        "株式会社ヘッドウォータースについて教えてください。また参照した reference ファイルを提示してください。"
    )
    print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

instruction_template は、今回の実験で Skill の利用ルールを明示するために指定しています。
MS Learn の基本的なファイルベース Skill の説明では、SkillsProvider に skill_paths を渡す構成が中心です。

コードベースで Skills を定義する

次に、Python コード上で Skill を定義します。

ファイルベースでは SKILL.md を作成しましたが、コードベースでは Skill クラスを使って Python のコード内に Skill を定義します。
MS Learn でも、コード定義の Skill は、Skill の内容をアプリケーションコードと一緒に管理したい場合や、動的なリソースを扱いたい場合に有効と説明されています。

動的リソース

@skill.resource デコレーターを使うことで、Python 関数を Skill のリソースとして登録できます。

この関数は、エージェントがそのリソースを読むたびに実行されます。

コード例

import asyncio
import os
from typing import Any

from agent_framework import Agent, Skill, SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
from dotenv import load_dotenv

load_dotenv()

project_info_skill = Skill(
    name="project-info",
    description="プロジェクトの環境設定やチーム構成を案内するスキル",
    content=(
        "このスキルは、プロジェクトの実行環境やチームメンバーについて質問されたときに使います。\n"
        "回答する前に、必要に応じて環境情報とチーム情報のリソースを確認してください。\n"
        "不明なことは推測せず、取得できる情報だけを簡潔に回答してください。"
    ),
)

@project_info_skill.resource
def environment() -> Any:
    """現在の実行環境情報を返す。"""
    env = os.environ.get("APP_ENV", "development")
    region = os.environ.get("APP_REGION", "us-east-1")
    return f"現在の環境は {env}、リージョンは {region} です。"

@project_info_skill.resource(
    name="team-roster",
    description="現在のチームメンバー一覧"
)
def get_team_roster() -> Any:
    """チームメンバー一覧を返す。"""
    return "チームメンバーは、Alice Chen（Tech Lead）と Bob Smith（Backend Engineer）です。"

async def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ.get("FOUNDRY_MODEL"),
        credential=AzureCliCredential(),
    )

    async with Agent(
        client=client,
        name="SkillsAgent",
        instructions="あなたは親切なアシスタントです。必要に応じてスキルの情報を参照し、簡潔に回答してください。",
        context_providers=[
            SkillsProvider(skills=[project_info_skill])
        ],
    ) as agent:
        response = await agent.run(
            "このプロジェクトの環境とチームメンバーを教えてください。"
        )
        print(response)

if __name__ == "__main__":
    asyncio.run(main())

実行結果

このプロジェクトの環境とチームメンバーは以下のとおりです。

- 環境：development
- リージョン：us-east-1
- チームメンバー：Alice Chen（Tech Lead）、Bob Smith（Backend Engineer）

ファイルベースとコードベースの違い

観点 ファイルベース コードベース
定義方法 SKILL.md に定義する Python の Skill オブジェクトで定義する
指示の書き方 Markdown 本文に書く content に書く
参照情報 references や assets 配下のファイル @skill.resource で登録した関数
向いている用途 固定の業務ナレッジ、手順書、テンプレート 環境変数、DB、API など動的な情報
管理しやすいもの ドキュメント中心の Skill アプリケーションロジックと連動する Skill

試してわかったこと

今回試してみて、Agent Skills は単なるプロンプト追加ではなく、エージェントに業務知識や処理能力を追加するための再利用可能な単位だと感じました。

特に良いと感じた点は以下です。

  • Skill 単位で業務知識を分離できる
  • description によって、エージェントが使うべき Skill を判断できる
  • references に業務資料を分けられる
  • Python コードで定義すれば、動的な情報も扱える
ヘッドウォータース
ヘッドウォータース

株式会社ヘッドウォータースのテックブログです。 AIエージェント、生成AI、Azure、GitHub Copilot、IoT、XR系などData&AIとApp modernizeに関して幅広く投稿します！

Discussion