代理人技能

代理技能是可攜式的指令、腳本與資源套件，賦予代理專業能力與領域專業知識。技能遵循開放規範，並實施漸進式揭露模式，讓客服人員在需要時只載入他們需要的上下文。

使用代理技能的時機是：

套件領域專業知識 — 將專業知識（費用政策、法律工作流程、資料分析流程）以可重用、可攜式的套件形式呈現。
擴展代理能力 — 賦予代理新能力，且不改變其核心指令。
確保一致性 — 將多步驟任務轉化為可重複且可稽核的工作流程。
啟用互通性 — 在不同支援 Agent Skills 的產品間重複使用同一技能。

技能結構

技能是一個目錄，其中包含一個 SKILL.md 檔案，並且可以有用於儲存資源的子目錄：

expense-report/
├── SKILL.md                          # Required — frontmatter + instructions
├── scripts/
│   └── validate.py                   # Executable code agents can run
├── references/
│   └── POLICY_FAQ.md                 # Reference documents loaded on demand
└── assets/
    └── expense-report-template.md    # Templates and static resources

SKILL.md 格式

SKILL.md檔案必須包含 YAML 前導內容，然後是 markdown 內容：

---
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits.
license: Apache-2.0
compatibility: Requires python3
metadata:
  author: contoso-finance
  version: "2.1"
---

領域	為必填項目	Description
`name`	Yes	最多64字元。只限小寫字母、數字和連字號。不得以連字號開頭或結尾，或包含連續連字號。必須與父目錄名稱相符。
`description`	Yes	這個技能的作用以及何時使用。最多 1024 字元。應包含幫助客服人員辨識相關任務的關鍵字。
`license`	否	授權名稱或綁定授權檔案的引用。
`compatibility`	否	最多 500 字元。表示環境需求（預期產品、系統套件、網路存取等）。
`metadata`	否	額外元資料的任意鍵值映射。
`allowed-tools`	否	預先核准工具的以空格分隔的清單。實驗性 — 支援可能因代理實作而異。

前言後的標記內容包含技能指示——逐步指導、輸入與輸出範例、常見邊緣案例，或任何有助於代理執行任務的內容。行數控制 SKILL.md 在 500 行以內，並將詳細參考資料移到獨立檔案。

漸進式披露

Agent Skills 採用三階段漸進式揭露模式以最小化情境使用：

廣告（~每個技能100個代幣）— 技能名稱與描述會在每次遊戲開始時注入系統提示，讓代理人知道可用的技能。
載入（< 建議 5000 個代幣）— 當任務符合技能領域時，代理會呼叫工具 load_skill 以取得完整 SKILL.md 內容並附上詳細指示。
讀取資源 （視需要）— 代理程式僅在需要時呼叫 read_skill_resource 工具擷取補充檔案（參考、範本、資產）。

這種模式讓代理的上下文視窗保持精簡，同時能隨時存取深層的領域知識。

使用 FileAgentSkillsProvider

它 FileAgentSkillsProvider 從檔案系統目錄中發現技能，並作為情境提供者提供給代理。它會以遞迴方式（最多可達兩層深度）搜尋已設定的路徑檔案 SKILL.md ，驗證其格式與資源，並向代理者開放兩個工具： load_skill 與 read_skill_resource。

備註

腳本執行尚未被支援 FileAgentSkillsProvider ，未來版本會加入。

基本設定

建立 FileAgentSkillsProvider 指向包含你技能的目錄，並將其加入代理人的上下文提供者中：

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

// Discover skills from the 'skills' directory
var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));

// Create an agent with the skills provider
AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "SkillsAgent",
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

喚起代理

設定完成後，代理會自動發現可用技能，並在任務匹配時使用：

// The agent loads the expense-report skill and reads the FAQ resource
AgentResponse response = await agent.RunAsync(
    "Are tips reimbursable? I left a 25% tip on a taxi ride.");
Console.WriteLine(response.Text);

基本設定

建立 FileAgentSkillsProvider 指向包含你技能的目錄，並將其加入代理人的上下文提供者中：

from pathlib import Path
from agent_framework import FileAgentSkillsProvider
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity.aio import AzureCliCredential

# Discover skills from the 'skills' directory
skills_provider = FileAgentSkillsProvider(
    skill_paths=Path(__file__).parent / "skills"
)

# Create an agent with the skills provider
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

呼叫代理

設定完成後，代理會自動發現可用技能，並在任務匹配時使用：

# The agent loads the expense-report skill and reads the FAQ resource
response = await agent.run(
    "Are tips reimbursable? I left a 25% tip on a taxi ride."
)
print(response.text)

多重技能目錄

您可以透過傳遞一串路徑來搜尋多個目錄：

var skillsProvider = new FileAgentSkillsProvider(
    skillPaths: [
        Path.Combine(AppContext.BaseDirectory, "company-skills"),
        Path.Combine(AppContext.BaseDirectory, "team-skills"),
    ]);

skills_provider = FileAgentSkillsProvider(
    skill_paths=[
        Path(__file__).parent / "company-skills",
        Path(__file__).parent / "team-skills",
    ]
)

每條路徑都可以指向一個獨立的技能資料夾（包含 SKILL.md），或是帶有技能子目錄的父資料夾。提供者會搜尋最多兩層深度。

自訂系統提示

預設情況下，會 FileAgentSkillsProvider 注入一個系統提示，列出可用技能並指示代理使用 load_skill 與 read_skill_resource。你可以自訂這個提示詞：

var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new FileAgentSkillsProviderOptions
    {
        SkillsInstructionPrompt = """
            You have skills available. Here they are:
            {0}
            Use the `load_skill` function to get skill instructions.
            Use the `read_skill_resource` function to read skill files.
            """
    });

備註

自訂範本必須包含插入技能清單的 {0} 佔位符。字面上的大括號必須分別跳脫為{{和}}。

skills_provider = FileAgentSkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    skills_instruction_prompt=(
        "You have skills available. Here they are:\n{0}\n"
        "Use the `load_skill` function to get skill instructions.\n"
        "Use the `read_skill_resource` function to read skill files."
    ),
)

備註

自訂範本必須包含用於插入技能清單的 {0} 佔位符。

安全性考慮

FileAgentSkillsProvider 僅讀取檔案系統中的靜態內容，並包含以下安全措施：

XML 轉譯 — 技能元資料（名稱與描述）在注入系統提示前進行 XML 轉譯，以防止通過技能前置資料進行提示注入。
路徑穿越保護 — 資源讀取驗證已解析的檔案路徑仍位於技能目錄內，阻止 ../ 逃脫嘗試。
符號連結警衛 — 每個路徑區段都會檢查可能在技能目錄外進行解析的符號連結。
發現時驗證 — 所有引用的資源在技能載入時都會被驗證。缺少或無效資源的技能會被排除並登錄。

警告

只使用可信來源的技能。技能指令會注入代理人的情境，並能影響代理人的行為。

後續步驟

情境提供者

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-02-26

共用方式為

代理人技能

技能結構

SKILL.md 格式

漸進式披露

使用 FileAgentSkillsProvider

基本設定

喚起代理

基本設定

呼叫代理

多重技能目錄

自訂系統提示

安全性考慮

後續步驟

相關內容

意見反應

其他資源