From 551dbd024b1b1340ed8ebf54e2898d9a363aadd4 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Mon, 9 Nov 2026 11:09:47 +0100 Subject: [PATCH 1/2] docs: keep consumer skills focused on development choices --- .github/copilot-instructions.md | 22 ++++++++++-- dotnet/AGENTS.md | 9 +++++ python/AGENTS.md | 11 ++++++ skills/README.md | 36 +++++++++++++++++-- .../agent-framework-builder-dotnet/SKILL.md | 10 +++--- .../agent-framework-builder-python/SKILL.md | 11 +++--- 6 files changed, 84 insertions(+), 15 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5de768027a7..71184efeef5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,11 +16,27 @@ not project skills for contributors working in this repository: - Do not load or invoke them as instructions for normal Agent Framework repository work. - Keep them outside `.github/skills`, `.agents/skills`, and `.claude/skills` so coding agents do not auto-discover them. -- When a change affects public APIs, packages, samples, configuration, evaluation, integrations, or hosting guidance, - review and update the corresponding consumer skill as maintained product documentation. -- Read a consumer skill during repository work only when that maintenance check is relevant; do not let its standalone +- Read a consumer skill during repository work only when maintaining its decision guidance; do not let its standalone application defaults override repository-specific instructions. +Consumer skills are decision guidance, not product documentation. Microsoft Learn is the documentation source for +developing with Microsoft Agent Framework. + +- Help coding agents choose an approach: plain agent, harness agent, or workflow; extension points; integrations; + state ownership; and hosting patterns. Include concise trade-offs, constraints that materially change those choices, + and links to current Learn guidance. +- Do not add API or option inventories, implementation details, setup or deployment procedures, exhaustive examples, + release notes, or per-bug workarounds. This applies to both `SKILL.md` and files under `references/`; moving detail + into a reference does not make it appropriate. +- A framework change does not automatically require a skill update. Update a consumer skill only when the change makes + an existing development recommendation incorrect, adds a materially different choice, or invalidates a documentation + link. Otherwise, leave the skill unchanged. +- Before adding content, identify the development decision it changes. If no decision changes, the content belongs in + Microsoft Learn, API documentation, samples, or contributor guidance, not in the consumer skill. Prefer revising an + existing recommendation over appending another rule. + +See the [consumer skill maintenance contract](../skills/README.md#repository-maintenance-contract) for scope examples. + ## Architectural Decision Records (ADRs) ADRs in `docs/decisions/` capture significant design decisions and their rationale. They document considered alternatives, trade-offs, and the reasoning behind choices. diff --git a/dotnet/AGENTS.md b/dotnet/AGENTS.md index 82a40871e26..03105778baa 100644 --- a/dotnet/AGENTS.md +++ b/dotnet/AGENTS.md @@ -2,6 +2,15 @@ Instructions for AI coding agents working in the .NET codebase. +## Public Consumer Skills + +The installable skills under `/skills/` guide high-level application-development choices. They are not documentation +or a checklist of framework behavior. Follow the +[consumer skill maintenance contract](../skills/README.md#repository-maintenance-contract). Do not update them merely +because a public API, package, sample, or implementation changed. + +This restriction concerns public consumer skills, not repository task skills under `.github/skills/`. + ## Build, Test, and Lint Commands See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects. diff --git a/python/AGENTS.md b/python/AGENTS.md index e74bd93a94b..2ef27383d45 100644 --- a/python/AGENTS.md +++ b/python/AGENTS.md @@ -20,6 +20,8 @@ Instructions for AI coding agents working in the Python codebase. ## Maintaining Documentation +This section concerns contributor guidance, not public consumer skills. + When making changes to a package, check if the following need updates: - The package's `AGENTS.md` file (adding/removing/renaming public APIs, architecture changes, import path changes) - The agent skills in `.github/skills/` if conventions, commands, or workflows change @@ -31,6 +33,15 @@ the user confirmed, etc.). **Before adding a new principle or rule, ask the user whether they want it captured as a durable principle** — do not invent team norms from a single conversation without explicit confirmation. +## Public Consumer Skills + +The installable skills under `/skills/` guide high-level application-development choices. They are not documentation +or a checklist of framework behavior. Follow the +[consumer skill maintenance contract](../skills/README.md#repository-maintenance-contract). Do not update them merely +because a public API, package, sample, or implementation changed. + +This restriction concerns public consumer skills, not repository task skills under `.github/skills/`. + ## Terminology - **Avoid "GA" for Agent Framework code.** Reserve *GA* for hosted services diff --git a/skills/README.md b/skills/README.md index 640e926c314..414747cf3e6 100644 --- a/skills/README.md +++ b/skills/README.md @@ -38,6 +38,36 @@ npx skills add microsoft/agent-framework --skill agent-framework-builder-dotnet instructions or automatically load them for normal framework development. - Keep the skills outside `.github/skills`, `.agents/skills`, and `.claude/skills` so repository agents do not discover them as project skills. -- Review the Python and .NET consumer skills whenever a change affects public APIs, package names or maturity, - canonical samples, configuration, evaluation, integrations, or hosting guidance. -- Update only the affected guidance. Do not copy internal contributor conventions into the consumer skill. + +### Purpose and scope + +Consumer skills are decision guidance, not product documentation. Microsoft Learn is the documentation source for +developing with Microsoft Agent Framework. Skills help coding agents make high-level development choices and find the +current documentation for implementing them. + +Include selection criteria, concise trade-offs, and constraints that materially change a choice: plain agent versus +harness agent versus workflow, extension points, integrations, state ownership, and hosting patterns. Link to Learn +for implementation guidance and to API documentation or maintained samples when needed. + +Do not add API or option inventories, implementation details, setup or deployment procedures, exhaustive examples, +release notes, per-bug workarounds, or internal contributor conventions. This applies to both `SKILL.md` and files under +`references/`; a reference file is not a place to accumulate documentation. + +For example: + +- Include the choice between application-managed and service-managed history and its trade-offs. Do not include + serialization fields, continuation-token mechanics, or every provider's storage options. +- Include the choice between self-hosted and Foundry-hosted execution. Do not include deployment commands, + environment-variable inventories, or protocol replay sequences. +- Include the need for interactive authorization when choosing a hosting pattern. Link to documentation for consent + handling instead of reproducing the request and response sequence. + +### When to update a skill + +A public API, package, sample, configuration, evaluation, integration, or hosting change does not automatically require +a consumer skill update. Update a skill only when the change makes an existing development recommendation incorrect, +adds a materially different choice, or invalidates a documentation link. Otherwise, leave the skill unchanged. + +Before adding content, identify the development decision it changes. If no decision changes, put the content in +Microsoft Learn, API documentation, samples, or contributor guidance instead. Prefer revising an existing recommendation +over appending another rule, and update only the affected guidance. diff --git a/skills/agent-framework-builder-dotnet/SKILL.md b/skills/agent-framework-builder-dotnet/SKILL.md index f03b8d8b956..ca176103531 100644 --- a/skills/agent-framework-builder-dotnet/SKILL.md +++ b/skills/agent-framework-builder-dotnet/SKILL.md @@ -77,11 +77,13 @@ relying on remembered preview-era syntax. ## Current documentation lookup -Use local guidance for stable decisions and common patterns. For provider matrices, package maturity, hosted tools, -deployment details, or unfamiliar APIs, consult current sources before generating code. +This skill and its references guide high-level development choices; they are not product documentation. Use them for +selection criteria, trade-offs, and constraints that materially change a choice. Microsoft Learn is the documentation +source for implementing the selected approach. -The reference pages intentionally describe selection rules, invariants, and non-obvious gotchas. Use XML docs or API -reference pages for signatures and option details, and use Learn or maintained samples for end-to-end procedures. +For provider matrices, package maturity, hosted tools, deployment details, or unfamiliar APIs, consult current sources +before generating code. Use XML docs or API reference pages for signatures and option details, and use Learn or +maintained samples for end-to-end procedures. Do not copy those details into this skill or its references. When the coding agent supports MCP, configure the Microsoft Learn MCP Server as a Streamable HTTP server: diff --git a/skills/agent-framework-builder-python/SKILL.md b/skills/agent-framework-builder-python/SKILL.md index 629d66eca47..eadf8939edd 100644 --- a/skills/agent-framework-builder-python/SKILL.md +++ b/skills/agent-framework-builder-python/SKILL.md @@ -68,12 +68,13 @@ relying on remembered preview-era syntax. ## Current documentation lookup -Use local guidance for stable decisions and common patterns. For provider matrices, package maturity, hosted tools, -deployment details, or unfamiliar APIs, consult current sources before generating code: +This skill and its references guide high-level development choices; they are not product documentation. Use them for +selection criteria, trade-offs, and constraints that materially change a choice. Microsoft Learn is the documentation +source for implementing the selected approach. -The reference pages intentionally describe selection rules, invariants, and non-obvious gotchas. Use public docstrings -or API reference pages for signatures and option details, and use Learn or maintained samples for end-to-end -procedures. +For provider matrices, package maturity, hosted tools, deployment details, or unfamiliar APIs, consult current sources +before generating code. Use public docstrings or API reference pages for signatures and option details, and use Learn +or maintained samples for end-to-end procedures. Do not copy those details into this skill or its references. When the coding agent supports MCP, configure the Microsoft Learn MCP Server as a Streamable HTTP server: From 32ad2ff1a2a7997b19c0870077648d3003707562 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Mon, 9 Nov 2026 11:19:18 +0100 Subject: [PATCH 2/2] docs: allow removal-first cleanup of stale skill details --- .github/copilot-instructions.md | 5 ++++- skills/README.md | 7 ++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 71184efeef5..cd597660081 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -30,7 +30,10 @@ developing with Microsoft Agent Framework. into a reference does not make it appropriate. - A framework change does not automatically require a skill update. Update a consumer skill only when the change makes an existing development recommendation incorrect, adds a materially different choice, or invalidates a documentation - link. Otherwise, leave the skill unchanged. + link, except for the cleanup rule below. Otherwise, leave the skill unchanged. +- If a framework change invalidates implementation details already present in a skill or its references, remove those + details or replace them with decision guidance and a link to current documentation. This cleanup exception does not + permit expanding the details or adding new implementation details. - Before adding content, identify the development decision it changes. If no decision changes, the content belongs in Microsoft Learn, API documentation, samples, or contributor guidance, not in the consumer skill. Prefer revising an existing recommendation over appending another rule. diff --git a/skills/README.md b/skills/README.md index 414747cf3e6..386ebdf7100 100644 --- a/skills/README.md +++ b/skills/README.md @@ -66,7 +66,12 @@ For example: A public API, package, sample, configuration, evaluation, integration, or hosting change does not automatically require a consumer skill update. Update a skill only when the change makes an existing development recommendation incorrect, -adds a materially different choice, or invalidates a documentation link. Otherwise, leave the skill unchanged. +adds a materially different choice, or invalidates a documentation link, except for the cleanup rule below. Otherwise, +leave the skill unchanged. + +If a framework change invalidates implementation details already present in a skill or its references, remove those +details or replace them with decision guidance and a link to current documentation. This cleanup exception does not +permit expanding the details or adding new implementation details. Before adding content, identify the development decision it changes. If no decision changes, put the content in Microsoft Learn, API documentation, samples, or contributor guidance instead. Prefer revising an existing recommendation