Skip to content

Commit c62bf6a

Browse files
aaronpowellaaronpowell
authored
Merge pull request #673 from ChrisMcKee1/update-microsoft-docs-skill
feat: Expand microsoft-docs skill to cover the full Microsoft documentation ecosystem
2 parents d99ba71 + 3402d26 commit c62bf6a

File tree

2 files changed

+91
-34
lines changed

2 files changed

+91
-34
lines changed

‎docs/README.skills.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
4343
| [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 |
4444
| [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 |
4545
| [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 |
46-
| [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 |
46+
| [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 |
4747
| [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 |
4848
| [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`<br />`references/component-patterns.md`<br />`references/platform-guidelines.md`<br />`references/setup-troubleshooting.md` |
4949
| [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 |

‎skills/microsoft-docs/SKILL.md‎

Lines changed: 90 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,113 @@
11
---
22
name: microsoft-docs
3-
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.
4-
compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp)
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.'
54
---
65

76
# Microsoft Docs
87

9-
## Tools
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).
109

11-
| Tool | Use For |
10+
---
11+
12+
## Default: Microsoft Learn MCP
13+
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.
15+
16+
| Tool | Purpose |
1217
|------|---------|
13-
| `microsoft_docs_search` | Find documentation—concepts, guides, tutorials, configuration |
14-
| `microsoft_docs_fetch` | Get full page content (when search excerpts aren't enough) |
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) |
21+
22+
Use `microsoft_docs_fetch` after search when you need complete tutorials, all config options, or when search excerpts are truncated.
23+
24+
---
25+
26+
## Exceptions: When to Use Other Tools
27+
28+
The following categories live **outside** learn.microsoft.com. Use the specified tool instead.
29+
30+
### .NET Aspire — Use Aspire MCP Server (preferred) or Context7
31+
32+
Aspire docs live on **aspire.dev**, not Learn. The best tool depends on your Aspire CLI version:
33+
34+
**CLI 13.2+** (recommended) — The Aspire MCP server includes built-in docs search tools:
35+
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 |
41+
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/
43+
44+
**CLI 13.1** — The MCP server provides integration lookup (`list_integrations`, `get_integration_docs`) but **not** docs search. Fall back to Context7:
45+
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 |
51+
52+
### VS Code — Use Context7
53+
54+
VS Code docs live on **code.visualstudio.com**, not Learn.
1555

16-
## When to Use
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 |
1760

18-
- **Understanding concepts** — "How does Cosmos DB partitioning work?"
19-
- **Learning a service** — "Azure Functions overview", "Container Apps architecture"
20-
- **Finding tutorials** — "quickstart", "getting started", "step-by-step"
21-
- **Configuration options** — "App Service configuration settings"
22-
- **Limits & quotas** — "Azure OpenAI rate limits", "Service Bus quotas"
23-
- **Best practices** — "Azure security best practices"
61+
### GitHub — Use Context7
2462

25-
## Query Effectiveness
63+
GitHub docs live on **docs.github.com** and **cli.github.com**.
2664

27-
Good queries are specific:
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 |
69+
70+
### Agent Framework — Use Learn MCP + Context7
71+
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.
73+
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` |
78+
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).
80+
81+
---
82+
83+
## Context7 Setup
84+
85+
For any Context7 query, resolve the library ID first (one-time per session):
86+
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
89+
90+
---
91+
92+
## Writing Effective Queries
93+
94+
Be specific — include version, intent, and language:
2895

2996
```
3097
# ❌ Too broad
3198
"Azure Functions"
99+
"agent framework"
32100
33101
# ✅ Specific
34102
"Azure Functions Python v2 programming model"
35103
"Cosmos DB partition key design best practices"
36-
"Container Apps scaling rules KEDA"
104+
"GitHub Actions workflow_dispatch inputs matrix strategy"
105+
"Aspire AddUvicornApp Python FastAPI integration"
106+
"DevUI serve agents tracing OpenTelemetry directory discovery"
107+
"Agent Framework workflow conditional edges branching handoff"
37108
```
38109

39110
Include context:
40-
- **Version** when relevant (`.NET 8`, `EF Core 8`)
41-
- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`)
42-
- **Platform** for multi-platform docs (`Linux`, `Windows`)
43-
44-
## When to Fetch Full Page
45-
46-
Fetch after search when:
47-
- **Tutorials** — need complete step-by-step instructions
48-
- **Configuration guides** — need all options listed
49-
- **Deep dives** — user wants comprehensive coverage
50-
- **Search excerpt is cut off** — full context needed
51-
52-
## Why Use This
53-
54-
- **Accuracy** — live docs, not training data that may be outdated
55-
- **Completeness** — tutorials have all steps, not fragments
56-
- **Authority** — official Microsoft documentation
111+
- **Version** when relevant (`.NET 8`, `Aspire 13`, `VS Code 1.96`)
112+
- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`, `API reference`)
113+
- **Language** for polyglot docs (`Python`, `TypeScript`, `C#`)

0 commit comments

Comments
 (0)