.NET: Add 'advertise' frontmatter option to control automatic skill advertisement

[ron-clover]

Motivation & Context

AgentSkillsProvider unconditionally lists every skill's name and description in the <available_skills> block of the system prompt. There is no way for a skill author to decide that a skill should not be auto-introduced to the model: the only existing mechanism, skill filtering (FilteringAgentSkillsSource), removes the skill entirely so it can no longer be loaded at all.

This change lets a skill opt out of automatic advertisement while remaining fully functional, which is useful for keeping the system prompt small with large skill sets, and for skills that should only be used when referenced explicitly (e.g. from the agent's instructions or from another skill).

Description & Review Guide

A new boolean advertise frontmatter property, defaulting to true for full backward compatibility:

---
name: temperature-converter
description: Convert between Celsius and Fahrenheit temperatures.
advertise: false
---

• What are the major changes?
  • AgentSkillFrontmatter: new Advertise property (get/set, default true), so code-defined skills (AgentInlineSkill, AgentClassSkill) can set it via their Frontmatter as well.
  • AgentFileSkillsSource: parses the advertise frontmatter key; anything other than an explicit boolean false keeps the default of true.
  • AgentSkillsProvider.BuildSkillsInstructions: skips skills with Advertise = false when generating the <available_skills> listing. The load_skill / read_skill_resource / run_skill_script tools are unchanged, so a non-advertised skill remains loadable by name.
  • Unit tests for parsing (explicit false, explicit true, invalid value, default) and for the provider (non-advertised skill absent from instructions yet still loadable via load_skill).
  • Samples: Agent_Step01_FileBasedSkills gains an unadvertised temperature-converter skill that the agent's own instructions reference explicitly; the AgentSkills READMEs document the option and how it differs from skill filtering.
• What is the impact of these changes?
  • Additive and backward compatible: omitting advertise (or any non-false value) behaves exactly as before. No public API changes beyond the new optional property.
  • The Python SkillFrontmatter does not have this property yet; it could adopt the same advertise field for cross-language parity.
• What do you want reviewers to focus on?
  • Whether advertise is the right name for the property, and whether treating unparseable values as true (rather than rejecting the skill) is the desired behavior.

Related Issue

Fixes #6913

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 title prefix in sync automatically.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-out mechanism for automatic skill advertisement in the .NET Agent Skills system prompt, letting skills remain loadable/usable while being omitted from the <available_skills> listing to reduce prompt size and enable explicit-invocation patterns.

Changes:

• Introduces AgentSkillFrontmatter.Advertise (default true) and parses advertise: from SKILL.md frontmatter (only explicit boolean false disables advertising).
• Updates AgentSkillsProvider.BuildSkillsInstructions to exclude non-advertised skills from the generated skills listing while keeping all skills available via tools (e.g., load_skill).
• Adds unit tests for parsing behavior and provider behavior, plus sample/docs updates demonstrating an unadvertised temperature-converter skill.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs	Adds parsing tests for advertise and asserts default Advertise = true.
dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentSkillsProviderTests.cs	Verifies non-advertised skills are excluded from instructions but still loadable via load_skill.
dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs	Parses advertise frontmatter and maps it to AgentSkillFrontmatter.Advertise.
dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs	Filters out Advertise = false skills when building the <available_skills> instruction listing.
dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillFrontmatter.cs	Adds the Advertise property with documentation and default value.
dotnet/samples/02-agents/AgentSkills/README.md	Documents how advertise: false differs from filtering (keeps skill loadable).
dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/temperature-converter/SKILL.md	Adds a sample unadvertised skill (advertise: false).
dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/README.md	Updates sample documentation to describe unadvertised skill behavior and usage.
dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Program.cs	Updates sample code/instructions to explicitly reference and demonstrate loading the unadvertised skill.

[ron-clover]

@microsoft-github-policy-service agree company="Clover Security"