.NET: Align skill folder discovery with spec by SergeyMenshykh · Pull Request #5078 · microsoft/agent-framework

SergeyMenshykh · 2026-04-03T12:16:11Z

This PR adds support for discovering skill scripts and resources from folders defined in the agent skill specification, with the ability to specify other folders if needed via options.

The filtered solution file is generated dynamically by eng/scripts/New-FilteredSolution.ps1 during CI. Checking it in risks it becoming stale and out-of-sync with the real solution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ent-framework into skill-as-class

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR updates the .NET file-based skill discovery implementation to align script/resource folder scanning with the Agent Skills specification, while allowing callers to override the scanned folders via new options.

Changes:

Added ScriptFolders and ResourceFolders to AgentFileSkillsSourceOptions to control which subfolders are scanned (including support for "." to include skill-root files).
Updated AgentFileSkillsSource to scan only the configured folders (non-recursive within each folder) and added validation/filtering for configured folder values.
Updated and expanded unit tests to reflect spec folder names (scripts/, references/, assets/) and new configuration behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs	Introduces new options for script/resource folder discovery defaults and overrides.
dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs	Implements folder-based scanning and folder name validation/filtering for scripts/resources.
dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs	Updates resource discovery tests for spec folders and adds tests for folder configuration/validation.
dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentFileSkillsSourceScriptTests.cs	Updates script discovery expectations and adds tests for nested/dot-slash script folder configuration.

Copilot · 2026-04-03T12:44:18Z

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs

+            // Reject absolute paths and any path segments that escape upward.
+            if (Path.IsPathRooted(folder) || folder.Contains("..", StringComparison.Ordinal))
+            {
+                LogFolderNameSkippedInvalid(logger, folder);
+                continue;
+            }


FilterValidFolderNames rejects any folder string containing ".." anywhere, which will also skip legitimate relative folders like "my..scripts" even though they don’t escape upward. Consider validating path traversal by splitting into segments and rejecting only segments equal to ".." (and optionally normalizing separators) so valid names aren’t blocked.

Copilot · 2026-04-03T12:44:18Z

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs

+    private static IEnumerable<string> FilterValidFolderNames(IEnumerable<string> folders, ILogger logger)
+    {
+        foreach (string folder in folders)
+        {
+            if (string.IsNullOrWhiteSpace(folder))
+            {
+                throw new ArgumentException("Folder names must not be null or whitespace.", nameof(folders));
+            }
+
+            // "." is valid — it means the skill root directory.
+            if (string.Equals(folder, RootFolderIndicator, StringComparison.Ordinal))
+            {
+                yield return folder;
+                continue;
+            }
+
+            // Reject absolute paths and any path segments that escape upward.
+            if (Path.IsPathRooted(folder) || folder.Contains("..", StringComparison.Ordinal))
+            {
+                LogFolderNameSkippedInvalid(logger, folder);
+                continue;
+            }
+
+            yield return folder;
+        }


Folder values aren’t normalized before Distinct/scanning. If callers pass both "references" and "./references" (or include trailing slashes), the same directory will be scanned multiple times and duplicate resources/scripts with identical names can be produced. Normalize folder strings in FilterValidFolderNames (e.g., trim leading "./"/"." and trailing separators) before storing them.

Copilot · 2026-04-03T12:44:18Z

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs

+        foreach (string folder in this._resourceFolders.Distinct(StringComparer.OrdinalIgnoreCase))
        {
-            string fileName = Path.GetFileName(filePath);
+            string targetDirectory = string.Equals(folder, RootFolderIndicator, StringComparison.Ordinal)
+                ? skillDirectoryFullPath
+                : Path.Combine(skillDirectoryFullPath, folder);

-            // Exclude SKILL.md itself
-            if (string.Equals(fileName, SkillFileName, StringComparison.OrdinalIgnoreCase))
+            if (!Directory.Exists(targetDirectory))
            {
                continue;
            }

-            // Filter by extension
-            string extension = Path.GetExtension(filePath);
-            if (string.IsNullOrEmpty(extension) || !this._allowedResourceExtensions.Contains(extension))
+#if NET
+            var enumerationOptions = new EnumerationOptions
+            {
+                RecurseSubdirectories = false,
+                IgnoreInaccessible = true,
+                AttributesToSkip = FileAttributes.ReparsePoint,
+            };
+
+            foreach (string filePath in Directory.EnumerateFiles(targetDirectory, "*", enumerationOptions))


When targetDirectory itself is a symlink/reparse point (e.g., references/ symlinked outside), the code will still enumerate that external directory and then filter files out via the containment check. That can be abused for unnecessary I/O (DoS) and is avoidable—consider detecting FileAttributes.ReparsePoint on targetDirectory and skipping enumeration of that folder entirely.

Copilot · 2026-04-03T12:44:19Z

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs

+    /// <summary>
+    /// Gets or sets the sub-folder names to scan for script files, relative to the skill directory.
+    /// Use <c>"."</c> to include files directly at the skill root.
+    /// When <see langword="null"/>, defaults to <c>scripts</c> (per the
+    /// <see href="https://agentskills.io/specification">Agent Skills specification</see>).
+    /// When set, replaces the defaults entirely.
+    /// </summary>
+    public IEnumerable<string>? ScriptFolders { get; set; }
+
+    /// <summary>
+    /// Gets or sets the sub-folder names to scan for resource files, relative to the skill directory.
+    /// Use <c>"."</c> to include files directly at the skill root.
+    /// When <see langword="null"/>, defaults to <c>references</c> and <c>assets</c> (per the
+    /// <see href="https://agentskills.io/specification">Agent Skills specification</see>).
+    /// When set, replaces the defaults entirely.
+    /// </summary>


The XML docs say “sub-folder names”, but the implementation/tests accept multi-segment relative paths (e.g., "f1/f2/f3", "./scripts/f1") and "." for the root. Please update the documentation to describe these as relative folder paths (and mention normalization expectations) to avoid misleading API consumers.

SergeyMenshykh and others added 8 commits April 1, 2026 11:51

add class-based skills

3c1288b

Merge branch 'main' into skill-as-class

8b978ec

address formating issues

9093230

Merge branch 'skill-as-class' of https://github.com/SergeyMenshykh/ag…

42cf8fb

…ent-framework into skill-as-class

discover scripts and resource from folders defined in spec

d9158ae

Merge branch 'main' into agent-skills-validation

94755d1

markwallace-microsoft added documentation Improvements or additions to documentation .NET labels Apr 3, 2026

SergeyMenshykh temporarily deployed to integration April 3, 2026 12:16 — with GitHub Actions Inactive

github-actions bot changed the title ~~Discover scripts and resources from folders defined in spec~~ .NET: Discover scripts and resources from folders defined in spec Apr 3, 2026

SergeyMenshykh changed the title ~~.NET: Discover scripts and resources from folders defined in spec~~ .NET: Align skill folder discovery with spec Apr 3, 2026

Remove Step05 and Step06 DI skill samples

caceaff

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

SergeyMenshykh temporarily deployed to integration April 3, 2026 12:35 — with GitHub Actions Inactive

SergeyMenshykh self-assigned this Apr 3, 2026

SergeyMenshykh added this to Agent Framework Apr 3, 2026

SergeyMenshykh moved this to In Review in Agent Framework Apr 3, 2026

SergeyMenshykh marked this pull request as ready for review April 3, 2026 12:40

Copilot AI review requested due to automatic review settings April 3, 2026 12:40

Copilot started reviewing on behalf of SergeyMenshykh April 3, 2026 12:41 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

SergeyMenshykh mentioned this pull request Apr 3, 2026

.NET: Agent skills improvments #5077

Open

3 tasks

lokitoth approved these changes Apr 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.NET: Align skill folder discovery with spec#5078

.NET: Align skill folder discovery with spec#5078
SergeyMenshykh wants to merge 9 commits intomicrosoft:mainfrom
SergeyMenshykh:agent-skills-validation

SergeyMenshykh commented Apr 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

SergeyMenshykh commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SergeyMenshykh commented Apr 3, 2026 •

edited

Loading