Skip to content

.NET: docs: keep consumer skills focused on development choices - #10185

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 2 commits into
mainfrom
consumer-skill-scope
Nov 9, 2026
Merged

Eduard van Valkenburg (eavanvalkenburg) merged 2 commits into
mainfrom
consumer-skill-scope

Conversation

@eavanvalkenburg

Copy link
Copy Markdown
Member

Motivation & Context

The current contributor guidance asks coding agents to update consumer skills as maintained product documentation whenever APIs, packages, samples, or integrations change. That broad trigger encourages skills to accumulate implementation details and per-change rules instead of helping developers choose an approach.

Consumer skills should guide high-level development choices with Microsoft Agent Framework. Microsoft Learn remains the documentation source for implementing those choices.

Description & Review Guide

  • What are the major changes? Replace the automatic skill-update trigger with a decision-based maintenance rule. Define allowed and excluded content in the root instructions and consumer skill maintenance contract, add pointers in both language AGENTS.md files, and align both consumer SKILL.md documentation-lookup sections. Apply the same boundary to reference files, with concrete history, hosting, and authorization examples.
  • What is the impact of these changes? Framework changes no longer automatically require consumer skill edits. Updates are warranted only when a recommendation becomes incorrect, a materially different choice is introduced, or a documentation link becomes invalid. Repository task skills retain their existing purpose. This PR does not rewrite existing consumer reference content or change runtime behavior.
  • What do you want reviewers to focus on? Whether the scope and update criteria clearly separate development decisions from implementation documentation without restricting repository contributor guidance.

Checks: git diff --check passed; uv run --no-project python .github/tests/test_validate_agent_skill_links.py passed (16 tests); uv run --no-project python .github/scripts/validate_agent_skill_links.py skills passed. Runtime builds and unit suites were not run because this changes Markdown guidance only. Agent Skills specification validation and the GitHub publishing dry run were not run locally.

Related Issue

No linked issue. This guidance update was explicitly requested and its scope approved by Eduard van Valkenburg (@eavanvalkenburg) in the authoring conversation.

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Copilot assisted with the guidance proposal, Markdown edits, validation, and this PR description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • 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 a language prefix) — a workflow keeps the label and title prefix in sync automatically.

Copilot AI balanced review requested due to automatic review settings November 9, 2026 10:10
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python .NET Usage: [Issues, PRs], Target: .Net labels Nov 9, 2026
@github-actions github-actions Bot changed the title docs: keep consumer skills focused on development choices Python: docs: keep consumer skills focused on development choices Nov 9, 2026
@github-actions github-actions Bot changed the title Python: docs: keep consumer skills focused on development choices .NET: docs: keep consumer skills focused on development choices Nov 9, 2026
@eavanvalkenburg
Eduard van Valkenburg (eavanvalkenburg) marked this pull request as ready for review November 9, 2026 10:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the documentation-only updates to consumer skill guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR focuses public consumer skills on development choices, with Microsoft Learn providing implementation guidance. It preserves repository contributor guidance and does not change runtime behavior.

Changes:

  • Replaces automatic skill-update triggers with decision-based maintenance criteria.
  • Defines content boundaries for both consumer skills and their reference files.
  • Aligns Python and .NET guidance while keeping repository task skills outside these restrictions.
File Description
skills/​README.md Defines consumer skill scope, examples, and update criteria.
skills/​agent-framework-builder-python/​SKILL.md Aligns documentation lookup guidance with the decision-focused scope.
skills/​agent-framework-builder-dotnet/​SKILL.md Applies the same documentation boundary to the .NET consumer skill.
python/​AGENTS.md Separates contributor guidance from consumer skill maintenance.
dotnet/​AGENTS.md Adds consumer skill guidance and links to the maintenance contract.
.github/​copilot-instructions.md Replaces broad update requirements with decision-based rules.

Review effort: Balanced

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 551dbd024b1b
Model: gpt-5.6-sol

Overview

The PR consistently reframes consumer skills as decision guidance and adds clear boundaries, examples, current-source lookup instructions, and contributor/consumer separation. However, the new maintenance gate applies immediately while both distributed skills still contain concrete API and option details, leaving those retained details without an update path when an API changes but the underlying development choice does not.

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: skills/README.md

Comment thread skills/README.md Resolved
@github-code-quality

Copy link
Copy Markdown
Contributor

Code coverage overview

Languages: C#

C# / code-coverage/dotnet

main 924a6e5 consumer-skill-scope 32ad2ff +/-
86% 86% 0%
View coverage of the 1 most impacted file.
File main 924a6e5 consumer-skill-scope 32ad2ff +/-
/home/runner/wo...SessionStore.cs 100% 56% -44%

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

Merged via the queue into main with commit ce972ee Nov 9, 2026
40 checks passed
@eavanvalkenburg
Eduard van Valkenburg (eavanvalkenburg) deleted the consumer-skill-scope branch November 9, 2026 11:01

This branch was previously deployed

2 inactive deployments
github-app-auth — 32ad2ff1 Deployed Nov 9, 2026 by eavanvalkenburg via add_label #27380
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants