[BREAKING] Python: Align file skill folder discovery with agentskills.io spec#5807
Merged
SergeyMenshykh merged 3 commits intoMay 14, 2026
Conversation
Update FileSkillsSource to scan spec-defined subdirectories instead of recursive rglob for resource and script discovery: - Resources: scan 'references/' and 'assets/' (was: entire skill tree) - Scripts: scan 'scripts/' (was: entire skill tree) - Add resource_directories and script_directories parameters for customization, with '.' root indicator for skill root files - Add directory validation: reject '..' traversal, absolute paths, empty names; normalize separators and deduplicate directories - Non-recursive scanning within each configured directory (top-level only) - Containment check validates files against target directory, not just skill root, for stronger path-traversal defense - Case-insensitive directory deduplication via os.path.normcase() - Cross-platform absolute path rejection in directory validation - Sort discovery results for stable ordering - Update SkillsProvider.from_paths() to pass new parameters through - Update all tests for new subdirectory-scoped discovery behavior Resolves microsoft#5711. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Python Test Coverage Report •
Python Unit Test Overview
|
||||||||||||||||||||||||||||||
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Python FileSkillsSource discovery logic to follow the agentskills.io directory-structure specification, aligning behavior with the .NET implementation.
Changes:
- Switch resource discovery to non-recursive scanning of spec-defined folders (
references/,assets/) and script discovery toscripts/. - Add customizable
resource_directoriesandscript_directoriesoptions (including"."to scan the skill root). - Expand and update test coverage to validate new discovery behavior, ordering, and directory-name validation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
python/packages/core/agent_framework/_skills.py |
Implements directory-based, non-recursive resource/script discovery and adds directory configuration + validation utilities. |
python/packages/core/tests/core/test_skills.py |
Updates existing tests and adds new cases for spec-aligned discovery and directory validation behavior. |
Comments suppressed due to low confidence (1)
python/packages/core/agent_framework/_skills.py:2545
_discover_script_filescalls_has_symlink_in_path(resolved_target, root_directory_path)without checking thatresolved_targetis contained withinroot_directory_path. With an absolute/escapingdirectoriesentry,_has_symlink_in_pathraisesValueErrorand stops discovery. Add a containment guard (or catchValueError) and skip the directory with a warning to keep discovery robust.
# Directory-level symlink check for non-root directories
if not is_root and FileSkillsSource._has_symlink_in_path(resolved_target, root_directory_path):
logger.warning(
"Skipping script directory '%s': symlink detected in path under skill directory '%s'",
directory,
skill_dir_path,
)
continue
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
- Narrow Windows absolute path check to proper drive-root pattern (re.match r'^[A-Za-z]:[/\\]') to avoid rejecting valid POSIX names - Add _is_path_within_directory guard before _has_symlink_in_path in both discovery methods to prevent ValueError on escaped paths Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
TaoChenOSU
approved these changes
May 13, 2026
moonbox3
reviewed
May 14, 2026
Address review comment: _discover_resource_files and _discover_script_files previously swallowed OSError silently when iterdir() failed. Now log a warning so permission errors and transient FS failures are visible instead of making resource/script directories silently disappear. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
SergeyMenshykh
changed the title
SergeyMenshykh
changed the title
SergeyMenshykh
changed the title
moonbox3
approved these changes
May 14, 2026
This was referenced May 14, 2026
Open
This was referenced May 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Context
Port of .NET PR #5078. The agentskills.io specification defines a standard directory structure for skill files. The previous implementation used recursive
rglobscanning of the entire skill directory, which does not align with the spec and could pick up unintended files.Resolves #5711.
Description
Updates
FileSkillsSourceto scan spec-defined subdirectories instead of recursiverglob:references/andassets/; scripts default toscripts/resource_directoriesandscript_directoriesparameters for customization.root indicator for skill root files.., absolute paths, empty names[BREAKING] — Constructor and discovery behavior changed. Skills with resources or scripts outside the configured directories (
references/,assets/,scripts/) will no longer discover those files automatically. Use theresource_directoriesorscript_directoriesparameters to include custom directories, or move files into the standard directories. Acceptable as the Skills API is@experimental.Contribution Checklist