Add Learn CLI fallback to all skills (#123)

* Add Learn CLI alternative to all skills

Add CLI fallback sections to microsoft-docs, microsoft-code-reference,
and microsoft-skill-creator skills so agents can use the mslearn CLI
via Bash when the Learn MCP server is not available. Each section maps
MCP tools to their CLI equivalents and shows both npx and global install
usage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update compatibility metadata, fix section order, and add CLI to templates

- Update compatibility frontmatter in all 3 skills to reflect CLI fallback
- Move "Why Use This" above "CLI Alternative" in microsoft-docs skill
- Add CLI Alternative section to the example generated skill in skill-creator
- Add CLI mapping table to the top of skill-templates.md so generated
  skills can reference CLI equivalents without duplicating in every template

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: TianqiZhang

skills/microsoft-code-reference/SKILL.md

@@ -2,7 +2,7 @@
 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: 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 Code Reference
@@ -77,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.

skills/microsoft-docs/SKILL.md

@@ -2,7 +2,7 @@
 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.
 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 Docs
@@ -55,3 +55,23 @@ Fetch after search when:
 - **Accuracy** — live docs, not training data that may be outdated
 - **Completeness** — tutorials have all steps, not fragments
 - **Authority** — official Microsoft documentation
+
+## 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 "azure functions timeout"
+
+# Or install globally, then run
+npm install -g @microsoft/learn-cli
+mslearn search "azure functions timeout"
+```
+
+| MCP Tool | CLI Command |
+|----------|-------------|
+| `microsoft_docs_search(query: "...")` | `mslearn search "..."` |
+| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` |
+
+The `fetch` command also supports `--section <heading>` to extract a single section and `--max-chars <number>` to truncate output.

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 <command>` or install globally with `npm install -g @microsoft/learn-cli`.
 ```

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 <command>` or install globally with `npm install -g @microsoft/learn-cli`.
+
 ## Template 1: SDK/Library Skill
 
 For client libraries, SDKs, and programming frameworks.