Restructure agent skills to use multi-source architecture

[Quim Muntal (qmuntal)]

Port of microsoft/agent-framework#4871

Fixes https://github.com/microsoft/go-lab/issues/269

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Restructures the skills subsystem to support a multi-source architecture (in-memory + external sources) and introduces first-class script discovery/execution wiring, aligning with the referenced upstream port.

Changes:

• Replaces the legacy filesystem-only skills provider with a new NewContextProvider built around composable Source implementations.
• Adds fsskills.Source for file-based discovery of skills, resources, and scripts (with configurable directories/extensions and optional script runners).
• Updates/expands tests and refreshes skills examples to demonstrate file-based, code-defined, and mixed skills composition.

Show a summary per file

File	Description
memory/skills/skills_test.go	Updates tests to use the new provider + file source options; adjusts expectations around tool exposure and exact-name behaviors.
memory/skills/skills.go	Refactors core type definitions (Frontmatter/Skill/Resource/Script) and validation utilities to support the new provider model.
memory/skills/provider_test.go	Adds coverage for new provider behaviors: caching, deduplication, template validation, scripts, approval, and multi-source aggregation.
memory/skills/provider.go	Introduces the new multi-source NewContextProvider implementation, prompt templating, tool wiring, caching, and deduplication logic.
memory/skills/loader.go	Removes the old filesystem loader/provider implementation in favor of the new source/provider architecture.
memory/skills/fsskills/source.go	Adds file-based Source for discovering skills/resources/scripts from one or more fs.FS roots with normalization and filtering.
memory/skills/fsskills/source_test.go	Adds tests for file-based skill discovery, frontmatter parsing (incl. metadata), and resource directory normalization.
memory/skills/fsskills/source_script_test.go	Adds tests for script discovery, allowed extensions, runner behavior, directories, and error cases.
memory/skills/frontmatter_source_test.go	Adds validation tests for Frontmatter and in-memory source behavior.
examples/skills/01_basic_skills/main.go	Removes the old basic skills example entrypoint (superseded by new examples structure).
examples/skills/01_basic_skills/skills/expense-report/SKILL.md	Removes legacy example skill content (part of examples restructure).
examples/skills/01_basic_skills/skills/expense-report/references/POLICY_FAQ.md	Removes legacy example resource file (part of examples restructure).
examples/skills/01_basic_skills/skills/expense-report/assets/expense-report-template.md	Removes legacy example asset file (part of examples restructure).
examples/02-agents/skills/step01_file_based_skills/main.go	Adds a new example showing file-based skills with explicit source composition and script runner integration.
examples/02-agents/skills/step01_file_based_skills/skills/unit-converter/SKILL.md	Adds a file-based unit converter skill for the new examples.
examples/02-agents/skills/step01_file_based_skills/skills/unit-converter/references/conversion-table.md	Adds a resource file used by the file-based unit converter skill.
examples/02-agents/skills/step01_file_based_skills/skills/unit-converter/scripts/convert.py	Adds a script used by the file-based unit converter skill.
examples/02-agents/skills/step02_code_defined_skills/main.go	Adds a code-defined skills example demonstrating programmatic skills/resources/scripts.
examples/02-agents/skills/step03_mixed_skills/main.go	Adds a mixed-skills example combining in-memory skills with a file-based source.
examples/02-agents/skills/step03_mixed_skills/skills/unit-converter/SKILL.md	Adds an additional file-based skill used by the mixed-skills example.
examples/02-agents/skills/step03_mixed_skills/skills/unit-converter/references/conversion-table.md	Adds resource content for the mixed-skills file-based unit converter skill.
examples/02-agents/skills/step03_mixed_skills/skills/unit-converter/scripts/convert.py	Adds script content for the mixed-skills file-based unit converter skill.
examples/02-agents/skills/internal/skillhelpers/subprocess_script_runner.go	Adds a sample script runner that materializes a file-backed skill and executes scripts via subprocess.
examples/02-agents/skills/internal/skillhelpers/inline.go	Adds helper utilities for parsing arguments and shaping conversion results in examples.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 24/24 changed files
• Comments generated: 5

[github-actions]

Generated by Go API Consistency Review Agent for issue #104 · ● 1.8M

[github-actions]

Cross-repo parity review — PR #104: Restructure agent skills to use multi-source architecture

This PR is a port of microsoft/agent-framework#4871 and the Go implementation is closely aligned with the upstream .NET skills subsystem in dotnet/src/Microsoft.Agents.AI/Skills/. Core concepts, validation rules, tool names (load_skill, read_skill_resource, run_skill_script), default directory/extension sets, deduplication semantics, caching, script-approval flag, and prompt-template placeholders all match the .NET reference.

Two minor parity observations

1. DisableSourceDeduplication in ContextProviderOptions — Go-only option

Go's ContextProviderOptions adds a DisableSourceDeduplication bool field that has no counterpart in .NET's AgentSkillsProviderOptions. In .NET, deduplication is always applied by the DeduplicatingAgentSkillsSource wrapper that every public constructor and the builder insert unconditionally. The Go default (false = dedup on) preserves the same runtime behavior, so existing callers are unaffected, but the option exposes a "turn off dedup" knob that doesn't exist in .NET. This isn't a behavioral regression, but worth tracking in case .NET later adds the same escape hatch — the option shape and semantics should stay in sync.

Upstream surface to watch: dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProviderOptions.cs and the DeduplicatingAgentSkillsSource decorator.

2. Code-defined skill Content — raw text vs. synthesized XML

In .NET, AgentInlineSkill.Content is built by AgentInlineSkillContentBuilder, which produces a structured XML document that embeds name, description, instructions, and enumerates the skill's resources and scripts. When the model calls load_skill, it receives this self-describing XML so it can discover which resources/scripts are available from the loaded body.

In the Go example (step02_code_defined_skills) and the skills.Skill struct design, Content is set to raw instruction text with no resource/script enumeration. When load_skill returns, the model sees only the instructions — it must rely on the system-prompt preamble and the tool descriptions to know what to call next.

This is not necessarily wrong (the Go design is simpler and the system-prompt approach is valid), but it represents a behavioral difference in what the model sees after calling load_skill for a code-defined skill. The upstream .NET AgentInlineSkillContentBuilder at dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs is the relevant reference if Go ever adds a helper to synthesize structured content for code-defined skills.

Sample coverage

.NET step	Go step	Notes
Step01: File-based skills	step01	✅ aligned
Step02: Code-defined (AgentInlineSkill)	step02	✅ aligned (raw-text Content difference noted above)
Step03: Class-based (AgentClassSkill<T>)	—	intentionally absent; Go has no attribute-reflection equivalent
Step04: Mixed skills	step03	✅ aligned (renumbered due to absent class-based step)
Step05: Skills with DI	—	intentionally absent; .NET-specific DI integration

Everything else reviewed — Frontmatter.Validate(), Source interface, fsskills.Source, ScriptRunner, NewInMemorySource, SourceOptions / AgentFileSkillsSourceOptions, and the functool changes — is semantically equivalent to the upstream .NET implementation.

Generated by Go API Consistency Review Agent for issue #104 · ● 1.6M · ◷