Giles Odigwe
25ec4c3b5c
* Python: Support archive-type MCP skills in MCPSkillsSource Add `archive`-type skill support to `MCPSkillsSource` so an MCP server can advertise packaged skills (ZIP / TAR / gzip-compressed TAR) that are downloaded, safely unpacked to a local directory, and served like file-based skills, while keeping the guarantee that MCP-delivered scripts are never executed. - Dispatch `skill://index.json` entries by `type`: `skill-md` (existing, fetched on demand) and `archive` (new). Unknown types are skipped. - `_ArchiveEntryLoader` downloads, extracts, and prunes archive skills and delegates discovery to an internal `FileSkillsSource` created with no script extensions and no runner, so bundled scripts surface as read-only resources only. - Hardened stdlib extraction: path-traversal (zip-slip) guard, non-regular TAR member skipping, and file-count / uncompressed-size / download-size limits. - Configure via `archive_*` constructor kwargs (no options object, per Python conventions); use `CachingSkillsSource` for refresh rather than a source level refresh interval. - Fix `FileSkillsSource` to treat `None` extensions as "use defaults" and an empty tuple as "discover none" (an empty tuple previously fell back to defaults). Port of .NET PR #6631. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d * Propagate non-not-found archive download errors in MCPSkillsSource Only swallow "resource not found" MCP errors when downloading an archive resource; re-raise every other error (auth failure, INTERNAL_ERROR, connection drop, timeout) so a transient transport failure is not silently turned into a missing skill. This matches the existing failure model used by `_try_read_index` and `MCPSkill.get_resource`, and avoids a failed `CachingSkillsSource` refresh overwriting a previously cached list with a partial result. Add tests asserting archive-download INTERNAL_ERROR and ConnectionError propagate out of `get_skills`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d * Python: Expose archive skill options on FoundryToolbox and demo in sample - FoundryToolbox.as_skills_provider() now forwards the MCPSkillsSource archive options (archive_skills_directory, archive_resource_extensions, archive_resource_search_depth, archive_max_file_count, archive_max_size_bytes, archive_max_uncompressed_size_bytes). Only explicitly-set options are forwarded so unset ones keep the MCPSkillsSource defaults. This lets a hosted toolbox agent redirect archive extraction to a writable directory (the default is under the cwd, which may be read-only in a container). - Add unit tests covering default (no options forwarded) and override forwarding. - Update the 12_foundry_toolbox_mcp_skills sample to demonstrate all three progressive-disclosure stages with an archive skill: escalation-policy now ships a references/refund-matrix.md resource and is uploaded as a ZIP archive; main.py disables load_skill and read_skill_resource approval and points archive extraction at a temp directory. README, toolbox.yaml, and ignore files updated accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36 * Python: Fix ty type error in toolbox archive-option test Cast provider._source to _FoundryToolboxSkillsSource before accessing the private _archive_options, so the ty checker (which runs over tests) resolves the concrete type instead of the SkillsSource base. Replaces the mypy-style type: ignore that ty did not honor. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36 * Rework archive-type skill support in MCPSkillsSource to unpack archives entirely in memory instead of extracting them to a local directory, and apply reviewer feedback. * Python: Raise on archive member path-traversal (zip-slip) Treat a `..` path-traversal member in an archive skill as a hostile archive and reject the whole skill, matching how the file-count and uncompressed-size limits reject a malformed archive (previously the member was silently skipped while the rest of the skill still loaded). - `_normalize_archive_member_name` now raises `ValueError` on a `..` escape; benign degenerate entries (empty, `.`, `/`) still return None (skipped) and absolute paths are still neutralized to relative. The raise propagates to `_ArchiveEntryLoader._build_skill`, which already skips the skill on error. - Update tests: traversal cases now assert a raise, and add an end-to-end test that a zip-slip archive drops the whole skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d * Python: Revert archive skill demo in toolbox MCP skills sample Restore the 12_foundry_toolbox_mcp_skills sample to its pre-PR, skill-md-only form (matching the .NET Agent_Step26_FoundryToolboxMcpSkills sample, which uses skill-md and no ZIP archive): - Revert main.py, toolbox.yaml, README.md, .azdignore, .dockerignore, and escalation-policy/SKILL.md to the single-file SKILL.md version. - Remove the archive demo files added by this PR (.gitignore and escalation-policy/references/refund-matrix.md). - Soften two README notes so they no longer claim archive skills are unsupported/silently dropped (this PR adds archive support); instead frame single-file SKILL.md as a focus choice and point to the archive_* options. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d * Python: Clarify archive framing in mcp_based_skill sample README The mcp_based_skill sample is a generic MCP consumer that discovers whatever the server advertises; it does not itself demonstrate archive skills. Reword the archive note so it reads as an MCPSkillsSource capability rather than a sample feature, and fix the stale "unpacked to a local directory" claim to "unpacked in memory" (matching the in-memory extraction implementation). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
Agent Skills Samples
These samples demonstrate how to use Agent Skills — modular packages of instructions, resources, and scripts that extend an agent's capabilities. Skills follow the Agent Skills specification and use progressive disclosure to optimize token usage.
Learning Path
Start with file-based or code-defined skills, then explore combining them and adding approval workflows.
| Sample | Description |
|---|---|
| file_based_skill | Define skills as SKILL.md files on disk with reference documents and executable scripts. Uses the unit-converter skill. |
| code_defined_skill | Define skills entirely in Python code using Skill, @skill.resource, and @skill.script decorators. Uses a code-defined unit-converter skill. |
| class_based_skill | Define skills as Python classes using ClassSkill with @ClassSkill.resource and @ClassSkill.script decorators for auto-discovery. Uses a class-based unit-converter skill. |
| mixed_skills | Combine code-defined, class-based, and file-based skills in a single agent. Uses a code-defined volume-converter, a class-based temperature-converter, and a file-based unit-converter. |
| mcp_based_skill | Discover skills served over the Model Context Protocol (MCP) via MCPSkillsSource. Connects to a remote MCP server that exposes skills as skill://... resources following the SEP-2640 convention. |
| script_approval | Require manual human-in-the-loop approval before running skill tools (the default). |
| skills_auto_approval | Configure auto-approval rules with ToolApprovalMiddleware so read-only skill tools are approved automatically while script execution still prompts. |
Key Concepts
Progressive Disclosure
Skills use a three-step interaction model to minimize token usage:
- Advertise — Skill names and descriptions (~100 tokens each) are injected into the system prompt
- Load — Full instructions are loaded on-demand via the
load_skilltool - Access — Resources are read via
read_skill_resource; scripts are executed viarun_skill_script
File-Based vs Code-Defined vs Class-Based Skills
| Aspect | File-Based | Code-Defined | Class-Based |
|---|---|---|---|
| Definition | SKILL.md files on disk |
Skill instances in Python |
Classes extending ClassSkill |
| Resources | Static files in references/ and assets/ directories |
Callable functions via @skill.resource decorator |
@ClassSkill.resource decorator (auto-discovered) |
| Scripts | Python files in scripts/ directory (executed via subprocess) |
Callable functions via @skill.script decorator (executed in-process) |
@ClassSkill.script decorator (executed in-process) |
| Discovery | Automatic via skill_paths parameter |
Explicit via skills parameter |
Explicit via skills parameter |
| Dynamic content | No (static files only) | Yes (functions can generate content at runtime) | Yes (functions can generate content at runtime) |
| Sharing pattern | Copy skill directory | Inline or shared instances | Package in shared libraries/PyPI |
All three types can be combined in a single SkillsProvider — see the mixed_skills sample.
Script Execution
Skills can include executable scripts. How a script runs depends on how it was defined:
| Code-Defined Scripts | File-Based Scripts | |
|---|---|---|
| Defined via | @skill.script decorator |
.py files in scripts/ directory |
| Execution | In-process (direct function call) | Delegated to a script_runner |
script_runner needed? |
No — runs in-process automatically | Yes — required |
The script_runner parameter on SkillsProvider is only applicable to file-based scripts. Code-defined scripts are always executed in-process regardless of this setting. See file_based_skill for an example using a SkillScriptRunner callable with a subprocess runner, and code_defined_skill for in-process scripts that need no runner.
Prerequisites
All samples require:
- A Microsoft Foundry project with a deployed model (e.g.
gpt-4o-mini) - Azure CLI authentication (
az login) - Environment variables set in a
.envfile (seepython/.env.example)
Suppressing the experimental MCP Skills warning
The core Agent Skills APIs are stable. MCP-based skill discovery
(MCPSkillsSource) is still experimental, so the mcp_based_skill
sample includes a short commented warnings.filterwarnings(...) snippet near the
imports. Uncomment it if you want to suppress the MCP Skills warning.