[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.

[github-actions]

Scope: public API, user-visible behavior

Changed Go contract: agent/skills package — skills.SourceContext (new, exported struct with Agent *agent.Agent, Session *agent.Session); skills.Source.Skills / skills.SourceFunc signature changed from Skills(context.Context) to Skills(context.Context, SourceContext); ContextProviderOptions.SkillFilter changed from func(*Skill) bool to func(*Skill, SourceContext) bool; new ContextProviderOptions.CacheIsolationKeySelector func(SourceContext) (key string, ok bool); provider cache/loading state changed from single-slot to per-key map keyed by a shared sentinel bucket (sharedSkillsCacheKey) or an isolated key.

Upstream evidence reviewed: microsoft/agent-framework@09fbccfb20cb77da10b3489d9a16627dc4b62044 (.NET PR microsoft/agent-framework#6797):

• dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsSourceContext.cs (new AgentSkillsSourceContext(AIAgent Agent, AgentSession? Session)) ↔ Go skills.SourceContext{Agent, Session} — matches shape.
• dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsSource.cs (GetSkillsAsync(AgentSkillsSourceContext, CancellationToken)) ↔ Go Source.Skills(context.Context, SourceContext) — matches.
• dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs (builds new AgentSkillsSourceContext(context.Agent, context.Session) from InvokingContext) ↔ Go sourceContextForInvocation builds SourceContext from agent.AgentFromContext(ctx) and agent.GetOption(options, agent.WithSession) — matches.
• dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProviderBuilder.cs (UseFilter(Func<AgentSkill, AgentSkillsSourceContext, bool>)) ↔ Go SkillFilter func(*Skill, SourceContext) bool — matches (two-arg predicate, same as the upstream's final design after dropping the bundled filter-context type).
• dotnet/src/Microsoft.Agents.AI/Skills/Decorators/CachingAgentSkillsSourceOptions.cs (CacheIsolationKeySelector, null/no-match falls back to a dedicated shared-bucket sentinel key so an isolation selector returning "" still gets its own bucket) ↔ Go CacheIsolationKeySelector + sharedSkillsCacheKey sentinel and "isolated:" + key prefixing to keep isolated buckets distinct from the shared sentinel — matches the same cardinality/sentinel-key design intent.
• dotnet/.../Decorators/CachingAgentSkillsSource.cs (per-key ConcurrentDictionary cache/in-flight tracking) ↔ Go providerState.cached map[string]*providerContext / loading map[string]chan struct{} — same per-key caching and de-duplication-of-concurrent-loads strategy, adapted to Go's mutex+channel concurrency idiom instead of .NET's TaskCompletionSource/ConcurrentDictionary.

Result: aligned. This is a faithful, semantically equivalent port of the linked upstream .NET change. The breaking change to skills.Source/SourceFunc/SkillFilter signatures is intentional and mirrors the equivalent breaking change upstream made to AgentSkillsSource.GetSkillsAsync and FilteringAgentSkillsSource's predicate; it is acceptable given the Go SDK's beta status, as stated in the PR description. fsskills.Source.Skills correctly accepts but ignores the new SourceContext, matching the file-based source's lack of context-dependent behavior upstream. No divergence found in enablement, defaults, or observable caching/filtering behavior.

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