File-Based Agent Skills

This repository demonstrates how to use file-based skills with the Microsoft Agent Framework (MAF) to build modular, context-efficient AI agents.

Skills are self-contained units of domain knowledge that the agent discovers and loads on demand. This approach keeps the context window lean while enabling rich, composable agent capabilities.

Getting Started

The recommended way to run this is with GitHub Codespaces, which provides a ready-to-use environment with all required tools. Alternatively, you can use Visual Studio Code to run it locally.

Using GitHub Codespaces

Once you've forked the repository, navigate to your forked repository on GitHub and click the green Code button, then select the Codespaces tab and click Create codespace on main.

The Codespace will be pre-configured with all the necessary dependencies and tools.

Prerequisites

• Azure Subscription: Sign up for a free Azure account
• Azure Developer CLI (azd): Required for provisioning Azure resources

Verify Azure Developer CLI Installation

Run the following command in your terminal to verify the installation:

azd version

Setup Azure Infrastructure

Create your Azure environment by provisioning the necessary resources:

Authenticate with Azure

First, authenticate with your Azure account using the Azure Developer CLI:

azd auth login --use-device-code

Follow the prompts to complete the authentication process in your browser.

Create and Configure Environment

Create a new environment for your Azure resources:

azd env new dev
azd env select dev
azd env set AZURE_LOCATION australiaeast

Note: You can change australiaeast to any Azure region that supports AI Foundry. Common options include: eastus, westus2, westeurope, southeastasia.

Provision and Deploy

Deploy all required Azure resources using a single command:

azd up

This command will:

• Provision Azure AI Foundry resources (AI Hub, AI Project)
• Deploy AI models
• Configure authentication and permissions

Note: The deployment process may take 5-10 minutes to complete.

Verify Deployment

1. Navigate to the Azure Portal
2. Look for a resource group named rg-aiagent-ws-dev (or similar, based on your environment name)
3. Verify the following resources are created:
   • Azure AI Hub
   • Azure AI Project
   • AI models (e.g., GPT-4)

Running the Application Locally

This example shows how to use file-based skills with the FileAgentSkillsProvider for progressive disclosure of agent capabilities.

Modular skill packages (SKILL.md files) provide domain-specific instructions to the agent on demand.

You will:

• Understand how FileAgentSkillsProvider works
• See progressive disclosure in action (advertise -> load -> read resources)
• Organise agent capabilities into reusable, composable skill packages

Key Implementation Details

What are File-Based Skills?

Skills are self-contained units of domain knowledge stored as SKILL.md files in a directory. Each skill has a name, a short description, and detailed instructions.

Rather than loading all skill instructions upfront (which wastes context tokens), FileAgentSkillsProvider uses progressive disclosure:

1. Advertise — the agent receives only the skill name and description (~100 tokens per skill)
2. Load — the agent calls load_skill to fetch full instructions for skills it actually needs
3. Read resources — the agent calls read_skill_resource to pull in supplementary files on demand

This means large sets of skills can be registered without bloating the context window.

Skill Directory Structure

Skills are under the ./skills folder, one sub-directory per skill:

skills/
  weather-info/
    SKILL.md          ← name, description, and instructions
  visa-recommendation/
    SKILL.md
  destination-recommendation/
    SKILL.md

Each SKILL.md starts with a YAML front-matter block that provides the advertised name and description:

---
name: weather-info
description: Provides weather forecasts for travel destinations
---

# Weather Information Skill
...full instructions loaded on demand...

Registering the Skills Provider

Create a FileAgentSkillsProvider pointing at the skills directory, then pass it as an AIContextProvider:

var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));

var agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    Name = "TravelAssistant",
    ChatOptions = new()
    {
        Instructions = "You are a helpful travel assistant...",
        Tools = [AIFunctionFactory.Create(GetWeatherForecast)],
    },
    AIContextProviders = [skillsProvider],
})
.AsBuilder()
.UseOpenTelemetry(SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)
.UseLogging(loggerFactory)
.Build();

The provider automatically injects the advertised skill list into the agent's context and registers the load_skill and read_skill_resource tools so the agent can fetch details at runtime.

Combining Skills with Regular Tools

Skills and tools are complementary:

• Tools (AIFunctionFactory.Create) expose callable functions (e.g., GetWeatherForecast)
• Skills (FileAgentSkillsProvider) supply domain instructions and knowledge that guide how the agent uses those tools

Instructions

Step 1: Run the Program

With .NET 10's file-based apps, you can run the single .cs file directly:

dotnet run Program.cs

Or in Visual Studio Code, open Program.cs and click the Run button that appears above the code.

Step 2: Observe the Output

The agent discovers skills from the ./skills directory and loads them on-demand when needed. Watch the logs to see which skills are advertised versus which are actually loaded during the conversation.

(Optional) Set Up Aspire Dashboard for Observability

The .NET Aspire Dashboard provides a web-based UI for viewing OpenTelemetry traces, metrics, and logs in real-time. This is useful for monitoring your agent's behaviour and debugging.

Refer to the Aspire Dashboard Setup Guide for detailed instructions on how to set up the dashboard locally using Docker.