[dotnet-port-api] Port skills source context from .NET

[Michelle Clayton (michelle-clayton-work)]

Summary

Port the .NET skills-source context change from microsoft/agent-framework#6797 so Go skill sources and provider-level filters can receive invocation-aware context.

This updates the public agent/skills source API to pass a new skills.SourceContext containing the current agent and session, threads that context through skills.NewContextProvider, and adds CacheIsolationKeySelector so cached skill discovery can be isolated per context when needed while preserving the existing shared-cache default. File-based sources were updated to the new signature, the affected skills tests were updated, and the feature comparison doc now reflects the new invocation-aware skills support.

Upstream commit: microsoft/agent-framework@09fbccf

Ported .NET PRs

• .NET: Add AgentSkillsSourceContext to AgentSkillsSource.GetSkillsAsync agent-framework#6797 - add invocation-aware skills source context and context-aware cache/filter plumbing.

Breaking Changes

Yes.

Old behavior/API:

• skills.Source and skills.SourceFunc exposed Skills(context.Context) ([]*skills.Skill, error).
• skills.ContextProviderOptions.SkillFilter accepted func(*skills.Skill) bool.
• Skills provider caching was always shared across invocations unless disabled entirely.

New behavior/API:

• skills.Source and skills.SourceFunc now expose Skills(context.Context, skills.SourceContext) ([]*skills.Skill, error).
• skills.ContextProviderOptions.SkillFilter now accepts func(*skills.Skill, skills.SourceContext) bool.
• skills.ContextProviderOptions.CacheIsolationKeySelector can opt specific invocations into isolated cache buckets while keeping the default shared-cache behavior.

This breaking change is acceptable for the beta Go SDK because it directly aligns the public skills extension surface with upstream .NET and enables context-aware skill discovery/filtering without redesigning the broader agent lifecycle.

Tests and Examples

• Ran go test ./agent/skills/....
• Ran go test ./....
• Added provider coverage for source-context propagation and cache-isolation behavior.
• Updated existing in-memory and file-based skills tests for the new source method signature.
• No examples changed; this port updates the underlying public skills extension API rather than an end-user scenario.

Notes

• File-based fsskills.Source accepts the new skills.SourceContext but currently ignores it, preserving existing discovery behavior while matching the new public interface.
• Other nearby skills-related upstream changes were intentionally skipped for separate, narrower PRs, including .NET: Add skill approval options agent-framework#6843 and the broader Make skills source classes public with Experimental attribute agent-framework#6838 surface.
• The comparison doc remains Partial because Go still lacks the class-based/DI-backed skills support present in .NET.

Generated by .NET to Go API Porting Agent · 1.3K AIC · ⌖ 42.8 AIC · ⊞ 21.7K · ◷

Closes #440

[Copilot]

🟡 Changes recommended

The provider cache wait path can call buildContext while holding the provider mutex, which can unnecessarily block concurrent invocations and should be refactored.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Ports the upstream .NET “invocation-aware skills source context” change into the Go SDK so skills sources, provider-level filters, and caching can be aware of the invoking agent/session and optionally isolate caches per invocation context.

Changes:

• Introduces skills.SourceContext and updates skills.Source / skills.SourceFunc to accept it.
• Threads SourceContext through skills.NewContextProvider, updates SkillFilter signature, and adds CacheIsolationKeySelector for per-context cache buckets (default remains shared).
• Updates file-based skills source signature, adjusts/extends skills provider tests, and refreshes the feature comparison doc entry.

File summaries

File	Description
agent/skills/skills.go	Adds SourceContext and updates the public source interface/function adapter to accept invocation context.
agent/skills/provider.go	Threads source context into loading/filtering and adds optional cache isolation with per-key caching state.
agent/skills/provider_test.go	Adds coverage for source-context propagation and cache-isolation behavior; updates filter signature usage.
agent/skills/fsskills/source.go	Updates file-based source to accept SourceContext (currently unused).
agent/skills/fsskills/source_test.go	Updates tests to call Skills(ctx, skills.SourceContext{}).
agent/skills/fsskills/source_script_test.go	Updates script-related source tests to use the new source signature.
agent/skills/frontmatter_source_test.go	Updates in-memory/frontmatter source test invocation for new signature.
docs/dotnet-go-sdk-feature-comparison.md	Updates the Skills row to reflect invocation-aware source/filter/caching context support.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Michelle Clayton (michelle-clayton-work)]

Copilot resolve merge conflicts and address PR feedback

[Copilot]

Copilot resolve merge conflicts and address PR feedback

Resolved the merge conflicts and addressed the provider cache feedback in b0cdbea by ensuring cache waiters retry outside the provider mutex. Also merged main in d680729; final validation passed after 9c920f6.

[Michelle Clayton (michelle-clayton-work)]

Copilot resolve merge conflicts

[Copilot]

Copilot resolve merge conflicts

Resolved the merge conflict by merging main and preserving the PR’s skills source-context comparison wording in 9d2438c. Targeted skills tests and final validation passed.

[github-actions]

Scope: public API

Changed Go contract: agent/skills — Source.Skills/SourceFunc gained a SourceContext parameter, ContextProviderOptions.SkillFilter signature changed to func(*Skill, SourceContext) bool, and a new ContextProviderOptions.CacheIsolationKeySelector func(SourceContext) (key string, ok bool) field was added alongside the new exported SourceContext{Agent, Session} type. fsskills.Source.Skills was updated to the new signature (ignoring the new parameter, as documented).

Upstream evidence reviewed: microsoft/agent-framework@09fbccf (port of microsoft/agent-framework#6797) — dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsSourceContext.cs (AgentSkillsSourceContext(AIAgent agent, AgentSession? session)), dotnet/src/Microsoft.Agents.AI/Skills/Decorators/FilteringAgentSkillsSource.cs (Func<AgentSkill, AgentSkillsSourceContext, bool> predicate), dotnet/src/Microsoft.Agents.AI/Skills/Decorators/CachingAgentSkillsSourceOptions.cs (Func<AgentSkillsSourceContext, string?> CacheIsolationKeySelector, null/null-return ⇒ shared cache bucket), dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs (ProvideAIContextAsync builds new AgentSkillsSourceContext(context.Agent, context.Session)).

Result: aligned. The Go port preserves upstream semantics: SourceContext{Agent, Session} mirrors AgentSkillsSourceContext; the filter predicate gains the same context parameter; CacheIsolationKeySelector defaults to the shared cache bucket when nil or when it reports ok=false, matching .NET's "null selector or null key ⇒ shared bucket" default (Go's (string, bool) return is an idiomatic, equivalent way to unambiguously support an empty-string isolation key, where .NET relies on a nullable string). The Go single-flight/cache locking implementation differs mechanically (mutex + maps vs. ConcurrentDictionary<string, Task>) but preserves the same shared-once/isolated-per-key contract. fsskills.Source intentionally ignoring the new context parameter matches AgentFileSkillsSource's lack of context-based behavior upstream. Local build (go build ./...) and go test ./agent/skills/... pass on the PR branch. The feature-comparison doc update is accurate and appropriately keeps the "Partial" classification since class-based/DI-backed skills remain unported.

Since this PR changes exported Go APIs (Source, SourceFunc, ContextProviderOptions.SkillFilter, new SourceContext, new CacheIsolationKeySelector), the public-api-change label is added for maintainer public-API review, and parity-approved is applied since the port faithfully preserves .NET semantics and defaults.

Generated by Go API Consistency Review Agent for #1048 · copilot · auto · 82.8 AIC · ⌖ 5.89 AIC · ⊞ 9.6K · ◷

[Quim Muntal (qmuntal)]

Closing, AgentSkillsSourceContext is still experimental.