From ab8787b505f6d38d21b3c6f9ee59287eecb2384e Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:03:29 -0600 Subject: [PATCH 1/8] feat: Expand microsoft-docs skill with Agent Framework, DevUI, and Semantic Kernel coverage Major improvements to the microsoft-docs skill: - Add Microsoft Agent Framework section with two Context7 sources: /websites/learn_microsoft_en-us_agent-framework (tutorials, 2282 snippets) /microsoft/agent-framework (GitHub repo API detail, 1177 snippets) - Add comprehensive DevUI workflow reference covering installation, programmatic launch, directory discovery, tracing, OpenAI-compatible API, OpenAI proxy, authentication, UI modes, .NET integration, and external observability export - Add Semantic Kernel section with three quality-ranked sources covering Learn docs, agent framework subset, and GitHub repo - Add guidance on when GitHub repo sources beat published docs (DevUI API reference, .NET integration, extension samples) - Expand decision table with agent framework scenarios - Add agent framework query examples for DevUI, SK, and workflows - Highlight microsoft_code_sample_search with language filter for working code snippets Tested all sources against identical queries to verify quality rankings. --- docs/README.skills.md | 2 +- skills/microsoft-docs/SKILL.md | 213 +++++++++++++++++++++++++++++---- 2 files changed, 194 insertions(+), 21 deletions(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index c2c3090fa..7c3fa2e1a 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -43,7 +43,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | [mcp-cli](../skills/mcp-cli/SKILL.md) | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None | | [meeting-minutes](../skills/meeting-minutes/SKILL.md) | Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps. | None | | [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md) | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None | -| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. Use for Azure, .NET, Microsoft 365, Windows, Power Platform, and all Microsoft technologies. Get accurate, current information from learn.microsoft.com and other official Microsoft websites—architecture overviews, quickstarts, configuration guides, limits, and best practices. | None | +| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft and Microsoft-adjacent documentation to understand concepts, find tutorials, and get code examples. Covers Azure, .NET, Agent Framework, Semantic Kernel, DevUI, Aspire, VS Code, GitHub, Microsoft 365, Windows, and Power Platform using Microsoft Learn MCP and Context7 for comprehensive lookup across learn.microsoft.com, code.visualstudio.com, docs.github.com, aspire.dev, and GitHub source repos. | None | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | | [penpot-uiux-design](../skills/penpot-uiux-design/SKILL.md) | Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools. Use this skill when: (1) Creating new UI/UX designs for web, mobile, or desktop applications, (2) Building design systems with components and tokens, (3) Designing dashboards, forms, navigation, or landing pages, (4) Applying accessibility standards and best practices, (5) Following platform guidelines (iOS, Android, Material Design), (6) Reviewing or improving existing Penpot designs for usability. Triggers: "design a UI", "create interface", "build layout", "design dashboard", "create form", "design landing page", "make it accessible", "design system", "component library". | `references/accessibility.md`
`references/component-patterns.md`
`references/platform-guidelines.md`
`references/setup-troubleshooting.md` | | [plantuml-ascii](../skills/plantuml-ascii/SKILL.md) | Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag | None | diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index 92f523b7d..d5511dfc5 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -1,26 +1,143 @@ --- name: microsoft-docs -description: Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. Use for Azure, .NET, Microsoft 365, Windows, Power Platform, and all Microsoft technologies. Get accurate, current information from learn.microsoft.com and other official Microsoft websites—architecture overviews, quickstarts, configuration guides, limits, and best practices. -compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp) +description: 'Query official Microsoft and Microsoft-adjacent documentation to understand concepts, find tutorials, and get code examples. Covers Azure, .NET, Agent Framework, Semantic Kernel, DevUI, Aspire, VS Code, GitHub, Microsoft 365, Windows, and Power Platform using Microsoft Learn MCP and Context7 for comprehensive lookup across learn.microsoft.com, code.visualstudio.com, docs.github.com, aspire.dev, and GitHub source repos.' --- # Microsoft Docs +A unified documentation research skill for the full Microsoft technology ecosystem — including technologies like VS Code, GitHub, and Agent Framework repos that live outside or ahead of learn.microsoft.com. + ## Tools +### Microsoft Learn MCP Server + +| Tool | Use For | +|------|---------| +| `microsoft_docs_search` | Find documentation on learn.microsoft.com — concepts, guides, tutorials, configuration | +| `microsoft_code_sample_search` | Find **working code snippets** from official Microsoft Learn docs. Especially strong for Agent Framework, Semantic Kernel, DevUI, and Azure SDK examples. Pass `language` parameter (`python`, `csharp`) for best results. | +| `microsoft_docs_fetch` | Get full page content from a specific Microsoft docs URL (when search excerpts aren't enough) | + +### Context7 (broader coverage) + +Context7 indexes both **websites** and **GitHub repos**, giving access to documentation that the Microsoft Learn MCP server cannot reach — including VS Code docs, GitHub docs, Aspire.dev, GitHub CLI, and README-level content from source repos that is often ahead of published docs. + | Tool | Use For | |------|---------| -| `microsoft_docs_search` | Find documentation—concepts, guides, tutorials, configuration | -| `microsoft_docs_fetch` | Get full page content (when search excerpts aren't enough) | +| `mcp_context7_resolve-library-id` | Find the Context7 library ID for a technology (one-time per session) | +| `mcp_context7_query-docs` | Query docs with a specific library ID — returns code snippets, explanations, and source links in a single call | + +### When GitHub Repo Sources (Context7) Beat Published Docs + +Context7 indexes GitHub repo README files, which often contain API-level detail, CLI references, and advanced config that hasn't been published to learn.microsoft.com yet. This is especially true for: + +- **DevUI** — the repo README (`/microsoft/agent-framework`) has complete API reference (endpoints, parameters, response schemas), OpenAI proxy config, and auth setup that the Learn page summarizes +- **Agent Framework .NET** — the repo has `Microsoft.Agents.AI.DevUI` integration code for ASP.NET Core before it appears on Learn +- **Extension samples** — `/microsoft/vscode-extension-samples` has working projects not always linked from the VS Code API docs + +**Rule of thumb:** query the **website source** for tutorials and concepts, then the **repo source** for API-level detail and the latest features. + +## When to Use Which Tool + +| Scenario | Best Tool | Why | +|----------|-----------|-----| +| Azure services, .NET, M365, Power Platform | `microsoft_docs_search` | Direct access to learn.microsoft.com | +| Code samples for any Learn topic | `microsoft_code_sample_search` | Returns up to 20 working code snippets with links. Filter by language. | +| Agent Framework — tutorials, concepts | `microsoft_docs_search` + Context7 Learn | Polished guides on learn.microsoft.com | +| Agent Framework — DevUI setup, API, CLI | Context7 `/microsoft/agent-framework` | GitHub repo has detailed DevUI README with full API reference | +| Agent Framework — DevUI tracing, directory discovery | Context7 `/websites/learn_microsoft_en-us_agent-framework` | Learn website has step-by-step guides | +| Semantic Kernel — agents, plugins, orchestration | Context7 `/websites/learn_microsoft_en-us_semantic-kernel` + `microsoft_code_sample_search` | Learn has the best SK docs; code sample search excels here | +| Semantic Kernel — source code, ADRs, design docs | Context7 `/microsoft/semantic-kernel` | GitHub repo has samples and architectural decisions | +| VS Code features, settings, shortcuts | Context7 `/websites/code_visualstudio` | VS Code docs live on code.visualstudio.com, not Learn | +| VS Code extension development / API | Context7 `/websites/code_visualstudio_api` | Extension API docs are separate from user docs | +| GitHub Actions, repos, API, features | Context7 `/websites/github_en` | GitHub docs live on docs.github.com | +| GitHub CLI (gh) | Context7 `/websites/cli_github` | CLI reference lives on cli.github.com | +| .NET Aspire (AppHost, integrations, CLI) | Context7 `/microsoft/aspire.dev` | Aspire docs live on aspire.dev, not Learn | +| Aspire community integrations (Go, Java) | Context7 `/communitytoolkit/aspire` | Community Toolkit is a separate repo | +| Need full tutorial with all steps | `microsoft_docs_fetch` | Gets complete page content | + +## Context7 Library Reference + +Call `mcp_context7_resolve-library-id` once per session to confirm IDs. Below are tested, quality-ranked sources. + +### Agent Frameworks + +#### Microsoft Agent Framework + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/websites/learn_microsoft_en-us_agent-framework` | 2,282 | 81.2 | **Primary for tutorials** — DevUI guides, directory discovery, tracing, AG-UI integration, workflow orchestration | +| `/microsoft/agent-framework` | 1,177 | — | **Primary for API detail** — DevUI README (full REST API, CLI flags, auth, OpenAI proxy), .NET DevUI integration, samples | + +The **Learn website** source has polished tutorials and conceptual docs. The **GitHub repo** source has README-level detail that is often ahead of published docs — particularly the DevUI REST API reference, advanced CLI options, and .NET `Microsoft.Agents.AI.DevUI` package setup. + +**Use both** for comprehensive Agent Framework coverage: query the website source for "how to" guides, then the repo source for API-level specifics. + +##### DevUI Workflow + +DevUI is a sample app for running and debugging agents/workflows interactively. Key topics: + +1. **Installation**: `pip install agent-framework-devui --pre` +2. **Programmatic launch**: `serve(entities=[agent], auto_open=True)` — registers agents in-memory +3. **Directory discovery**: `devui ./agents --port 8080` — auto-discovers agents/workflows from `__init__.py` files +4. **Tracing**: `devui ./agents --tracing` or `serve(entities=[agent], tracing_enabled=True)` — enables OpenTelemetry traces visible in the debug panel +5. **OpenAI-compatible API**: `POST /v1/responses` with `metadata.entity_id` — use with OpenAI Python SDK +6. **OpenAI proxy**: Set `X-Proxy-Backend: openai` header to proxy requests through DevUI (keeps API key server-side) +7. **Authentication**: `devui ./agents --auth --auth-token "token"` — Bearer token auth +8. **UI modes**: `--mode developer` (default, full debug) vs `--mode user` (simplified, restricted) +9. **.NET integration**: `builder.AddDevUI()` + `app.MapDevUI()` in ASP.NET Core (development only) +10. **Export to external observability**: Set `OTLP_ENDPOINT` to send traces to Jaeger, Zipkin, Azure Monitor, Datadog -## When to Use +**Best query strategy for DevUI:** +- Use `microsoft_code_sample_search` with `language: "python"` for working DevUI code +- Use Context7 `/microsoft/agent-framework` for the DevUI REST API reference +- Use Context7 `/websites/learn_microsoft_en-us_agent-framework` for directory structure and tracing guides -- **Understanding concepts** — "How does Cosmos DB partitioning work?" -- **Learning a service** — "Azure Functions overview", "Container Apps architecture" -- **Finding tutorials** — "quickstart", "getting started", "step-by-step" -- **Configuration options** — "App Service configuration settings" -- **Limits & quotas** — "Azure OpenAI rate limits", "Service Bus quotas" -- **Best practices** — "Azure security best practices" +#### Semantic Kernel + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/websites/learn_microsoft_en-us_semantic-kernel` | 4,909 | 69.5 | **Primary** — agents, plugins, orchestration, function calling, migration guides | +| `/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent` | 932 | 76.4 | Agent framework subset — ChatCompletionAgent, AgentGroupChat, orchestration patterns | +| `/microsoft/semantic-kernel` | 2,950 | 74.7 | GitHub repo — samples, ADRs, design documents, process integration | + +**Use the Learn website source** for Semantic Kernel tutorials and plugin setup. **Use the agent framework subset** for focused agent orchestration queries. **Use the GitHub repo** for sample code, architectural decisions, and advanced patterns (e.g., `GettingStartedWithProcesses`). + +### Azure & .NET (learn.microsoft.com) + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/websites/learn_microsoft_en-us_azure` | 164,912 | 73.8 | All Azure services — compute, storage, networking, AI, databases | +| `/microsoftdocs/azure-docs` | 61,791 | 76.7 | Azure docs GitHub repo — higher quality score | +| `/websites/learn_microsoft_en-us` | 158,360 | 45.4 | All of Microsoft Learn — broadest but lower precision | +| `/websites/learn_microsoft_en-us_dotnet_azure` | 1,156 | — | Azure SDK for .NET developers specifically | + +### .NET Aspire + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/microsoft/aspire.dev` | 1,865 | 73.0 | **Primary** — official docs site repo, best quality, full Aspire 13+ coverage | +| `/websites/aspire_dev` | 31,845 | 71.6 | Website crawl — massive but includes multilingual duplicates | +| `/dotnet/aspire` | 1,185 | 71.5 | Runtime source — API internals, playground examples | +| `/communitytoolkit/aspire` | 311 | 64.2 | Community integrations — Golang, Java, Node.js, Vite, Ollama | +| `/dotnet/docs-aspire` | 482 | 71.4 | **Legacy** — being superseded by aspire.dev, avoid for tutorials | + +### Visual Studio Code + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/websites/code_visualstudio` | 6,288 | 80.4 | **Primary** — user docs, settings, features, debugging, remote dev | +| `/websites/code_visualstudio_api` | 1,681 | 65.4 | Extension API — webviews, TreeViews, commands, contribution points | +| `/microsoft/vscode-docs` | 8,289 | 87.9 | Docs repo — highest score, markdown source files | +| `/microsoft/vscode-extension-samples` | 320 | 82.4 | Extension samples — working code examples | + +### GitHub + +| Library ID | Snippets | Score | Coverage | +|---|---|---|---| +| `/websites/github_en` | 43,828 | 66.2 | **Primary** — Actions, API, repos, security, admin, Copilot | +| `/github/docs` | 24,544 | 73.7 | Docs repo — markdown source, higher quality score | +| `/websites/cli_github` | 386 | 83.2 | GitHub CLI reference — gh commands, flags, examples | +| `/websites/cli_github_manual` | 478 | 44.0 | CLI manual — alternative, lower score | ## Query Effectiveness @@ -29,28 +146,84 @@ Good queries are specific: ``` # ❌ Too broad "Azure Functions" +"VS Code extensions" +"agent framework" # ✅ Specific "Azure Functions Python v2 programming model" "Cosmos DB partition key design best practices" -"Container Apps scaling rules KEDA" +"VS Code webview API onDidReceiveMessage postMessage" +"GitHub Actions workflow_dispatch inputs matrix strategy" +"Aspire AddUvicornApp Python FastAPI integration" +"DevUI serve agents tracing OpenTelemetry directory discovery" +"ChatCompletionAgent plugin tool calling multi-agent orchestration" +"Agent Framework workflow conditional edges branching handoff" ``` Include context: -- **Version** when relevant (`.NET 8`, `EF Core 8`) -- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`) -- **Platform** for multi-platform docs (`Linux`, `Windows`) +- **Version** when relevant (`.NET 8`, `Aspire 13`, `VS Code 1.96`) +- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`, `API reference`) +- **Platform** for multi-platform docs (`Linux`, `Windows`, `macOS`) +- **Language** for polyglot docs (`Python`, `TypeScript`, `C#`) + +### Agent Framework Query Examples + +``` +# DevUI — setup and running +microsoft_code_sample_search(language="python", query="DevUI agent framework serve agents tracing") +context7_query("/microsoft/agent-framework", "DevUI CLI options port host headless authentication") +context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI directory discovery agent workflow __init__.py") + +# DevUI — tracing and observability +context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI tracing OpenTelemetry debug panel span hierarchy") +microsoft_docs_search("configure tracing agent framework DevUI OTLP_ENDPOINT Jaeger") + +# DevUI — API and OpenAI SDK +context7_query("/microsoft/agent-framework", "DevUI POST /v1/responses OpenAI SDK entity_id streaming") +context7_query("/microsoft/agent-framework", "DevUI OpenAI proxy X-Proxy-Backend authentication") + +# DevUI — .NET integration +microsoft_code_sample_search(language="csharp", query="DevUI AddDevUI MapDevUI ASP.NET Core agent") +context7_query("/microsoft/agent-framework", "Microsoft.Agents.AI.DevUI AddDevUI MapDevUI ASP.NET Core") + +# Semantic Kernel agents +microsoft_code_sample_search(language="python", query="ChatCompletionAgent plugin AgentGroupChat") +context7_query("/websites/learn_microsoft_en-us_semantic-kernel", "ChatCompletionAgent plugin tool calling setup") +context7_query("/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent", "AgentGroupChat selection strategy termination") + +# Agent Framework workflows +context7_query("/websites/learn_microsoft_en-us_agent-framework", "workflow orchestration magentic handoff conditional edge") +microsoft_code_sample_search(language="csharp", query="agent framework workflow WorkflowBuilder AddEdge") + +# Cross-framework tracing +microsoft_docs_search("configure tracing AI agent frameworks Foundry Semantic Kernel Agent Framework") +``` + +## Workflow + +1. **Identify the technology** — is it Azure/Learn content, Agent Framework, Semantic Kernel, DevUI, VS Code, GitHub, or Aspire? +2. **Pick the right tool** — use the decision table above to choose between Microsoft Learn MCP and Context7 +3. **For Agent Frameworks** — use `microsoft_code_sample_search` for working code, then Context7 for deeper API docs: + - **DevUI how-to**: Context7 Learn website → code sample search for working examples → Context7 repo for API detail + - **Semantic Kernel**: Context7 Learn website + code sample search → Context7 repo for advanced samples + - **Workflow orchestration**: Microsoft Learn search → Context7 Learn website for patterns +4. **For Context7** — resolve the library ID first (if not cached), then query with a specific question +5. **For Microsoft Learn** — search first, then fetch full pages when you need complete tutorials or all config options +6. **Combine tools** — for cross-cutting questions (e.g., "deploy Aspire to Azure", "trace Agent Framework to Azure Monitor"), use multiple sources -## When to Fetch Full Page +## When to Fetch Full Page (Microsoft Learn MCP) -Fetch after search when: +Use `microsoft_docs_fetch` after `microsoft_docs_search` when: - **Tutorials** — need complete step-by-step instructions - **Configuration guides** — need all options listed - **Deep dives** — user wants comprehensive coverage - **Search excerpt is cut off** — full context needed +- **Agent Framework DevUI docs** — `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` for complete setup guide ## Why Use This -- **Accuracy** — live docs, not training data that may be outdated -- **Completeness** — tutorials have all steps, not fragments -- **Authority** — official Microsoft documentation +- **Accuracy** — live docs and indexed sources, not stale training data +- **Completeness** — full tutorials, not fragments +- **Breadth** — covers the entire Microsoft ecosystem including VS Code, GitHub, Agent Framework repos, and Aspire that live outside learn.microsoft.com +- **Depth** — GitHub repo sources provide API-level detail ahead of published docs +- **Authority** — official Microsoft and first-party documentation From bdaeff279fa3072c076946d0ba83c6158434616c Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:09:19 -0600 Subject: [PATCH 2/8] refactor: Replace DevUI tutorial content with research guidance The skill is about how to research docs, not a DevUI tutorial. Replace the 10-step DevUI workflow checklist with a research strategy table showing which tool to use for each type of DevUI information. --- skills/microsoft-docs/SKILL.md | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index d5511dfc5..7e91ba77f 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -72,25 +72,19 @@ The **Learn website** source has polished tutorials and conceptual docs. The **G **Use both** for comprehensive Agent Framework coverage: query the website source for "how to" guides, then the repo source for API-level specifics. -##### DevUI Workflow - -DevUI is a sample app for running and debugging agents/workflows interactively. Key topics: - -1. **Installation**: `pip install agent-framework-devui --pre` -2. **Programmatic launch**: `serve(entities=[agent], auto_open=True)` — registers agents in-memory -3. **Directory discovery**: `devui ./agents --port 8080` — auto-discovers agents/workflows from `__init__.py` files -4. **Tracing**: `devui ./agents --tracing` or `serve(entities=[agent], tracing_enabled=True)` — enables OpenTelemetry traces visible in the debug panel -5. **OpenAI-compatible API**: `POST /v1/responses` with `metadata.entity_id` — use with OpenAI Python SDK -6. **OpenAI proxy**: Set `X-Proxy-Backend: openai` header to proxy requests through DevUI (keeps API key server-side) -7. **Authentication**: `devui ./agents --auth --auth-token "token"` — Bearer token auth -8. **UI modes**: `--mode developer` (default, full debug) vs `--mode user` (simplified, restricted) -9. **.NET integration**: `builder.AddDevUI()` + `app.MapDevUI()` in ASP.NET Core (development only) -10. **Export to external observability**: Set `OTLP_ENDPOINT` to send traces to Jaeger, Zipkin, Azure Monitor, Datadog - -**Best query strategy for DevUI:** -- Use `microsoft_code_sample_search` with `language: "python"` for working DevUI code -- Use Context7 `/microsoft/agent-framework` for the DevUI REST API reference -- Use Context7 `/websites/learn_microsoft_en-us_agent-framework` for directory structure and tracing guides +##### Researching DevUI + +DevUI docs are split across Learn and the GitHub repo. The best research strategy: + +| What You Need | Where to Search | +|---------------|----------------| +| Setup tutorial, directory structure | Context7 `/websites/learn_microsoft_en-us_agent-framework` — query "DevUI directory discovery" or "DevUI tracing" | +| CLI flags, REST API endpoints, auth config | Context7 `/microsoft/agent-framework` — query "DevUI CLI options" or "DevUI POST /v1/responses" | +| Working Python code snippets | `microsoft_code_sample_search` with `language: "python"` — query "DevUI agent framework serve" | +| Working C# integration code | `microsoft_code_sample_search` with `language: "csharp"` — query "DevUI AddDevUI MapDevUI" | +| Full setup guide in one page | `microsoft_docs_fetch` with URL `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` | + +The GitHub repo source is particularly valuable for DevUI because it contains API-level detail (endpoint schemas, proxy config, auth tokens) that the Learn page summarizes. #### Semantic Kernel From 00508b71f3612767118c240a189c7547c52ea511 Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:12:10 -0600 Subject: [PATCH 3/8] refactor: Remove Semantic Kernel prose, keep library reference table --- skills/microsoft-docs/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index 7e91ba77f..1d6847452 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -94,8 +94,6 @@ The GitHub repo source is particularly valuable for DevUI because it contains AP | `/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent` | 932 | 76.4 | Agent framework subset — ChatCompletionAgent, AgentGroupChat, orchestration patterns | | `/microsoft/semantic-kernel` | 2,950 | 74.7 | GitHub repo — samples, ADRs, design documents, process integration | -**Use the Learn website source** for Semantic Kernel tutorials and plugin setup. **Use the agent framework subset** for focused agent orchestration queries. **Use the GitHub repo** for sample code, architectural decisions, and advanced patterns (e.g., `GettingStartedWithProcesses`). - ### Azure & .NET (learn.microsoft.com) | Library ID | Snippets | Score | Coverage | From b5cf6a24738e93478c79f12bc706bdfce3a3b1f7 Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:13:28 -0600 Subject: [PATCH 4/8] refactor: Remove Semantic Kernel library reference table --- skills/microsoft-docs/SKILL.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index 1d6847452..146637c23 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -86,14 +86,6 @@ DevUI docs are split across Learn and the GitHub repo. The best research strateg The GitHub repo source is particularly valuable for DevUI because it contains API-level detail (endpoint schemas, proxy config, auth tokens) that the Learn page summarizes. -#### Semantic Kernel - -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/websites/learn_microsoft_en-us_semantic-kernel` | 4,909 | 69.5 | **Primary** — agents, plugins, orchestration, function calling, migration guides | -| `/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent` | 932 | 76.4 | Agent framework subset — ChatCompletionAgent, AgentGroupChat, orchestration patterns | -| `/microsoft/semantic-kernel` | 2,950 | 74.7 | GitHub repo — samples, ADRs, design documents, process integration | - ### Azure & .NET (learn.microsoft.com) | Library ID | Snippets | Score | Coverage | From f28f8ab883c992dfa7d60cd380e8cd56c79e1038 Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:26:30 -0600 Subject: [PATCH 5/8] chore: Rebuild README.skills.md with updated description --- docs/README.skills.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.skills.md b/docs/README.skills.md index 7c3fa2e1a..be0ef0a52 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -24,6 +24,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | ---- | ----------- | -------------- | | [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
- Implementing self-critique and reflection loops
- Building evaluator-optimizer pipelines for quality-critical generation
- Creating test-driven code refinement workflows
- Designing rubric-based or LLM-as-judge evaluation systems
- Adding iterative improvement to agent outputs (code, reports, analysis)
- Measuring and improving agent response quality | None | | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`
`examples/appinsights.bicep`
`references/ASPNETCORE.md`
`references/AUTO.md`
`references/NODEJS.md`
`references/PYTHON.md`
`scripts/appinsights.ps1` | +| [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | None | | [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`
`references/REPORT-TEMPLATE.md`
`references/VALIDATION-COMMANDS.md` | | [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None | | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`
`assets/template-architecture.md` | From 27c55ffdb877bdfce093631c10db681b608e734a Mon Sep 17 00:00:00 2001 From: Chris McKee <25754153+ChrisMcKee1@users.noreply.github.com> Date: Fri, 6 Feb 2026 10:32:24 -0600 Subject: [PATCH 6/8] Update skills/microsoft-docs/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- skills/microsoft-docs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index 146637c23..bcbb92b5e 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -176,7 +176,7 @@ context7_query("/websites/learn_microsoft_en-us_semantic-kernel", "ChatCompletio context7_query("/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent", "AgentGroupChat selection strategy termination") # Agent Framework workflows -context7_query("/websites/learn_microsoft_en-us_agent-framework", "workflow orchestration magentic handoff conditional edge") +context7_query("/websites/learn_microsoft_en-us_agent-framework", "workflow orchestration multi-agent handoff conditional edge") microsoft_code_sample_search(language="csharp", query="agent framework workflow WorkflowBuilder AddEdge") # Cross-framework tracing From e4c35f3702b0c65a405c77c183107c6529658fae Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Fri, 6 Feb 2026 10:36:43 -0600 Subject: [PATCH 7/8] chore: rebuild README.skills.md without aspire skill (belongs to separate PR) --- docs/README.skills.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index be0ef0a52..7c3fa2e1a 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -24,7 +24,6 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | ---- | ----------- | -------------- | | [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
- Implementing self-critique and reflection loops
- Building evaluator-optimizer pipelines for quality-critical generation
- Creating test-driven code refinement workflows
- Designing rubric-based or LLM-as-judge evaluation systems
- Adding iterative improvement to agent outputs (code, reports, analysis)
- Measuring and improving agent response quality | None | | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`
`examples/appinsights.bicep`
`references/ASPNETCORE.md`
`references/AUTO.md`
`references/NODEJS.md`
`references/PYTHON.md`
`scripts/appinsights.ps1` | -| [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | None | | [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`
`references/REPORT-TEMPLATE.md`
`references/VALIDATION-COMMANDS.md` | | [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None | | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`
`assets/template-architecture.md` | From ae7bb2aa7ca2fd3ffbfcab434c63f860e6f9d8e1 Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Sun, 8 Feb 2026 20:22:52 -0600 Subject: [PATCH 8/8] refactor: Simplify microsoft-docs skill to default-Learn-with-exceptions pattern, add Aspire MCP version gate --- docs/README.skills.md | 2 +- skills/microsoft-docs/SKILL.md | 212 +++++++++------------------------ 2 files changed, 57 insertions(+), 157 deletions(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index 7c3fa2e1a..8e7cebfd0 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -43,7 +43,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | [mcp-cli](../skills/mcp-cli/SKILL.md) | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None | | [meeting-minutes](../skills/meeting-minutes/SKILL.md) | Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps. | None | | [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md) | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None | -| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft and Microsoft-adjacent documentation to understand concepts, find tutorials, and get code examples. Covers Azure, .NET, Agent Framework, Semantic Kernel, DevUI, Aspire, VS Code, GitHub, Microsoft 365, Windows, and Power Platform using Microsoft Learn MCP and Context7 for comprehensive lookup across learn.microsoft.com, code.visualstudio.com, docs.github.com, aspire.dev, and GitHub source repos. | None | +| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft documentation to find concepts, tutorials, and code examples across Azure, .NET, Agent Framework, Aspire, VS Code, GitHub, and more. Uses Microsoft Learn MCP as the default, with Context7 and Aspire MCP for content that lives outside learn.microsoft.com. | None | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | | [penpot-uiux-design](../skills/penpot-uiux-design/SKILL.md) | Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools. Use this skill when: (1) Creating new UI/UX designs for web, mobile, or desktop applications, (2) Building design systems with components and tokens, (3) Designing dashboards, forms, navigation, or landing pages, (4) Applying accessibility standards and best practices, (5) Following platform guidelines (iOS, Android, Material Design), (6) Reviewing or improving existing Penpot designs for usability. Triggers: "design a UI", "create interface", "build layout", "design dashboard", "create form", "design landing page", "make it accessible", "design system", "component library". | `references/accessibility.md`
`references/component-patterns.md`
`references/platform-guidelines.md`
`references/setup-troubleshooting.md` | | [plantuml-ascii](../skills/plantuml-ascii/SKILL.md) | Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag | None | diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index bcbb92b5e..201b5e008 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -1,213 +1,113 @@ --- name: microsoft-docs -description: 'Query official Microsoft and Microsoft-adjacent documentation to understand concepts, find tutorials, and get code examples. Covers Azure, .NET, Agent Framework, Semantic Kernel, DevUI, Aspire, VS Code, GitHub, Microsoft 365, Windows, and Power Platform using Microsoft Learn MCP and Context7 for comprehensive lookup across learn.microsoft.com, code.visualstudio.com, docs.github.com, aspire.dev, and GitHub source repos.' +description: 'Query official Microsoft documentation to find concepts, tutorials, and code examples across Azure, .NET, Agent Framework, Aspire, VS Code, GitHub, and more. Uses Microsoft Learn MCP as the default, with Context7 and Aspire MCP for content that lives outside learn.microsoft.com.' --- # Microsoft Docs -A unified documentation research skill for the full Microsoft technology ecosystem — including technologies like VS Code, GitHub, and Agent Framework repos that live outside or ahead of learn.microsoft.com. +Research skill for the Microsoft technology ecosystem. Covers learn.microsoft.com and documentation that lives outside it (VS Code, GitHub, Aspire, Agent Framework repos). -## Tools - -### Microsoft Learn MCP Server - -| Tool | Use For | -|------|---------| -| `microsoft_docs_search` | Find documentation on learn.microsoft.com — concepts, guides, tutorials, configuration | -| `microsoft_code_sample_search` | Find **working code snippets** from official Microsoft Learn docs. Especially strong for Agent Framework, Semantic Kernel, DevUI, and Azure SDK examples. Pass `language` parameter (`python`, `csharp`) for best results. | -| `microsoft_docs_fetch` | Get full page content from a specific Microsoft docs URL (when search excerpts aren't enough) | +--- -### Context7 (broader coverage) +## Default: Microsoft Learn MCP -Context7 indexes both **websites** and **GitHub repos**, giving access to documentation that the Microsoft Learn MCP server cannot reach — including VS Code docs, GitHub docs, Aspire.dev, GitHub CLI, and README-level content from source repos that is often ahead of published docs. +Use these tools for **everything on learn.microsoft.com** — Azure, .NET, M365, Power Platform, Agent Framework, Semantic Kernel, Windows, and more. This is the primary tool for the vast majority of Microsoft documentation queries. -| Tool | Use For | +| Tool | Purpose | |------|---------| -| `mcp_context7_resolve-library-id` | Find the Context7 library ID for a technology (one-time per session) | -| `mcp_context7_query-docs` | Query docs with a specific library ID — returns code snippets, explanations, and source links in a single call | +| `microsoft_docs_search` | Search learn.microsoft.com — concepts, guides, tutorials, configuration | +| `microsoft_code_sample_search` | Find working code snippets from Learn docs. Pass `language` (`python`, `csharp`, etc.) for best results | +| `microsoft_docs_fetch` | Get full page content from a specific URL (when search excerpts aren't enough) | -### When GitHub Repo Sources (Context7) Beat Published Docs +Use `microsoft_docs_fetch` after search when you need complete tutorials, all config options, or when search excerpts are truncated. -Context7 indexes GitHub repo README files, which often contain API-level detail, CLI references, and advanced config that hasn't been published to learn.microsoft.com yet. This is especially true for: +--- -- **DevUI** — the repo README (`/microsoft/agent-framework`) has complete API reference (endpoints, parameters, response schemas), OpenAI proxy config, and auth setup that the Learn page summarizes -- **Agent Framework .NET** — the repo has `Microsoft.Agents.AI.DevUI` integration code for ASP.NET Core before it appears on Learn -- **Extension samples** — `/microsoft/vscode-extension-samples` has working projects not always linked from the VS Code API docs +## Exceptions: When to Use Other Tools -**Rule of thumb:** query the **website source** for tutorials and concepts, then the **repo source** for API-level detail and the latest features. +The following categories live **outside** learn.microsoft.com. Use the specified tool instead. -## When to Use Which Tool +### .NET Aspire — Use Aspire MCP Server (preferred) or Context7 -| Scenario | Best Tool | Why | -|----------|-----------|-----| -| Azure services, .NET, M365, Power Platform | `microsoft_docs_search` | Direct access to learn.microsoft.com | -| Code samples for any Learn topic | `microsoft_code_sample_search` | Returns up to 20 working code snippets with links. Filter by language. | -| Agent Framework — tutorials, concepts | `microsoft_docs_search` + Context7 Learn | Polished guides on learn.microsoft.com | -| Agent Framework — DevUI setup, API, CLI | Context7 `/microsoft/agent-framework` | GitHub repo has detailed DevUI README with full API reference | -| Agent Framework — DevUI tracing, directory discovery | Context7 `/websites/learn_microsoft_en-us_agent-framework` | Learn website has step-by-step guides | -| Semantic Kernel — agents, plugins, orchestration | Context7 `/websites/learn_microsoft_en-us_semantic-kernel` + `microsoft_code_sample_search` | Learn has the best SK docs; code sample search excels here | -| Semantic Kernel — source code, ADRs, design docs | Context7 `/microsoft/semantic-kernel` | GitHub repo has samples and architectural decisions | -| VS Code features, settings, shortcuts | Context7 `/websites/code_visualstudio` | VS Code docs live on code.visualstudio.com, not Learn | -| VS Code extension development / API | Context7 `/websites/code_visualstudio_api` | Extension API docs are separate from user docs | -| GitHub Actions, repos, API, features | Context7 `/websites/github_en` | GitHub docs live on docs.github.com | -| GitHub CLI (gh) | Context7 `/websites/cli_github` | CLI reference lives on cli.github.com | -| .NET Aspire (AppHost, integrations, CLI) | Context7 `/microsoft/aspire.dev` | Aspire docs live on aspire.dev, not Learn | -| Aspire community integrations (Go, Java) | Context7 `/communitytoolkit/aspire` | Community Toolkit is a separate repo | -| Need full tutorial with all steps | `microsoft_docs_fetch` | Gets complete page content | +Aspire docs live on **aspire.dev**, not Learn. The best tool depends on your Aspire CLI version: -## Context7 Library Reference +**CLI 13.2+** (recommended) — The Aspire MCP server includes built-in docs search tools: -Call `mcp_context7_resolve-library-id` once per session to confirm IDs. Below are tested, quality-ranked sources. +| MCP Tool | Description | +|----------|-------------| +| `list_docs` | Lists all available documentation from aspire.dev | +| `search_docs` | Weighted lexical search across aspire.dev content | +| `get_doc` | Retrieves a specific document by slug | -### Agent Frameworks +These ship in Aspire CLI 13.2 ([PR #14028](https://github.com/dotnet/aspire/pull/14028)). To update: `aspire update --self --channel daily`. Ref: https://davidpine.dev/posts/aspire-docs-mcp-tools/ -#### Microsoft Agent Framework +**CLI 13.1** — The MCP server provides integration lookup (`list_integrations`, `get_integration_docs`) but **not** docs search. Fall back to Context7: -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/websites/learn_microsoft_en-us_agent-framework` | 2,282 | 81.2 | **Primary for tutorials** — DevUI guides, directory discovery, tracing, AG-UI integration, workflow orchestration | -| `/microsoft/agent-framework` | 1,177 | — | **Primary for API detail** — DevUI README (full REST API, CLI flags, auth, OpenAI proxy), .NET DevUI integration, samples | +| Library ID | Use for | +|---|---| +| `/microsoft/aspire.dev` | Primary — guides, integrations, CLI reference, deployment | +| `/dotnet/aspire` | Runtime source — API internals, implementation details | +| `/communitytoolkit/aspire` | Community integrations — Go, Java, Node.js, Ollama | -The **Learn website** source has polished tutorials and conceptual docs. The **GitHub repo** source has README-level detail that is often ahead of published docs — particularly the DevUI REST API reference, advanced CLI options, and .NET `Microsoft.Agents.AI.DevUI` package setup. +### VS Code — Use Context7 -**Use both** for comprehensive Agent Framework coverage: query the website source for "how to" guides, then the repo source for API-level specifics. +VS Code docs live on **code.visualstudio.com**, not Learn. -##### Researching DevUI +| Library ID | Use for | +|---|---| +| `/websites/code_visualstudio` | User docs — settings, features, debugging, remote dev | +| `/websites/code_visualstudio_api` | Extension API — webviews, TreeViews, commands, contribution points | -DevUI docs are split across Learn and the GitHub repo. The best research strategy: +### GitHub — Use Context7 -| What You Need | Where to Search | -|---------------|----------------| -| Setup tutorial, directory structure | Context7 `/websites/learn_microsoft_en-us_agent-framework` — query "DevUI directory discovery" or "DevUI tracing" | -| CLI flags, REST API endpoints, auth config | Context7 `/microsoft/agent-framework` — query "DevUI CLI options" or "DevUI POST /v1/responses" | -| Working Python code snippets | `microsoft_code_sample_search` with `language: "python"` — query "DevUI agent framework serve" | -| Working C# integration code | `microsoft_code_sample_search` with `language: "csharp"` — query "DevUI AddDevUI MapDevUI" | -| Full setup guide in one page | `microsoft_docs_fetch` with URL `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` | +GitHub docs live on **docs.github.com** and **cli.github.com**. -The GitHub repo source is particularly valuable for DevUI because it contains API-level detail (endpoint schemas, proxy config, auth tokens) that the Learn page summarizes. +| Library ID | Use for | +|---|---| +| `/websites/github_en` | Actions, API, repos, security, admin, Copilot | +| `/websites/cli_github` | GitHub CLI (`gh`) commands and flags | -### Azure & .NET (learn.microsoft.com) +### Agent Framework — Use Learn MCP + Context7 -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/websites/learn_microsoft_en-us_azure` | 164,912 | 73.8 | All Azure services — compute, storage, networking, AI, databases | -| `/microsoftdocs/azure-docs` | 61,791 | 76.7 | Azure docs GitHub repo — higher quality score | -| `/websites/learn_microsoft_en-us` | 158,360 | 45.4 | All of Microsoft Learn — broadest but lower precision | -| `/websites/learn_microsoft_en-us_dotnet_azure` | 1,156 | — | Azure SDK for .NET developers specifically | +Agent Framework tutorials are on learn.microsoft.com (use `microsoft_docs_search`), but the **GitHub repo** has API-level detail that is often ahead of published docs — particularly DevUI REST API reference, CLI options, and .NET integration. -### .NET Aspire +| Library ID | Use for | +|---|---| +| `/websites/learn_microsoft_en-us_agent-framework` | Tutorials — DevUI guides, tracing, workflow orchestration | +| `/microsoft/agent-framework` | API detail — DevUI REST endpoints, CLI flags, auth, .NET `AddDevUI`/`MapDevUI` | -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/microsoft/aspire.dev` | 1,865 | 73.0 | **Primary** — official docs site repo, best quality, full Aspire 13+ coverage | -| `/websites/aspire_dev` | 31,845 | 71.6 | Website crawl — massive but includes multilingual duplicates | -| `/dotnet/aspire` | 1,185 | 71.5 | Runtime source — API internals, playground examples | -| `/communitytoolkit/aspire` | 311 | 64.2 | Community integrations — Golang, Java, Node.js, Vite, Ollama | -| `/dotnet/docs-aspire` | 482 | 71.4 | **Legacy** — being superseded by aspire.dev, avoid for tutorials | +**DevUI tip:** Query the Learn website source for how-to guides, then the repo source for API-level specifics (endpoint schemas, proxy config, auth tokens). -### Visual Studio Code +--- -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/websites/code_visualstudio` | 6,288 | 80.4 | **Primary** — user docs, settings, features, debugging, remote dev | -| `/websites/code_visualstudio_api` | 1,681 | 65.4 | Extension API — webviews, TreeViews, commands, contribution points | -| `/microsoft/vscode-docs` | 8,289 | 87.9 | Docs repo — highest score, markdown source files | -| `/microsoft/vscode-extension-samples` | 320 | 82.4 | Extension samples — working code examples | +## Context7 Setup -### GitHub +For any Context7 query, resolve the library ID first (one-time per session): -| Library ID | Snippets | Score | Coverage | -|---|---|---|---| -| `/websites/github_en` | 43,828 | 66.2 | **Primary** — Actions, API, repos, security, admin, Copilot | -| `/github/docs` | 24,544 | 73.7 | Docs repo — markdown source, higher quality score | -| `/websites/cli_github` | 386 | 83.2 | GitHub CLI reference — gh commands, flags, examples | -| `/websites/cli_github_manual` | 478 | 44.0 | CLI manual — alternative, lower score | +1. Call `mcp_context7_resolve-library-id` with the technology name +2. Call `mcp_context7_query-docs` with the returned library ID and a specific query -## Query Effectiveness +--- -Good queries are specific: +## Writing Effective Queries + +Be specific — include version, intent, and language: ``` # ❌ Too broad "Azure Functions" -"VS Code extensions" "agent framework" # ✅ Specific "Azure Functions Python v2 programming model" "Cosmos DB partition key design best practices" -"VS Code webview API onDidReceiveMessage postMessage" "GitHub Actions workflow_dispatch inputs matrix strategy" "Aspire AddUvicornApp Python FastAPI integration" "DevUI serve agents tracing OpenTelemetry directory discovery" -"ChatCompletionAgent plugin tool calling multi-agent orchestration" "Agent Framework workflow conditional edges branching handoff" ``` Include context: - **Version** when relevant (`.NET 8`, `Aspire 13`, `VS Code 1.96`) - **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`, `API reference`) -- **Platform** for multi-platform docs (`Linux`, `Windows`, `macOS`) - **Language** for polyglot docs (`Python`, `TypeScript`, `C#`) - -### Agent Framework Query Examples - -``` -# DevUI — setup and running -microsoft_code_sample_search(language="python", query="DevUI agent framework serve agents tracing") -context7_query("/microsoft/agent-framework", "DevUI CLI options port host headless authentication") -context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI directory discovery agent workflow __init__.py") - -# DevUI — tracing and observability -context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI tracing OpenTelemetry debug panel span hierarchy") -microsoft_docs_search("configure tracing agent framework DevUI OTLP_ENDPOINT Jaeger") - -# DevUI — API and OpenAI SDK -context7_query("/microsoft/agent-framework", "DevUI POST /v1/responses OpenAI SDK entity_id streaming") -context7_query("/microsoft/agent-framework", "DevUI OpenAI proxy X-Proxy-Backend authentication") - -# DevUI — .NET integration -microsoft_code_sample_search(language="csharp", query="DevUI AddDevUI MapDevUI ASP.NET Core agent") -context7_query("/microsoft/agent-framework", "Microsoft.Agents.AI.DevUI AddDevUI MapDevUI ASP.NET Core") - -# Semantic Kernel agents -microsoft_code_sample_search(language="python", query="ChatCompletionAgent plugin AgentGroupChat") -context7_query("/websites/learn_microsoft_en-us_semantic-kernel", "ChatCompletionAgent plugin tool calling setup") -context7_query("/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent", "AgentGroupChat selection strategy termination") - -# Agent Framework workflows -context7_query("/websites/learn_microsoft_en-us_agent-framework", "workflow orchestration multi-agent handoff conditional edge") -microsoft_code_sample_search(language="csharp", query="agent framework workflow WorkflowBuilder AddEdge") - -# Cross-framework tracing -microsoft_docs_search("configure tracing AI agent frameworks Foundry Semantic Kernel Agent Framework") -``` - -## Workflow - -1. **Identify the technology** — is it Azure/Learn content, Agent Framework, Semantic Kernel, DevUI, VS Code, GitHub, or Aspire? -2. **Pick the right tool** — use the decision table above to choose between Microsoft Learn MCP and Context7 -3. **For Agent Frameworks** — use `microsoft_code_sample_search` for working code, then Context7 for deeper API docs: - - **DevUI how-to**: Context7 Learn website → code sample search for working examples → Context7 repo for API detail - - **Semantic Kernel**: Context7 Learn website + code sample search → Context7 repo for advanced samples - - **Workflow orchestration**: Microsoft Learn search → Context7 Learn website for patterns -4. **For Context7** — resolve the library ID first (if not cached), then query with a specific question -5. **For Microsoft Learn** — search first, then fetch full pages when you need complete tutorials or all config options -6. **Combine tools** — for cross-cutting questions (e.g., "deploy Aspire to Azure", "trace Agent Framework to Azure Monitor"), use multiple sources - -## When to Fetch Full Page (Microsoft Learn MCP) - -Use `microsoft_docs_fetch` after `microsoft_docs_search` when: -- **Tutorials** — need complete step-by-step instructions -- **Configuration guides** — need all options listed -- **Deep dives** — user wants comprehensive coverage -- **Search excerpt is cut off** — full context needed -- **Agent Framework DevUI docs** — `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` for complete setup guide - -## Why Use This - -- **Accuracy** — live docs and indexed sources, not stale training data -- **Completeness** — full tutorials, not fragments -- **Breadth** — covers the entire Microsoft ecosystem including VS Code, GitHub, Agent Framework repos, and Aspire that live outside learn.microsoft.com -- **Depth** — GitHub repo sources provide API-level detail ahead of published docs -- **Authority** — official Microsoft and first-party documentation