diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5de768027a7..cd597660081 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,11 +16,30 @@ 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, 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. + +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..386ebdf7100 100644 --- a/skills/README.md +++ b/skills/README.md @@ -38,6 +38,41 @@ 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, 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 +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: