Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 9 additions & 0 deletions dotnet/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 11 additions & 0 deletions python/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
41 changes: 38 additions & 3 deletions skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
eavanvalkenburg marked this conversation as resolved.
Resolved
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.
10 changes: 6 additions & 4 deletions skills/agent-framework-builder-dotnet/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
11 changes: 6 additions & 5 deletions skills/agent-framework-builder-python/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading