// Required when reviewing, updating, auditing, or creating any concept documentation page. Covers code accuracy checks against source repos, language parity across zone pivots, parity table comments, and structural consistency.
How to reference code from sample repos in Agent Framework docs pages using :::code directives, snippet tags, zone pivots, and highlight attributes.
How to configure cross-repository references (CRR) and create API class links for Microsoft Learn docs in this repository.
How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.
How to delete, rename, or move articles on Microsoft Learn while preserving Platform IDs, preventing broken links, and managing redirects.
Conceptual organization of Agent Framework documentation and samples. For language-specific details (file naming, provider setup, code patterns), see each code repo's skills files.
How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.
| name | per-concept-documentation |
| description | Required when reviewing, updating, auditing, or creating any concept documentation page. Covers code accuracy checks against source repos, language parity across zone pivots, parity table comments, and structural consistency. |
To create or update documentation for a specific concept in the project, follow this process:
Identify the concept for which the user is seeking new or updated documentation. This could be a feature, function, class, or any other relevant topic within the project. The project can be either Agent Framework or Semantic Kernel.
Gather information about the concept. Ask the following questions if they are not already answered:
If the concept is already documented, review the existing documentation to identify any gaps or areas that need updating. If the concept is not yet documented, proceed to create new documentation (ask the location where the documentation should be created if not already defined).
Documentation follows the format of the existing documentation in the project. Ensure that the new or updated documentation is consistent with the style and structure of the existing documentation.
If code snippets are needed, refer to the "code-snippets" skill for guidance on how to create code snippets in the documentation.
Verify code accuracy against source. For each language zone, compare the documented APIs (class names, method signatures, imports, parameters) against the current source code in the corresponding GitHub repository. Use GitHub search and file retrieval tools to check the actual source files, not just samples.
Check language parity. If the documentation covers multiple languages via zone pivots, compare the sections side by side to ensure each language covers the same set of concepts. Build a parity table listing each section and whether it is present for each language. Identify:
Add a parity comment. Insert an HTML comment immediately after the YAML frontmatter containing the language parity table. This table should be maintained as sections are added or removed. Use ✅ for included concepts, ❌ for excluded concepts, and add a notes column for explanations (e.g., "Python-specific"). Example:
<!--
Language parity table – keep in sync when adding/removing sections.
| Section | C# | Python | Notes |
|----------------------------|:--:|:------:|-----------------|
| Basic Structure | ✅ | ✅ | |
| Function-Based | ✅ | ✅ | |
| Explicit Type Parameters | ❌ | ✅ | Python-specific |
| The Context Object | ✅ | ✅ | |
-->
Resolve parity gaps. For each missing section identified in the parity table, determine whether it should be added (the concept exists in the other language's SDK) or marked as language-specific. Add equivalent sections where appropriate, mirroring the structure and depth of the existing language zone.
Treat each language zone as an isolated document. Do not compare or contrast one language's implementation with another within the zone content itself. For example, avoid phrases like "Unlike C#, Python does not use a RequestPort" or "the same guessing game workflow." Each zone pivot should read as a standalone document that makes sense without any knowledge of the other language's zone.
Update the date. After making changes, update the ms.date field in the YAML frontmatter to the current date.