diff --git a/docs/README.skills.md b/docs/README.skills.md index b83420f11..18c26caac 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -26,6 +26,8 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | [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` | | [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` | | [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` | +| [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 | | [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 | | [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md) | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | diff --git a/skills/microsoft-code-reference/SKILL.md b/skills/microsoft-code-reference/SKILL.md new file mode 100644 index 000000000..41c4685db --- /dev/null +++ b/skills/microsoft-code-reference/SKILL.md @@ -0,0 +1,78 @@ +--- +name: microsoft-code-reference +description: 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. +compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp) +--- + +# Microsoft Code Reference + +## Tools + +| Need | Tool | Example | +|------|------|---------| +| API method/class lookup | `microsoft_docs_search` | `"BlobClient UploadAsync Azure.Storage.Blobs"` | +| Working code sample | `microsoft_code_sample_search` | `query: "upload blob managed identity", language: "python"` | +| Full API reference | `microsoft_docs_fetch` | Fetch URL from `microsoft_docs_search` (for overloads, full signatures) | + +## Finding Code Samples + +Use `microsoft_code_sample_search` to get official, working examples: + +``` +microsoft_code_sample_search(query: "upload file to blob storage", language: "csharp") +microsoft_code_sample_search(query: "authenticate with managed identity", language: "python") +microsoft_code_sample_search(query: "send message service bus", language: "javascript") +``` + +**When to use:** +- Before writing code—find a working pattern to follow +- After errors—compare your code against a known-good sample +- Unsure of initialization/setup—samples show complete context + +## API Lookups + +``` +# Verify method exists (include namespace for precision) +"BlobClient UploadAsync Azure.Storage.Blobs" +"GraphServiceClient Users Microsoft.Graph" + +# Find class/interface +"DefaultAzureCredential class Azure.Identity" + +# Find correct package +"Azure Blob Storage NuGet package" +"azure-storage-blob pip package" +``` + +Fetch full page when method has multiple overloads or you need complete parameter details. + +## Error Troubleshooting + +Use `microsoft_code_sample_search` to find working code samples and compare with your implementation. For specific errors, use `microsoft_docs_search` and `microsoft_docs_fetch`: + +| Error Type | Query | +|------------|-------| +| Method not found | `"[ClassName] methods [Namespace]"` | +| Type not found | `"[TypeName] NuGet package namespace"` | +| Wrong signature | `"[ClassName] [MethodName] overloads"` → fetch full page | +| Deprecated warning | `"[OldType] migration v12"` | +| Auth failure | `"DefaultAzureCredential troubleshooting"` | +| 403 Forbidden | `"[ServiceName] RBAC permissions"` | + +## When to Verify + +Always verify when: +- Method name seems "too convenient" (`UploadFile` vs actual `Upload`) +- Mixing SDK versions (v11 `CloudBlobClient` vs v12 `BlobServiceClient`) +- Package name doesn't follow conventions (`Azure.*` for .NET, `azure-*` for Python) +- Using an API for the first time + +## Validation Workflow + +Before generating code using Microsoft SDKs, verify it's correct: + +1. **Confirm method or package exists** — `microsoft_docs_search(query: "[ClassName] [MethodName] [Namespace]")` +2. **Fetch full details** (for overloads/complex params) — `microsoft_docs_fetch(url: "...")` +3. **Find working sample** — `microsoft_code_sample_search(query: "[task]", language: "[lang]")` + +For simple lookups, step 1 alone may suffice. For complex API usage, complete all three steps. diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md new file mode 100644 index 000000000..92f523b7d --- /dev/null +++ b/skills/microsoft-docs/SKILL.md @@ -0,0 +1,56 @@ +--- +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) +--- + +# Microsoft Docs + +## Tools + +| 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) | + +## When to Use + +- **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" + +## Query Effectiveness + +Good queries are specific: + +``` +# ❌ Too broad +"Azure Functions" + +# ✅ Specific +"Azure Functions Python v2 programming model" +"Cosmos DB partition key design best practices" +"Container Apps scaling rules KEDA" +``` + +Include context: +- **Version** when relevant (`.NET 8`, `EF Core 8`) +- **Task intent** (`quickstart`, `tutorial`, `overview`, `limits`) +- **Platform** for multi-platform docs (`Linux`, `Windows`) + +## When to Fetch Full Page + +Fetch after 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 + +## Why Use This + +- **Accuracy** — live docs, not training data that may be outdated +- **Completeness** — tutorials have all steps, not fragments +- **Authority** — official Microsoft documentation