.NET: Support Agent Skills (#4122)

* support agent skills * make the new agent skill provider experimental * Fix file encoding: add UTF-8 BOM to .cs files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix final newline and simplify new expressions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix broken links in Agent Skills sample README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add null check for skillPaths parameter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Normalize references * normilize skill path * address comments regarding symlink check * address comments * fix failing test + regex improvements * small optimizations and improvments * address pr review comments * Update dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com> * address pr review comments * address pr review comments --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-02-20 21:05:56 +00:00
parent 44aec2009f
commit 7ba636d642
18 changed files with 1776 additions and 1 deletions
@@ -2,12 +2,14 @@

  <PropertyGroup>
    <IsReleaseCandidate>true</IsReleaseCandidate>
-    <NoWarn>$(NoWarn);MEAI001</NoWarn>
+    <NoWarn>$(NoWarn);MEAI001;MAAI001</NoWarn>
  </PropertyGroup>

  <PropertyGroup>
    <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
    <InjectDiagnosticClassesOnLegacy>true</InjectDiagnosticClassesOnLegacy>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
    <InjectTrimAttributesOnLegacy>true</InjectTrimAttributesOnLegacy>
    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
  </PropertyGroup>
@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a loaded Agent Skill discovered from a filesystem directory.
+/// </summary>
+/// <remarks>
+/// Each skill is backed by a <c>SKILL.md</c> file containing YAML frontmatter (name and description)
+/// and a markdown body with instructions. Resource files referenced in the body are validated at
+/// discovery time and read from disk on demand.
+/// </remarks>
+internal sealed class FileAgentSkill
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAgentSkill"/> class.
+    /// </summary>
+    /// <param name="frontmatter">Parsed YAML frontmatter (name and description).</param>
+    /// <param name="body">The SKILL.md content after the closing <c>---</c> delimiter.</param>
+    /// <param name="sourcePath">Absolute path to the directory containing this skill.</param>
+    /// <param name="resourceNames">Relative paths of resource files referenced in the skill body.</param>
+    public FileAgentSkill(
+        SkillFrontmatter frontmatter,
+        string body,
+        string sourcePath,
+        IReadOnlyList<string>? resourceNames = null)
+    {
+        this.Frontmatter = Throw.IfNull(frontmatter);
+        this.Body = Throw.IfNull(body);
+        this.SourcePath = Throw.IfNullOrWhitespace(sourcePath);
+        this.ResourceNames = resourceNames ?? [];
+    }
+
+    /// <summary>
+    /// Gets the parsed YAML frontmatter (name and description).
+    /// </summary>
+    public SkillFrontmatter Frontmatter { get; }
+
+    /// <summary>
+    /// Gets the SKILL.md body content (without the YAML frontmatter).
+    /// </summary>
+    public string Body { get; }
+
+    /// <summary>
+    /// Gets the directory path where the skill was discovered.
+    /// </summary>
+    public string SourcePath { get; }
+
+    /// <summary>
+    /// Gets the relative paths of resource files referenced in the skill body (e.g., "references/FAQ.md").
+    /// </summary>
+    public IReadOnlyList<string> ResourceNames { get; }
+}
@@ -0,0 +1,407 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Discovers, parses, and validates SKILL.md files from filesystem directories.
+/// </summary>
+/// <remarks>
+/// Searches directories recursively (up to <see cref="MaxSearchDepth"/> levels) for SKILL.md files.
+/// Each file is validated for YAML frontmatter and resource integrity. Invalid skills are excluded
+/// with logged warnings. Resource paths are checked against path traversal and symlink escape attacks.
+/// </remarks>
+internal sealed partial class FileAgentSkillLoader
+{
+    private const string SkillFileName = "SKILL.md";
+    private const int MaxSearchDepth = 2;
+    private const int MaxNameLength = 64;
+    private const int MaxDescriptionLength = 1024;
+
+    // Matches YAML frontmatter delimited by "---" lines. Group 1 = content between delimiters.
+    // Multiline makes ^/$ match line boundaries; Singleline makes . match newlines across the block.
+    // The \uFEFF? prefix allows an optional UTF-8 BOM that some editors prepend.
+    // Example: "---\nname: foo\n---\nBody" → Group 1: "name: foo\n"
+    private static readonly Regex s_frontmatterRegex = new(@"\A\uFEFF?^---\s*$(.+?)^---\s*$", RegexOptions.Multiline | RegexOptions.Singleline | RegexOptions.Compiled, TimeSpan.FromSeconds(5));
+
+    // Matches markdown links to local resource files. Group 1 = relative file path.
+    // Supports optional ./ or ../ prefixes; excludes URLs (no ":" in the path character class).
+    // Intentionally conservative: only matches paths with word characters, hyphens, dots,
+    // and forward slashes. Paths with spaces or special characters are not supported.
+    // Examples: [doc](refs/FAQ.md) → "refs/FAQ.md", [s](./s.json) → "./s.json",
+    //           [p](../shared/doc.txt) → "../shared/doc.txt"
+    private static readonly Regex s_resourceLinkRegex = new(@"\[.*?\]\((\.?\.?/?[\w][\w\-./]*\.\w+)\)", RegexOptions.Compiled, TimeSpan.FromSeconds(5));
+
+    // Matches YAML "key: value" lines. Group 1 = key, Group 2 = quoted value, Group 3 = unquoted value.
+    // Accepts single or double quotes; the lazy quantifier trims trailing whitespace on unquoted values.
+    // Examples: "name: foo" → (name, _, foo), "name: 'foo bar'" → (name, foo bar, _),
+    //           "description: \"A skill\"" → (description, A skill, _)
+    private static readonly Regex s_yamlKeyValueRegex = new(@"^\s*(\w+)\s*:\s*(?:[""'](.+?)[""']|(.+?))\s*$", RegexOptions.Multiline | RegexOptions.Compiled, TimeSpan.FromSeconds(5));
+
+    // Validates skill names: lowercase letters, numbers, and hyphens only; must not start or end with a hyphen.
+    // Examples: "my-skill" ✓, "skill123" ✓, "-bad" ✗, "bad-" ✗, "Bad" ✗
+    private static readonly Regex s_validNameRegex = new(@"^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$", RegexOptions.Compiled);
+
+    private readonly ILogger _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAgentSkillLoader"/> class.
+    /// </summary>
+    /// <param name="logger">The logger instance.</param>
+    internal FileAgentSkillLoader(ILogger logger)
+    {
+        this._logger = logger;
+    }
+
+    /// <summary>
+    /// Discovers skill directories and loads valid skills from them.
+    /// </summary>
+    /// <param name="skillPaths">Paths to search for skills. Each path can point to an individual skill folder or a parent folder.</param>
+    /// <returns>A dictionary of loaded skills keyed by skill name.</returns>
+    internal Dictionary<string, FileAgentSkill> DiscoverAndLoadSkills(IEnumerable<string> skillPaths)
+    {
+        var skills = new Dictionary<string, FileAgentSkill>(StringComparer.OrdinalIgnoreCase);
+
+        var discoveredPaths = DiscoverSkillDirectories(skillPaths);
+
+        LogSkillsDiscovered(this._logger, discoveredPaths.Count);
+
+        foreach (string skillPath in discoveredPaths)
+        {
+            FileAgentSkill? skill = this.ParseSkillFile(skillPath);
+            if (skill is null)
+            {
+                continue;
+            }
+
+            if (skills.TryGetValue(skill.Frontmatter.Name, out FileAgentSkill? existing))
+            {
+                LogDuplicateSkillName(this._logger, skill.Frontmatter.Name, skillPath, existing.SourcePath);
+
+                // Skip duplicate skill names, keeping the first one found.
+                continue;
+            }
+
+            skills[skill.Frontmatter.Name] = skill;
+
+            LogSkillLoaded(this._logger, skill.Frontmatter.Name);
+        }
+
+        LogSkillsLoadedTotal(this._logger, skills.Count);
+
+        return skills;
+    }
+
+    /// <summary>
+    /// Reads a resource file from disk with path traversal and symlink guards.
+    /// </summary>
+    /// <param name="skill">The skill that owns the resource.</param>
+    /// <param name="resourceName">Relative path of the resource within the skill directory.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The UTF-8 text content of the resource file.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// The resource is not registered, resolves outside the skill directory, or does not exist.
+    /// </exception>
+    internal async Task<string> ReadSkillResourceAsync(FileAgentSkill skill, string resourceName, CancellationToken cancellationToken = default)
+    {
+        resourceName = NormalizeResourcePath(resourceName);
+
+        if (!skill.ResourceNames.Any(r => r.Equals(resourceName, StringComparison.OrdinalIgnoreCase)))
+        {
+            throw new InvalidOperationException($"Resource '{resourceName}' not found in skill '{skill.Frontmatter.Name}'.");
+        }
+
+        string fullPath = Path.GetFullPath(Path.Combine(skill.SourcePath, resourceName));
+        string normalizedSourcePath = Path.GetFullPath(skill.SourcePath) + Path.DirectorySeparatorChar;
+
+        if (!IsPathWithinDirectory(fullPath, normalizedSourcePath))
+        {
+            throw new InvalidOperationException($"Resource file '{resourceName}' references a path outside the skill directory.");
+        }
+
+        if (!File.Exists(fullPath))
+        {
+            throw new InvalidOperationException($"Resource file '{resourceName}' not found in skill '{skill.Frontmatter.Name}'.");
+        }
+
+        if (HasSymlinkInPath(fullPath, normalizedSourcePath))
+        {
+            throw new InvalidOperationException($"Resource file '{resourceName}' is a symlink that resolves outside the skill directory.");
+        }
+
+        LogResourceReading(this._logger, resourceName, skill.Frontmatter.Name);
+
+#if NET
+        return await File.ReadAllTextAsync(fullPath, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+        return await Task.FromResult(File.ReadAllText(fullPath, Encoding.UTF8)).ConfigureAwait(false);
+#endif
+    }
+
+    private static List<string> DiscoverSkillDirectories(IEnumerable<string> skillPaths)
+    {
+        var discoveredPaths = new List<string>();
+
+        foreach (string rootDirectory in skillPaths)
+        {
+            if (string.IsNullOrWhiteSpace(rootDirectory) || !Directory.Exists(rootDirectory))
+            {
+                continue;
+            }
+
+            SearchDirectoriesForSkills(rootDirectory, discoveredPaths, currentDepth: 0);
+        }
+
+        return discoveredPaths;
+    }
+
+    private static void SearchDirectoriesForSkills(string directory, List<string> results, int currentDepth)
+    {
+        string skillFilePath = Path.Combine(directory, SkillFileName);
+        if (File.Exists(skillFilePath))
+        {
+            results.Add(Path.GetFullPath(directory));
+        }
+
+        if (currentDepth >= MaxSearchDepth)
+        {
+            return;
+        }
+
+        foreach (string subdirectory in Directory.EnumerateDirectories(directory))
+        {
+            SearchDirectoriesForSkills(subdirectory, results, currentDepth + 1);
+        }
+    }
+
+    private FileAgentSkill? ParseSkillFile(string skillDirectoryPath)
+    {
+        string skillFilePath = Path.Combine(skillDirectoryPath, SkillFileName);
+
+        string content = File.ReadAllText(skillFilePath, Encoding.UTF8);
+
+        if (!this.TryParseSkillDocument(content, skillFilePath, out SkillFrontmatter frontmatter, out string body))
+        {
+            return null;
+        }
+
+        List<string> resourceNames = ExtractResourcePaths(body);
+
+        if (!this.ValidateResources(skillDirectoryPath, resourceNames, frontmatter.Name))
+        {
+            return null;
+        }
+
+        return new FileAgentSkill(
+            frontmatter: frontmatter,
+            body: body,
+            sourcePath: skillDirectoryPath,
+            resourceNames: resourceNames);
+    }
+
+    private bool TryParseSkillDocument(string content, string skillFilePath, out SkillFrontmatter frontmatter, out string body)
+    {
+        frontmatter = null!;
+        body = null!;
+
+        Match match = s_frontmatterRegex.Match(content);
+        if (!match.Success)
+        {
+            LogInvalidFrontmatter(this._logger, skillFilePath);
+            return false;
+        }
+
+        string? name = null;
+        string? description = null;
+
+        string yamlContent = match.Groups[1].Value.Trim();
+
+        foreach (Match kvMatch in s_yamlKeyValueRegex.Matches(yamlContent))
+        {
+            string key = kvMatch.Groups[1].Value;
+            string value = kvMatch.Groups[2].Success ? kvMatch.Groups[2].Value : kvMatch.Groups[3].Value;
+
+            if (string.Equals(key, "name", StringComparison.OrdinalIgnoreCase))
+            {
+                name = value;
+            }
+            else if (string.Equals(key, "description", StringComparison.OrdinalIgnoreCase))
+            {
+                description = value;
+            }
+        }
+
+        if (string.IsNullOrWhiteSpace(name))
+        {
+            LogMissingFrontmatterField(this._logger, skillFilePath, "name");
+            return false;
+        }
+
+        if (name.Length > MaxNameLength || !s_validNameRegex.IsMatch(name))
+        {
+            LogInvalidFieldValue(this._logger, skillFilePath, "name", $"Must be {MaxNameLength} characters or fewer, using only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen.");
+            return false;
+        }
+
+        if (string.IsNullOrWhiteSpace(description))
+        {
+            LogMissingFrontmatterField(this._logger, skillFilePath, "description");
+            return false;
+        }
+
+        if (description.Length > MaxDescriptionLength)
+        {
+            LogInvalidFieldValue(this._logger, skillFilePath, "description", $"Must be {MaxDescriptionLength} characters or fewer.");
+            return false;
+        }
+
+        frontmatter = new SkillFrontmatter(name, description);
+        body = content.Substring(match.Index + match.Length).TrimStart();
+
+        return true;
+    }
+
+    private bool ValidateResources(string skillDirectoryPath, List<string> resourceNames, string skillName)
+    {
+        string normalizedSkillPath = Path.GetFullPath(skillDirectoryPath) + Path.DirectorySeparatorChar;
+
+        foreach (string resourceName in resourceNames)
+        {
+            string fullPath = Path.GetFullPath(Path.Combine(skillDirectoryPath, resourceName));
+
+            if (!IsPathWithinDirectory(fullPath, normalizedSkillPath))
+            {
+                LogResourcePathTraversal(this._logger, skillName, resourceName);
+                return false;
+            }
+
+            if (!File.Exists(fullPath))
+            {
+                LogMissingResource(this._logger, skillName, resourceName);
+                return false;
+            }
+
+            if (HasSymlinkInPath(fullPath, normalizedSkillPath))
+            {
+                LogResourceSymlinkEscape(this._logger, skillName, resourceName);
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /// <summary>
+    /// Checks that <paramref name="fullPath"/> is under <paramref name="normalizedDirectoryPath"/>,
+    /// guarding against path traversal attacks.
+    /// </summary>
+    private static bool IsPathWithinDirectory(string fullPath, string normalizedDirectoryPath)
+    {
+        return fullPath.StartsWith(normalizedDirectoryPath, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Checks whether any segment in <paramref name="fullPath"/> (relative to
+    /// <paramref name="normalizedDirectoryPath"/>) is a symlink (reparse point).
+    /// Uses <see cref="FileAttributes.ReparsePoint"/> which is available on all target frameworks.
+    /// </summary>
+    private static bool HasSymlinkInPath(string fullPath, string normalizedDirectoryPath)
+    {
+        string relativePath = fullPath.Substring(normalizedDirectoryPath.Length);
+        string[] segments = relativePath.Split(
+            new[] { Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar },
+            StringSplitOptions.RemoveEmptyEntries);
+
+        string currentPath = normalizedDirectoryPath.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+
+        foreach (string segment in segments)
+        {
+            currentPath = Path.Combine(currentPath, segment);
+
+            if ((File.GetAttributes(currentPath) & FileAttributes.ReparsePoint) != 0)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static List<string> ExtractResourcePaths(string content)
+    {
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var paths = new List<string>();
+        foreach (Match m in s_resourceLinkRegex.Matches(content))
+        {
+            string path = NormalizeResourcePath(m.Groups[1].Value);
+            if (seen.Add(path))
+            {
+                paths.Add(path);
+            }
+        }
+
+        return paths;
+    }
+
+    /// <summary>
+    /// Normalizes a relative resource path by trimming a leading <c>./</c> prefix and replacing
+    /// backslashes with forward slashes so that <c>./refs/doc.md</c> and <c>refs/doc.md</c> are
+    /// treated as the same resource.
+    /// </summary>
+    private static string NormalizeResourcePath(string path)
+    {
+        if (path.IndexOf('\\') >= 0)
+        {
+            path = path.Replace('\\', '/');
+        }
+
+        if (path.StartsWith("./", StringComparison.Ordinal))
+        {
+            path = path.Substring(2);
+        }
+
+        return path;
+    }
+
+    [LoggerMessage(LogLevel.Information, "Discovered {Count} potential skills")]
+    private static partial void LogSkillsDiscovered(ILogger logger, int count);
+
+    [LoggerMessage(LogLevel.Information, "Loaded skill: {SkillName}")]
+    private static partial void LogSkillLoaded(ILogger logger, string skillName);
+
+    [LoggerMessage(LogLevel.Information, "Successfully loaded {Count} skills")]
+    private static partial void LogSkillsLoadedTotal(ILogger logger, int count);
+
+    [LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}' does not contain valid YAML frontmatter delimited by '---'")]
+    private static partial void LogInvalidFrontmatter(ILogger logger, string skillFilePath);
+
+    [LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}' is missing a '{FieldName}' field in frontmatter")]
+    private static partial void LogMissingFrontmatterField(ILogger logger, string skillFilePath, string fieldName);
+
+    [LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}' has an invalid '{FieldName}' value: {Reason}")]
+    private static partial void LogInvalidFieldValue(ILogger logger, string skillFilePath, string fieldName, string reason);
+
+    [LoggerMessage(LogLevel.Warning, "Excluding skill '{SkillName}': referenced resource '{ResourceName}' does not exist")]
+    private static partial void LogMissingResource(ILogger logger, string skillName, string resourceName);
+
+    [LoggerMessage(LogLevel.Warning, "Excluding skill '{SkillName}': resource '{ResourceName}' references a path outside the skill directory")]
+    private static partial void LogResourcePathTraversal(ILogger logger, string skillName, string resourceName);
+
+    [LoggerMessage(LogLevel.Warning, "Duplicate skill name '{SkillName}': skill from '{NewPath}' skipped in favor of existing skill from '{ExistingPath}'")]
+    private static partial void LogDuplicateSkillName(ILogger logger, string skillName, string newPath, string existingPath);
+
+    [LoggerMessage(LogLevel.Warning, "Excluding skill '{SkillName}': resource '{ResourceName}' is a symlink that resolves outside the skill directory")]
+    private static partial void LogResourceSymlinkEscape(ILogger logger, string skillName, string resourceName);
+
+    [LoggerMessage(LogLevel.Information, "Reading resource '{FileName}' from skill '{SkillName}'")]
+    private static partial void LogResourceReading(ILogger logger, string fileName, string skillName);
+}
@@ -0,0 +1,213 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Security;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that discovers and exposes Agent Skills from filesystem directories.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This provider implements the progressive disclosure pattern from the
+/// <see href="https://agentskills.io/">Agent Skills specification</see>:
+/// </para>
+/// <list type="number">
+/// <item><description><strong>Advertise</strong> — skill names and descriptions are injected into the system prompt (~100 tokens per skill).</description></item>
+/// <item><description><strong>Load</strong> — the full SKILL.md body is returned via the <c>load_skill</c> tool.</description></item>
+/// <item><description><strong>Read resources</strong> — supplementary files are read from disk on demand via the <c>read_skill_resource</c> tool.</description></item>
+/// </list>
+/// <para>
+/// Skills are discovered by searching the configured directories for <c>SKILL.md</c> files.
+/// Referenced resources are validated at initialization; invalid skills are excluded and logged.
+/// </para>
+/// <para>
+/// <strong>Security:</strong> this provider only reads static content. Skill metadata is XML-escaped
+/// before prompt embedding, and resource reads are guarded against path traversal and symlink escape.
+/// Only use skills from trusted sources.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed partial class FileAgentSkillsProvider : AIContextProvider
+{
+    private const string DefaultSkillsInstructionPrompt =
+        """
+        You have access to skills containing domain-specific knowledge and capabilities.
+        Each skill provides specialized instructions, reference documents, and assets for specific tasks.
+
+        <available_skills>
+        {0}
+        </available_skills>
+
+        When a task aligns with a skill's domain:
+        1. Use `load_skill` to retrieve the skill's instructions
+        2. Follow the provided guidance
+        3. Use `read_skill_resource` to read any references or other files mentioned by the skill
+
+        Only load what is needed, when it is needed.
+        """;
+
+    private readonly Dictionary<string, FileAgentSkill> _skills;
+    private readonly ILogger<FileAgentSkillsProvider> _logger;
+    private readonly FileAgentSkillLoader _loader;
+    private readonly AITool[] _tools;
+    private readonly string? _skillsInstructionPrompt;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAgentSkillsProvider"/> class that searches a single directory for skills.
+    /// </summary>
+    /// <param name="skillPath">Path to an individual skill folder (containing a SKILL.md file) or a parent folder with skill subdirectories.</param>
+    /// <param name="options">Optional configuration for prompt customization.</param>
+    /// <param name="loggerFactory">Optional logger factory.</param>
+    public FileAgentSkillsProvider(string skillPath, FileAgentSkillsProviderOptions? options = null, ILoggerFactory? loggerFactory = null)
+        : this([skillPath], options, loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAgentSkillsProvider"/> class that searches multiple directories for skills.
+    /// </summary>
+    /// <param name="skillPaths">Paths to search. Each can be an individual skill folder or a parent folder with skill subdirectories.</param>
+    /// <param name="options">Optional configuration for prompt customization.</param>
+    /// <param name="loggerFactory">Optional logger factory.</param>
+    public FileAgentSkillsProvider(IEnumerable<string> skillPaths, FileAgentSkillsProviderOptions? options = null, ILoggerFactory? loggerFactory = null)
+    {
+        _ = Throw.IfNull(skillPaths);
+
+        this._logger = (loggerFactory ?? NullLoggerFactory.Instance).CreateLogger<FileAgentSkillsProvider>();
+
+        this._loader = new FileAgentSkillLoader(this._logger);
+        this._skills = this._loader.DiscoverAndLoadSkills(skillPaths);
+
+        this._skillsInstructionPrompt = BuildSkillsInstructionPrompt(options, this._skills);
+
+        this._tools =
+        [
+            AIFunctionFactory.Create(
+                this.LoadSkill,
+                name: "load_skill",
+                description: "Loads the full instructions for a specific skill."),
+            AIFunctionFactory.Create(
+                this.ReadSkillResourceAsync,
+                name: "read_skill_resource",
+                description: "Reads a file associated with a skill, such as references or assets."),
+        ];
+    }
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        if (this._skills.Count == 0)
+        {
+            return base.ProvideAIContextAsync(context, cancellationToken);
+        }
+
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._skillsInstructionPrompt,
+            Tools = this._tools
+        });
+    }
+
+    private string LoadSkill(string skillName)
+    {
+        if (string.IsNullOrWhiteSpace(skillName))
+        {
+            return "Error: Skill name cannot be empty.";
+        }
+
+        if (!this._skills.TryGetValue(skillName, out FileAgentSkill? skill))
+        {
+            return $"Error: Skill '{skillName}' not found.";
+        }
+
+        LogSkillLoading(this._logger, skillName);
+
+        return skill.Body;
+    }
+
+    private async Task<string> ReadSkillResourceAsync(string skillName, string resourceName, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(skillName))
+        {
+            return "Error: Skill name cannot be empty.";
+        }
+
+        if (string.IsNullOrWhiteSpace(resourceName))
+        {
+            return "Error: Resource name cannot be empty.";
+        }
+
+        if (!this._skills.TryGetValue(skillName, out FileAgentSkill? skill))
+        {
+            return $"Error: Skill '{skillName}' not found.";
+        }
+
+        try
+        {
+            return await this._loader.ReadSkillResourceAsync(skill, resourceName, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            LogResourceReadError(this._logger, skillName, resourceName, ex);
+            return $"Error: Failed to read resource '{resourceName}' from skill '{skillName}'.";
+        }
+    }
+
+    private static string? BuildSkillsInstructionPrompt(FileAgentSkillsProviderOptions? options, Dictionary<string, FileAgentSkill> skills)
+    {
+        string promptTemplate = DefaultSkillsInstructionPrompt;
+
+        if (options?.SkillsInstructionPrompt is { } optionsInstructions)
+        {
+            try
+            {
+                promptTemplate = string.Format(optionsInstructions, string.Empty);
+            }
+            catch (FormatException ex)
+            {
+                throw new ArgumentException(
+                    "The provided SkillsInstructionPrompt is not a valid format string. It must contain a '{0}' placeholder and escape any literal '{' or '}' by doubling them ('{{' or '}}').",
+                    nameof(options),
+                    ex);
+            }
+        }
+
+        if (skills.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+
+        // Order by name for deterministic prompt output across process restarts
+        // (Dictionary enumeration order is not guaranteed and varies with hash randomization).
+        foreach (var skill in skills.Values.OrderBy(s => s.Frontmatter.Name, StringComparer.Ordinal))
+        {
+            sb.AppendLine("  <skill>");
+            sb.AppendLine($"    <name>{SecurityElement.Escape(skill.Frontmatter.Name)}</name>");
+            sb.AppendLine($"    <description>{SecurityElement.Escape(skill.Frontmatter.Description)}</description>");
+            sb.AppendLine("  </skill>");
+        }
+
+        return string.Format(promptTemplate, sb.ToString().TrimEnd());
+    }
+
+    [LoggerMessage(LogLevel.Information, "Loading skill: {SkillName}")]
+    private static partial void LogSkillLoading(ILogger logger, string skillName);
+
+    [LoggerMessage(LogLevel.Error, "Failed to read resource '{ResourceName}' from skill '{SkillName}'")]
+    private static partial void LogResourceReadError(ILogger logger, string skillName, string resourceName, Exception exception);
+}
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Configuration options for <see cref="FileAgentSkillsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAgentSkillsProviderOptions
+{
+    /// <summary>
+    /// Gets or sets a custom system prompt template for advertising skills.
+    /// Use <c>{0}</c> as the placeholder for the generated skills list.
+    /// When <see langword="null"/>, a default template is used.
+    /// </summary>
+    public string? SkillsInstructionPrompt { get; set; }
+}
@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Parsed YAML frontmatter from a SKILL.md file, containing the skill's name and description.
+/// </summary>
+internal sealed class SkillFrontmatter
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SkillFrontmatter"/> class.
+    /// </summary>
+    /// <param name="name">Skill name.</param>
+    /// <param name="description">Skill description.</param>
+    public SkillFrontmatter(string name, string description)
+    {
+        this.Name = Throw.IfNullOrWhitespace(name);
+        this.Description = Throw.IfNullOrWhitespace(description);
+    }
+
+    /// <summary>
+    /// Gets the skill name. Lowercase letters, numbers, and hyphens only.
+    /// </summary>
+    public string Name { get; }
+
+    /// <summary>
+    /// Gets the skill description. Used for discovery in the system prompt.
+    /// </summary>
+    public string Description { get; }
+}