Agent Skills

Agent Skills are portable packages of instructions, scripts, and resources that give agents specialized capabilities and domain expertise. Skills follow an open specification and implement a progressive disclosure pattern so agents load only the context they need, when they need it.

Use Agent Skills when you want to:

• Package domain expertise — Capture specialized knowledge (expense policies, legal workflows, data analysis pipelines) as reusable, portable packages.
• Extend agent capabilities — Give agents new abilities without changing 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.

Skill structure

A skill is a directory containing a SKILL.md file with optional subdirectories for resources:

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 format

The SKILL.md file must contain YAML frontmatter followed by markdown content:

---
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"
---

The markdown body after the frontmatter contains the skill instructions — step-by-step guidance, examples of inputs and outputs, common edge cases, or any content that helps the agent perform the task. Keep SKILL.md under 500 lines and move detailed reference material to separate files.

Progressive disclosure

Agent Skills use a three-stage progressive disclosure pattern to minimize context usage:

1. Advertise (~100 tokens per skill) — Skill names and descriptions are injected into the system prompt at the start of each run, so the agent knows what skills are available.
2. Load (< 5000 tokens recommended) — When a task matches a skill's domain, the agent calls the load_skill tool to retrieve the full SKILL.md body with detailed instructions.
3. Read resources (as needed) — The agent calls the read_skill_resource tool to fetch supplementary files (references, templates, assets) only when required.

This pattern keeps the agent's context window lean while giving it access to deep domain knowledge on demand.

Using FileAgentSkillsProvider

The FileAgentSkillsProvider discovers skills from filesystem directories and makes them available to agents as a context provider. It searches configured paths recursively (up to two levels deep) for SKILL.md files, validates their format and resources, and exposes two tools to the agent: load_skill and read_skill_resource.

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);

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)

Multiple skill directories

You can search multiple directories by passing a list of paths:

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",
    ]
)

Each path can point to an individual skill folder (containing a SKILL.md) or a parent folder with skill subdirectories. The provider searches up to two levels deep.

Custom system prompt

By default, FileAgentSkillsProvider injects a system prompt that lists available skills and instructs the agent to use load_skill and read_skill_resource. You can customize this prompt:

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.
            """
    });

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."
    ),
)

Security considerations

FileAgentSkillsProvider reads only static content from the filesystem and includes the following security measures:

• XML-escaping — Skill metadata (names and descriptions) is XML-escaped before being injected into the system prompt, preventing prompt injection through skill frontmatter.
• Path traversal protection — Resource reads validate that the resolved file path remains within the skill directory, blocking ../ escape attempts.
• Symlink guards — Each path segment is checked for symlinks that could resolve outside the skill directory.
• Validation at discovery — All referenced resources are validated when skills are loaded. Skills with missing or invalid resources are excluded and logged.

Next steps

Related content

• Agent Skills specification
• Context Providers
• Tools Overview