From 6756760f4d9cc8ca0c6abd4153d56bfc74dd81f3 Mon Sep 17 00:00:00 2001 From: Tianqi Zhang Date: Fri, 13 Mar 2026 13:53:32 +0800 Subject: [PATCH 1/3] Add Learn CLI option to microsoft-docs skills --- skills/microsoft-code-reference/SKILL.md | 24 ++++++++++++- skills/microsoft-docs/SKILL.md | 21 +++++++++++ skills/microsoft-skill-creator/SKILL.md | 35 ++++++++++++++++++- .../references/skill-templates.md | 12 +++++++ 4 files changed, 90 insertions(+), 2 deletions(-) diff --git a/skills/microsoft-code-reference/SKILL.md b/skills/microsoft-code-reference/SKILL.md index 41c4685db..5fb3cf8cd 100644 --- a/skills/microsoft-code-reference/SKILL.md +++ b/skills/microsoft-code-reference/SKILL.md @@ -1,7 +1,8 @@ --- 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) +context: fork +compatibility: Works best with Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp). Can also use the mslearn CLI as a fallback. --- # Microsoft Code Reference @@ -76,3 +77,24 @@ Before generating code using Microsoft SDKs, verify it's correct: 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. + +## CLI Alternative + +If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: + +```bash +# Run directly (no install needed) +npx @microsoft/learn-cli search "BlobClient UploadAsync Azure.Storage.Blobs" + +# Or install globally, then run +npm install -g @microsoft/learn-cli +mslearn search "BlobClient UploadAsync Azure.Storage.Blobs" +``` + +| MCP Tool | CLI Command | +|----------|-------------| +| `microsoft_docs_search(query: "...")` | `mslearn search "..."` | +| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` | +| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` | + +Pass `--json` to `search` or `code-search` to get raw JSON output for further processing. diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index 201b5e008..f60ebebe5 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -21,6 +21,27 @@ Use these tools for **everything on learn.microsoft.com** — Azure, .NET, M365, Use `microsoft_docs_fetch` after search when you need complete tutorials, all config options, or when search excerpts are truncated. +### CLI Alternative + +If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: + +```bash +# Run directly (no install needed) +npx @microsoft/learn-cli search "BlobClient UploadAsync Azure.Storage.Blobs" + +# Or install globally, then run +npm install -g @microsoft/learn-cli +mslearn search "BlobClient UploadAsync Azure.Storage.Blobs" +``` + +| MCP Tool | CLI Command | +|----------|-------------| +| `microsoft_docs_search(query: "...")` | `mslearn search "..."` | +| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` | +| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` | + +Pass `--json` to `search` or `code-search` to get raw JSON output for further processing. + --- ## Exceptions: When to Use Other Tools diff --git a/skills/microsoft-skill-creator/SKILL.md b/skills/microsoft-skill-creator/SKILL.md index 545c40bde..433b66c96 100644 --- a/skills/microsoft-skill-creator/SKILL.md +++ b/skills/microsoft-skill-creator/SKILL.md @@ -2,7 +2,7 @@ name: microsoft-skill-creator description: Create agent skills for Microsoft technologies using Learn MCP tools. Use when users want to create a skill that teaches agents about any Microsoft technology, library, framework, or service (Azure, .NET, M365, VS Code, Bicep, etc.). Investigates topics deeply, then generates a hybrid skill storing essential knowledge locally while enabling dynamic deeper investigation. context: fork -compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp) +compatibility: Works best with Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp). Can also use the mslearn CLI as a fallback. --- # Microsoft Skill Creator @@ -37,6 +37,27 @@ skill-name/ | `microsoft_docs_fetch` | Get full page content | Deep dive into important pages | | `microsoft_code_sample_search` | Find code examples | Get implementation patterns | +### CLI Alternative + +If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: + +```bash +# Run directly (no install needed) +npx @microsoft/learn-cli search "semantic kernel overview" + +# Or install globally, then run +npm install -g @microsoft/learn-cli +mslearn search "semantic kernel overview" +``` + +| MCP Tool | CLI Command | +|----------|-------------| +| `microsoft_docs_search(query: "...")` | `mslearn search "..."` | +| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` | +| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` | + +Generated skills should include this same CLI fallback table so agents can use either path. + ## Creation Process ### Step 1: Investigate the Topic @@ -214,4 +235,16 @@ See [getting-started/hello-kernel.cs](sample_codes/getting-started/hello-kernel. | Plugin development | `microsoft_docs_search(query="semantic kernel plugins custom functions")` | | Planners | `microsoft_docs_search(query="semantic kernel planner")` | | Memory | `microsoft_docs_fetch(url="https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/agent-memory")` | + +## CLI Alternative + +If the Learn MCP server is not available, use the `mslearn` CLI instead: + +| MCP Tool | CLI Command | +|----------|-------------| +| `microsoft_docs_search(query: "...")` | `mslearn search "..."` | +| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` | +| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` | + +Run directly with `npx @microsoft/learn-cli ` or install globally with `npm install -g @microsoft/learn-cli`. ``` diff --git a/skills/microsoft-skill-creator/references/skill-templates.md b/skills/microsoft-skill-creator/references/skill-templates.md index dc2343008..9037ce6f1 100644 --- a/skills/microsoft-skill-creator/references/skill-templates.md +++ b/skills/microsoft-skill-creator/references/skill-templates.md @@ -2,6 +2,18 @@ Ready-to-use templates for different types of Microsoft technologies. +## CLI Alternative for MCP Tools + +All templates below use MCP tool calls (e.g., `microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search`). If the Learn MCP server is not available, replace them with CLI equivalents: + +| MCP Tool | CLI Command | +|----------|-------------| +| `microsoft_docs_search(query: "...")` | `mslearn search "..."` | +| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` | +| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` | + +Run directly with `npx @microsoft/learn-cli ` or install globally with `npm install -g @microsoft/learn-cli`. + ## Template 1: SDK/Library Skill For client libraries, SDKs, and programming frameworks. From 7a01bd7ecb678dd4bf9f6903c729777b00a2aa69 Mon Sep 17 00:00:00 2001 From: Tianqi Zhang Date: Fri, 13 Mar 2026 14:06:18 +0800 Subject: [PATCH 2/3] avoid context fork --- skills/microsoft-code-reference/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/microsoft-code-reference/SKILL.md b/skills/microsoft-code-reference/SKILL.md index 5fb3cf8cd..f4d62e9d4 100644 --- a/skills/microsoft-code-reference/SKILL.md +++ b/skills/microsoft-code-reference/SKILL.md @@ -1,7 +1,6 @@ --- 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. -context: fork compatibility: Works best with Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp). Can also use the mslearn CLI as a fallback. --- From 1a4c51cdc073c03452fca724cc61689865a6b852 Mon Sep 17 00:00:00 2001 From: Tianqi Zhang Date: Fri, 13 Mar 2026 14:17:17 +0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/microsoft-code-reference/SKILL.md | 4 ++-- skills/microsoft-docs/SKILL.md | 2 +- skills/microsoft-skill-creator/SKILL.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/microsoft-code-reference/SKILL.md b/skills/microsoft-code-reference/SKILL.md index f4d62e9d4..24de66989 100644 --- a/skills/microsoft-code-reference/SKILL.md +++ b/skills/microsoft-code-reference/SKILL.md @@ -79,9 +79,9 @@ For simple lookups, step 1 alone may suffice. For complex API usage, complete al ## CLI Alternative -If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: +If the Learn MCP server is not available, use the `mslearn` CLI from a terminal or shell (for example, Bash, PowerShell, or cmd) instead: -```bash +```sh # Run directly (no install needed) npx @microsoft/learn-cli search "BlobClient UploadAsync Azure.Storage.Blobs" diff --git a/skills/microsoft-docs/SKILL.md b/skills/microsoft-docs/SKILL.md index f60ebebe5..bbfd424c6 100644 --- a/skills/microsoft-docs/SKILL.md +++ b/skills/microsoft-docs/SKILL.md @@ -23,7 +23,7 @@ Use `microsoft_docs_fetch` after search when you need complete tutorials, all co ### CLI Alternative -If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: +If the Learn MCP server is not available, use the `mslearn` CLI from your terminal or shell (for example, Bash, PowerShell, or cmd) instead: ```bash # Run directly (no install needed) diff --git a/skills/microsoft-skill-creator/SKILL.md b/skills/microsoft-skill-creator/SKILL.md index 433b66c96..139faf235 100644 --- a/skills/microsoft-skill-creator/SKILL.md +++ b/skills/microsoft-skill-creator/SKILL.md @@ -39,7 +39,7 @@ skill-name/ ### CLI Alternative -If the Learn MCP server is not available, use the `mslearn` CLI via Bash instead: +If the Learn MCP server is not available, use the `mslearn` CLI from a terminal or shell (for example, Bash, PowerShell, or cmd) instead: ```bash # Run directly (no install needed)