Skip to content

Commit 45372f6

Browse files
ChrisMcKee1ChrisMcKee1
committed
refactor: Simplify microsoft-docs skill to default-Learn-with-exceptions pattern, add Aspire MCP version gate
1 parent e4c35f3 commit 45372f6

1 file changed

Lines changed: 56 additions & 156 deletions

File tree

‎skills/microsoft-docs/SKILL.md‎

Lines changed: 56 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -1,213 +1,113 @@
11
---
22
name: microsoft-docs
3-
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.'
3+
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.'
44
---
55

66
# Microsoft Docs
77

8-
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.
8+
Research skill for the Microsoft technology ecosystem. Covers learn.microsoft.com and documentation that lives outside it (VS Code, GitHub, Aspire, Agent Framework repos).
99

10-
## Tools
11-
12-
### Microsoft Learn MCP Server
13-
14-
| Tool | Use For |
15-
|------|---------|
16-
| `microsoft_docs_search` | Find documentation on learn.microsoft.com — concepts, guides, tutorials, configuration |
17-
| `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. |
18-
| `microsoft_docs_fetch` | Get full page content from a specific Microsoft docs URL (when search excerpts aren't enough) |
10+
---
1911

20-
### Context7 (broader coverage)
12+
## Default: Microsoft Learn MCP
2113

22-
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.
14+
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.
2315

24-
| Tool | Use For |
16+
| Tool | Purpose |
2517
|------|---------|
26-
| `mcp_context7_resolve-library-id` | Find the Context7 library ID for a technology (one-time per session) |
27-
| `mcp_context7_query-docs` | Query docs with a specific library ID — returns code snippets, explanations, and source links in a single call |
18+
| `microsoft_docs_search` | Search learn.microsoft.com — concepts, guides, tutorials, configuration |
19+
| `microsoft_code_sample_search` | Find working code snippets from Learn docs. Pass `language` (`python`, `csharp`, etc.) for best results |
20+
| `microsoft_docs_fetch` | Get full page content from a specific URL (when search excerpts aren't enough) |
2821

29-
### When GitHub Repo Sources (Context7) Beat Published Docs
22+
Use `microsoft_docs_fetch` after search when you need complete tutorials, all config options, or when search excerpts are truncated.
3023

31-
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:
24+
---
3225

33-
- **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
34-
- **Agent Framework .NET** — the repo has `Microsoft.Agents.AI.DevUI` integration code for ASP.NET Core before it appears on Learn
35-
- **Extension samples** — `/microsoft/vscode-extension-samples` has working projects not always linked from the VS Code API docs
26+
## Exceptions: When to Use Other Tools
3627

37-
**Rule of thumb:** query the **website source** for tutorials and concepts, then the **repo source** for API-level detail and the latest features.
28+
The following categories live **outside** learn.microsoft.com. Use the specified tool instead.
3829

39-
## When to Use Which Tool
30+
### .NET Aspire — Use Aspire MCP Server (preferred) or Context7
4031

41-
| Scenario | Best Tool | Why |
42-
|----------|-----------|-----|
43-
| Azure services, .NET, M365, Power Platform | `microsoft_docs_search` | Direct access to learn.microsoft.com |
44-
| Code samples for any Learn topic | `microsoft_code_sample_search` | Returns up to 20 working code snippets with links. Filter by language. |
45-
| Agent Framework — tutorials, concepts | `microsoft_docs_search` + Context7 Learn | Polished guides on learn.microsoft.com |
46-
| Agent Framework — DevUI setup, API, CLI | Context7 `/microsoft/agent-framework` | GitHub repo has detailed DevUI README with full API reference |
47-
| Agent Framework — DevUI tracing, directory discovery | Context7 `/websites/learn_microsoft_en-us_agent-framework` | Learn website has step-by-step guides |
48-
| 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 |
49-
| Semantic Kernel — source code, ADRs, design docs | Context7 `/microsoft/semantic-kernel` | GitHub repo has samples and architectural decisions |
50-
| VS Code features, settings, shortcuts | Context7 `/websites/code_visualstudio` | VS Code docs live on code.visualstudio.com, not Learn |
51-
| VS Code extension development / API | Context7 `/websites/code_visualstudio_api` | Extension API docs are separate from user docs |
52-
| GitHub Actions, repos, API, features | Context7 `/websites/github_en` | GitHub docs live on docs.github.com |
53-
| GitHub CLI (gh) | Context7 `/websites/cli_github` | CLI reference lives on cli.github.com |
54-
| .NET Aspire (AppHost, integrations, CLI) | Context7 `/microsoft/aspire.dev` | Aspire docs live on aspire.dev, not Learn |
55-
| Aspire community integrations (Go, Java) | Context7 `/communitytoolkit/aspire` | Community Toolkit is a separate repo |
56-
| Need full tutorial with all steps | `microsoft_docs_fetch` | Gets complete page content |
32+
Aspire docs live on **aspire.dev**, not Learn. The best tool depends on your Aspire CLI version:
5733

58-
## Context7 Library Reference
34+
**CLI 13.2+** (recommended) — The Aspire MCP server includes built-in docs search tools:
5935

60-
Call `mcp_context7_resolve-library-id` once per session to confirm IDs. Below are tested, quality-ranked sources.
36+
| MCP Tool | Description |
37+
|----------|-------------|
38+
| `list_docs` | Lists all available documentation from aspire.dev |
39+
| `search_docs` | Weighted lexical search across aspire.dev content |
40+
| `get_doc` | Retrieves a specific document by slug |
6141

62-
### Agent Frameworks
42+
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/
6343

64-
#### Microsoft Agent Framework
44+
**CLI 13.1** — The MCP server provides integration lookup (`list_integrations`, `get_integration_docs`) but **not** docs search. Fall back to Context7:
6545

66-
| Library ID | Snippets | Score | Coverage |
67-
|---|---|---|---|
68-
| `/websites/learn_microsoft_en-us_agent-framework` | 2,282 | 81.2 | **Primary for tutorials** — DevUI guides, directory discovery, tracing, AG-UI integration, workflow orchestration |
69-
| `/microsoft/agent-framework` | 1,177 | — | **Primary for API detail** — DevUI README (full REST API, CLI flags, auth, OpenAI proxy), .NET DevUI integration, samples |
46+
| Library ID | Use for |
47+
|---|---|
48+
| `/microsoft/aspire.dev` | Primary — guides, integrations, CLI reference, deployment |
49+
| `/dotnet/aspire` | Runtime source — API internals, implementation details |
50+
| `/communitytoolkit/aspire` | Community integrations — Go, Java, Node.js, Ollama |
7051

71-
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.
52+
### VS Code — Use Context7
7253

73-
**Use both** for comprehensive Agent Framework coverage: query the website source for "how to" guides, then the repo source for API-level specifics.
54+
VS Code docs live on **code.visualstudio.com**, not Learn.
7455

75-
##### Researching DevUI
56+
| Library ID | Use for |
57+
|---|---|
58+
| `/websites/code_visualstudio` | User docs — settings, features, debugging, remote dev |
59+
| `/websites/code_visualstudio_api` | Extension API — webviews, TreeViews, commands, contribution points |
7660

77-
DevUI docs are split across Learn and the GitHub repo. The best research strategy:
61+
### GitHub — Use Context7
7862

79-
| What You Need | Where to Search |
80-
|---------------|----------------|
81-
| Setup tutorial, directory structure | Context7 `/websites/learn_microsoft_en-us_agent-framework` — query "DevUI directory discovery" or "DevUI tracing" |
82-
| CLI flags, REST API endpoints, auth config | Context7 `/microsoft/agent-framework` — query "DevUI CLI options" or "DevUI POST /v1/responses" |
83-
| Working Python code snippets | `microsoft_code_sample_search` with `language: "python"` — query "DevUI agent framework serve" |
84-
| Working C# integration code | `microsoft_code_sample_search` with `language: "csharp"` — query "DevUI AddDevUI MapDevUI" |
85-
| Full setup guide in one page | `microsoft_docs_fetch` with URL `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` |
63+
GitHub docs live on **docs.github.com** and **cli.github.com**.
8664

87-
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.
65+
| Library ID | Use for |
66+
|---|---|
67+
| `/websites/github_en` | Actions, API, repos, security, admin, Copilot |
68+
| `/websites/cli_github` | GitHub CLI (`gh`) commands and flags |
8869

89-
### Azure & .NET (learn.microsoft.com)
70+
### Agent Framework — Use Learn MCP + Context7
9071

91-
| Library ID | Snippets | Score | Coverage |
92-
|---|---|---|---|
93-
| `/websites/learn_microsoft_en-us_azure` | 164,912 | 73.8 | All Azure services — compute, storage, networking, AI, databases |
94-
| `/microsoftdocs/azure-docs` | 61,791 | 76.7 | Azure docs GitHub repo — higher quality score |
95-
| `/websites/learn_microsoft_en-us` | 158,360 | 45.4 | All of Microsoft Learn — broadest but lower precision |
96-
| `/websites/learn_microsoft_en-us_dotnet_azure` | 1,156 | — | Azure SDK for .NET developers specifically |
72+
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.
9773

98-
### .NET Aspire
74+
| Library ID | Use for |
75+
|---|---|
76+
| `/websites/learn_microsoft_en-us_agent-framework` | Tutorials — DevUI guides, tracing, workflow orchestration |
77+
| `/microsoft/agent-framework` | API detail — DevUI REST endpoints, CLI flags, auth, .NET `AddDevUI`/`MapDevUI` |
9978

100-
| Library ID | Snippets | Score | Coverage |
101-
|---|---|---|---|
102-
| `/microsoft/aspire.dev` | 1,865 | 73.0 | **Primary** — official docs site repo, best quality, full Aspire 13+ coverage |
103-
| `/websites/aspire_dev` | 31,845 | 71.6 | Website crawl — massive but includes multilingual duplicates |
104-
| `/dotnet/aspire` | 1,185 | 71.5 | Runtime source — API internals, playground examples |
105-
| `/communitytoolkit/aspire` | 311 | 64.2 | Community integrations — Golang, Java, Node.js, Vite, Ollama |
106-
| `/dotnet/docs-aspire` | 482 | 71.4 | **Legacy** — being superseded by aspire.dev, avoid for tutorials |
79+
**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).
10780

108-
### Visual Studio Code
81+
---
10982

110-
| Library ID | Snippets | Score | Coverage |
111-
|---|---|---|---|
112-
| `/websites/code_visualstudio` | 6,288 | 80.4 | **Primary** — user docs, settings, features, debugging, remote dev |
113-
| `/websites/code_visualstudio_api` | 1,681 | 65.4 | Extension API — webviews, TreeViews, commands, contribution points |
114-
| `/microsoft/vscode-docs` | 8,289 | 87.9 | Docs repo — highest score, markdown source files |
115-
| `/microsoft/vscode-extension-samples` | 320 | 82.4 | Extension samples — working code examples |
83+
## Context7 Setup
11684

117-
### GitHub
85+
For any Context7 query, resolve the library ID first (one-time per session):
11886

119-
| Library ID | Snippets | Score | Coverage |
120-
|---|---|---|---|
121-
| `/websites/github_en` | 43,828 | 66.2 | **Primary** — Actions, API, repos, security, admin, Copilot |
122-
| `/github/docs` | 24,544 | 73.7 | Docs repo — markdown source, higher quality score |
123-
| `/websites/cli_github` | 386 | 83.2 | GitHub CLI reference — gh commands, flags, examples |
124-
| `/websites/cli_github_manual` | 478 | 44.0 | CLI manual — alternative, lower score |
87+
1. Call `mcp_context7_resolve-library-id` with the technology name
88+
2. Call `mcp_context7_query-docs` with the returned library ID and a specific query
12589

126-
## Query Effectiveness
90+
---
12791

128-
Good queries are specific:
92+
## Writing Effective Queries
93+
94+
Be specific — include version, intent, and language:
12995

13096
```
13197
# ❌ Too broad
13298
"Azure Functions"
133-
"VS Code extensions"
13499
"agent framework"
135100
136101
# ✅ Specific
137102
"Azure Functions Python v2 programming model"
138103
"Cosmos DB partition key design best practices"
139-
"VS Code webview API onDidReceiveMessage postMessage"
140104
"GitHub Actions workflow_dispatch inputs matrix strategy"
141105
"Aspire AddUvicornApp Python FastAPI integration"
142106
"DevUI serve agents tracing OpenTelemetry directory discovery"
143-
"ChatCompletionAgent plugin tool calling multi-agent orchestration"
144107
"Agent Framework workflow conditional edges branching handoff"
145108
```
146109

147110
Include context:
148111
- **Version** when relevant (`.NET 8`, `Aspire 13`, `VS Code 1.96`)
149112
- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`, `API reference`)
150-
- **Platform** for multi-platform docs (`Linux`, `Windows`, `macOS`)
151113
- **Language** for polyglot docs (`Python`, `TypeScript`, `C#`)
152-
153-
### Agent Framework Query Examples
154-
155-
```
156-
# DevUI — setup and running
157-
microsoft_code_sample_search(language="python", query="DevUI agent framework serve agents tracing")
158-
context7_query("/microsoft/agent-framework", "DevUI CLI options port host headless authentication")
159-
context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI directory discovery agent workflow __init__.py")
160-
161-
# DevUI — tracing and observability
162-
context7_query("/websites/learn_microsoft_en-us_agent-framework", "DevUI tracing OpenTelemetry debug panel span hierarchy")
163-
microsoft_docs_search("configure tracing agent framework DevUI OTLP_ENDPOINT Jaeger")
164-
165-
# DevUI — API and OpenAI SDK
166-
context7_query("/microsoft/agent-framework", "DevUI POST /v1/responses OpenAI SDK entity_id streaming")
167-
context7_query("/microsoft/agent-framework", "DevUI OpenAI proxy X-Proxy-Backend authentication")
168-
169-
# DevUI — .NET integration
170-
microsoft_code_sample_search(language="csharp", query="DevUI AddDevUI MapDevUI ASP.NET Core agent")
171-
context7_query("/microsoft/agent-framework", "Microsoft.Agents.AI.DevUI AddDevUI MapDevUI ASP.NET Core")
172-
173-
# Semantic Kernel agents
174-
microsoft_code_sample_search(language="python", query="ChatCompletionAgent plugin AgentGroupChat")
175-
context7_query("/websites/learn_microsoft_en-us_semantic-kernel", "ChatCompletionAgent plugin tool calling setup")
176-
context7_query("/websites/learn_microsoft_en-us_semantic-kernel_frameworks_agent", "AgentGroupChat selection strategy termination")
177-
178-
# Agent Framework workflows
179-
context7_query("/websites/learn_microsoft_en-us_agent-framework", "workflow orchestration multi-agent handoff conditional edge")
180-
microsoft_code_sample_search(language="csharp", query="agent framework workflow WorkflowBuilder AddEdge")
181-
182-
# Cross-framework tracing
183-
microsoft_docs_search("configure tracing AI agent frameworks Foundry Semantic Kernel Agent Framework")
184-
```
185-
186-
## Workflow
187-
188-
1. **Identify the technology** — is it Azure/Learn content, Agent Framework, Semantic Kernel, DevUI, VS Code, GitHub, or Aspire?
189-
2. **Pick the right tool** — use the decision table above to choose between Microsoft Learn MCP and Context7
190-
3. **For Agent Frameworks** — use `microsoft_code_sample_search` for working code, then Context7 for deeper API docs:
191-
- **DevUI how-to**: Context7 Learn website → code sample search for working examples → Context7 repo for API detail
192-
- **Semantic Kernel**: Context7 Learn website + code sample search → Context7 repo for advanced samples
193-
- **Workflow orchestration**: Microsoft Learn search → Context7 Learn website for patterns
194-
4. **For Context7** — resolve the library ID first (if not cached), then query with a specific question
195-
5. **For Microsoft Learn** — search first, then fetch full pages when you need complete tutorials or all config options
196-
6. **Combine tools** — for cross-cutting questions (e.g., "deploy Aspire to Azure", "trace Agent Framework to Azure Monitor"), use multiple sources
197-
198-
## When to Fetch Full Page (Microsoft Learn MCP)
199-
200-
Use `microsoft_docs_fetch` after `microsoft_docs_search` when:
201-
- **Tutorials** — need complete step-by-step instructions
202-
- **Configuration guides** — need all options listed
203-
- **Deep dives** — user wants comprehensive coverage
204-
- **Search excerpt is cut off** — full context needed
205-
- **Agent Framework DevUI docs** — `https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/` for complete setup guide
206-
207-
## Why Use This
208-
209-
- **Accuracy** — live docs and indexed sources, not stale training data
210-
- **Completeness** — full tutorials, not fragments
211-
- **Breadth** — covers the entire Microsoft ecosystem including VS Code, GitHub, Agent Framework repos, and Aspire that live outside learn.microsoft.com
212-
- **Depth** — GitHub repo sources provide API-level detail ahead of published docs
213-
- **Authority** — official Microsoft and first-party documentation

0 commit comments

Comments
 (0)