You can now equip your Microsoft Agent Framework agents with portable, reusable skill packages that provide domain expertise on demand — without changing a single line of your agent’s core instructions. With the new FileAgentSkillsProvider, available for both .NET and Python, your agents can discover and load Agent Skills at runtime, pulling in only the context they need, when they need it.

What Are Agent Skills?

Agent Skills is a simple, open format for giving agents new capabilities and expertise. At the core of every skill is a SKILL.md file — a markdown document that describes what the skill does and provides step-by-step instructions for how to do it. Skills can also include optional scripts, reference documents, and other resources the agent can fetch on demand.

A skill directory looks like this:

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

The SKILL.md file contains YAML frontmatter with metadata followed by the skill’s instructions in markdown. Only name and description are required; fields like license, compatibility, and metadata are optional:

---
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                   # Optional
compatibility: Requires python3       # Optional
metadata:                             # Optional
  author: contoso-finance
  version: "2.1"
---

## Instructions

1. Ask the employee for their receipt and expense details...
2. Validate against the policy in references/POLICY_FAQ.md...

Skills are useful when you want to:

• Package domain expertise — Capture specialized knowledge (expense policies, legal workflows, data analysis pipelines) as reusable packages.
• Extend agent capabilities — Give agents new abilities without modifying their core instructions.
• Ensure consistency — Turn multi-step tasks into repeatable, auditable workflows.
• Enable interoperability — Reuse the same skill across different Agent Skills-compatible products.

Progressive Disclosure: Context-Efficient by Design

One of the key design principles behind Agent Skills is progressive disclosure. Rather than loading everything into the agent’s context upfront, skills are disclosed in three stages:

1. Advertise (~100 tokens per skill) — Skill names and descriptions are injected into the system prompt so the agent knows what’s available.
2. Load (< 5,000 tokens recommended) — When a task matches a skill, the agent calls load_skill to retrieve the full SKILL.md instructions.
3. Read resources (as needed) — The agent calls read_skill_resource to fetch supplementary files (references, templates, assets) only when required.

This pattern keeps the agent’s context window lean while still giving it access to deep domain knowledge on demand — important when you’re working with agents that handle many different domains or when you want to keep token usage under control.

Creating a Skill

The simplest skill is just a folder with a SKILL.md file. Create a skills directory and add a skill folder inside it:

skills/
└── meeting-notes/
    └── SKILL.md

The SKILL.md file starts with YAML frontmatter (name and description are required) followed by instructions in markdown:

---
name: meeting-notes
description: >-
  Summarize meeting transcripts into structured notes with action items.
  Use when asked to process or summarize meeting recordings or transcripts.
---

## Instructions

1. Extract key discussion points from the transcript.
2. List any decisions that were made.
3. Create a list of action items with owners and due dates.
4. Keep the summary concise — aim for one page or less.

The description field is especially important — the agent uses it to decide when to load the skill, so include both what the skill does and when it should be used.

That’s it. No scripts, no extra files — just a folder and a SKILL.md. You can always add references/, scripts/, and assets/ directories later as your skill grows. You can also use the skill-creator skill to help you generate new skills interactively.

Connecting Skills to an Agent

The FileAgentSkillsProvider discovers skills from filesystem directories and makes them available to your agent as a context provider. It searches configured paths recursively (up to two levels deep) for SKILL.md files, validates their format and resources, and injects skill names and descriptions into the system prompt so the agent knows what’s available. It also exposes two tools to the agent:

• load_skill — Retrieves the full SKILL.md instructions when the agent determines a user’s request matches a skill’s domain, giving it detailed step-by-step guidance to address the task.
• read_skill_resource — Fetches supplementary files (references, templates, assets) bundled with a skill, allowing the agent to pull in additional context only when needed.

Using Skills in .NET

Install the package:

dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity

Set up the provider and create an agent:

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

// 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 discovers and loads matching skills automatically
AgentResponse response = await agent.RunAsync(
    "Summarize the key points and action items from today's standup meeting.");
Console.WriteLine(response.Text);

Using Skills in Python

Install the package:

pip install agent-framework --pre

Set up the provider and create an agent:

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 discovers and loads matching skills automatically
response = await agent.run(
    "Summarize the key points and action items from today's standup meeting."
)
print(response.text)

Once configured, the agent automatically discovers available skills and uses them when a user’s task matches a skill’s domain. You don’t need to write any routing logic — the agent reads the skill descriptions from the system prompt and decides when to load one.

Use Cases

Here are a few scenarios where Agent Skills can help:

Enterprise Policy Compliance

Package your company’s HR policies, expense rules, or IT security guidelines as skills. An employee-facing agent can load the relevant policy skill when someone asks “Can I expense a co-working space?” and give an accurate, policy-grounded answer — without needing all policies in context at all times.

Customer Support Playbooks

Turn your support team’s troubleshooting guides into skills. When a customer reports an issue, the agent loads the matching playbook and follows the documented steps, ensuring consistent resolution regardless of which agent instance handles the request.

Multi-Team Skill Libraries

Different teams can author and maintain their own skills independently. Point the FileAgentSkillsProvider at multiple directories to combine them:

.NET

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

Python

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

Each path can point to an individual skill folder or a parent folder containing multiple skill subdirectories.

Security

Treat skills like open-source dependencies — only use ones from sources you trust, and review them before adding them to your agent. Skill instructions are injected into the agent’s context and can influence its behavior, so the same diligence you’d apply to a new package applies here.

What’s Next

We’re continuing to build out Agent Skills support in the framework. Here’s what’s coming:

• Programmatic skills — Create and register agent skills dynamically via API, enabling scenarios where skills are generated or modified at runtime rather than authored as static files.
• Agent skill execution — Support for agents to execute scripts bundled within skills, extending skills beyond instructions and reference material into active code execution.

Learn More

To learn more and try it out yourself, check out the documentation and working samples:

• 📖 Agent Skills documentation on Microsoft Learn
• 💻 .NET sample
• 🐍 Python sample