Python: [Breaking] Refactor FileSkillsSource for depth-based discovery and predicate filters

[giles17]

Motivation and Context

Ports the refactoring from .NET PR microsoft#6109 to the Python side. The old directory-whitelist approach (resource_directories/script_directories) was rigid — users had to know exact subdirectory names upfront. The new depth-based scanning with optional filter predicates is strictly more flexible and aligns both language implementations.

Description

Refactors FileSkillsSource to replace preconfigured directory whitelists with depth-controlled recursive scanning and user-supplied filter predicates.

Removed:

• resource_directories / script_directories constructor options

Added:

• search_depth option (>= 1, default 2): controls how deep the recursive scan goes within each skill directory. Depth 1 = root only; depth 2 = root + one level of subdirectories.
• script_filter / resource_filter predicate options that receive a FileSkillFilterContext (skill_name + relative_file_path), allowing whitelist/blacklist filtering by file path.
• FileSkillFilterContext class exported from agent_framework.

Preserved:

• All security checks (path containment, symlink detection) using the skill root as the trusted boundary.
• Extension-based filtering (resource_extensions / script_extensions).

Updated:

• SkillsProvider.from_paths() accepts the new parameters.
• Discovery methods refactored from @staticmethod to instance methods.
• Tests rewritten to validate depth-based behavior and filter predicates.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add [BREAKING] prefix to the title of the PR.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_skills.py	1021	40	96%	294, 541, 1007, 1022, 1024–1025, 1381–1382, 1394–1395, 1672, 1701, 2170, 2620–2621, 2718, 2726, 2731, 2734, 2739, 2759, 2771, 2776, 2870, 2878, 2883, 2886, 2891, 2911, 2920, 2925, 3184–3185, 3534, 3761–3762, 3789–3790, 3797–3798
_tools.py	1138	90	92%	222–223, 400, 402, 415, 440–442, 450, 468, 482, 489, 496, 519, 521, 528, 536, 665, 699–701, 704–706, 708, 714, 765–767, 792, 818, 822, 860–862, 866, 888, 1031–1032, 1036, 1072, 1084, 1091–1094, 1115, 1119, 1123, 1137–1139, 1489, 1581, 1609, 1631, 1639, 1730, 1737–1738, 1797, 1801, 1847, 1908–1909, 1956, 1970, 1973, 1986, 1989, 2012, 2019, 2029, 2033, 2112, 2165, 2185, 2187, 2243, 2322, 2519, 2585–2586, 2738, 2743, 2745–2746, 2815, 2820, 2827
TOTAL	39095	4477	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7764	34 💤	0 ❌	0 🔥	2m 5s ⏱️