Repository navigation
.NET: docs: keep consumer skills focused on development choices - #10185
Conversation
There was a problem hiding this comment.
🟢 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
There was a problem hiding this comment.
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
Code coverage overviewLanguages: C# C# / code-coverage/dotnet
View coverage of the 1 most impacted file.
ℹ️ Calculations represent line coverage. Results may change as calculations are updated. |
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
Checks:
git diff --checkpassed;uv run --no-project python .github/tests/test_validate_agent_skill_links.pypassed (16 tests);uv run --no-project python .github/scripts/validate_agent_skill_links.py skillspassed. 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
AI assistance details: Copilot assisted with the guidance proposal, Markdown edits, validation, and this PR description.
Contribution Checklist
breaking changelabel (or add "[BREAKING]" to the title prefix, before or after a language prefix) — a workflow keeps the label and title prefix in sync automatically.