.NET: Clarify Agent Skills caching behavior

[SergeyMenshykh]

Motivation & Context

The Agent Skills builder caches resolved skills by default, but the scope of that cache was not stated consistently where custom sources are registered and providers are built. Clarifying the existing behavior helps callers choose the appropriate caching configuration for context-dependent sources.

Description & Review Guide

• What are the major changes? Expanded the XML documentation for both custom-source overloads, Build(), and CacheIsolationKeySelector to describe the existing shared cache bucket and point to DisableCaching() and cache isolation keys.
• What is the impact of these changes? Documentation only; there are no API or runtime behavior changes.
• What do you want reviewers to focus on? Whether the guidance accurately describes the current builder and caching-options behavior without implying a recommended isolation-key cardinality.

Related Issue

N/A — no public issue is associated with this documentation clarification.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and the title prefix in sync automatically.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the caching implementation and introduces no runtime changes.

Pull request overview

Clarifies the existing default cache scope and isolation requirements for .NET Agent Skills providers.

Changes:

• Documents shared-cache behavior for custom sources and Build().
• Explains when to use isolation keys or disable caching.

File summaries

File	Description
CachingAgentSkillsSourceOptions.cs	Clarifies cache isolation and security-boundary considerations.
AgentSkillsProviderBuilder.cs	Documents default caching across source registration and provider construction.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Balanced

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 4e1fc1beb6c1
Model: gpt-5.6-sol-fast

Overview

The added XML documentation correctly surfaces the builder's default caching, the null-key shared bucket, and the available opt-out and isolation controls. The implementation and tests substantiate default reuse, per-key separation, retries after failures or cancellation, and provider-owned cache disposal. One uncommon but concrete isolation gap remains: the internal shared-bucket sentinel is an ordinary string that a non-null selector can return, so the new security-boundary guidance overstates the isolation guarantee for that value.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI/Skills/Decorators/CachingAgentSkillsSourceOptions.cs