fix: repair broken skill references, fence nesting, and invisible unicode (#2568)

While implementing the Agent Plugin v1 spec in https://github.com/stbenjam/skillsaw/pull/483, I used this repository as a canonical real-world source for tests. Along the way its checks surfaced genuine correctness issues worth fixing regardless of tooling:

- Internal links that do not resolve (22): wrong relative paths, links whose targets are runtime output paths rather than bundled files (now inline code), a schemeless external URL parsed as a relative path, and links to files that do not exist (removed).

- Bundled skill files never referenced from their SKILL.md (14): each is now cited from the section where it is used, so nothing ships unreachable from the skill's instructions.

- Unclosed or mis-nested code fences (11): markdown templates embedding code blocks now use four-backtick outer fences so inner fences nest instead of closing the template early and leaking example content as live markdown; also removed stray orphan fences and closed an unterminated block at end of file.

- Invisible unicode (1): removed a zero-width space from a code example, a copy-paste artifact invisible to reviewers.
This commit is contained in:
Stephen Benjamin
2026-08-06 22:01:43 -04:00
committed by GitHub
parent 11deaef597
commit 4214189287
28 changed files with 55 additions and 50 deletions
@@ -18,7 +18,7 @@ Run directly with `npx @microsoft/learn-cli <command>` or install globally with
For client libraries, SDKs, and programming frameworks.
```markdown
````markdown
---
name: {sdk-name}
description: {What it does}. Use when agents need to {primary task} with {technology context}. Supports {languages/platforms}.
@@ -83,7 +83,7 @@ See [best-practices.md](references/best-practices.md) for detailed guidance.
| {Advanced topic 1} | `microsoft_docs_search(query="{sdk} {topic}")` |
| {Advanced topic 2} | `microsoft_docs_fetch(url="{url}")` |
| {Code examples} | `microsoft_code_sample_search(query="{sdk} {scenario}", language="{lang}")` |
```
````
---
@@ -91,7 +91,7 @@ See [best-practices.md](references/best-practices.md) for detailed guidance.
For Azure services and cloud resources.
```markdown
````markdown
---
name: {service-name}
description: Work with {Azure Service}. Use when agents need to {primary capabilities}. Covers provisioning, configuration, and SDK usage.
@@ -169,7 +169,7 @@ For more issues: `microsoft_docs_search(query="{service} troubleshoot {symptom}"
| REST API | `microsoft_docs_fetch(url="{url}")` |
| ARM/Bicep | `microsoft_docs_search(query="{service} bicep template")` |
| Security | `microsoft_docs_search(query="{service} security best practices")` |
```
````
---
@@ -177,7 +177,7 @@ For more issues: `microsoft_docs_search(query="{service} troubleshoot {symptom}"
For development frameworks and platforms (e.g., ASP.NET, MAUI, Blazor).
```markdown
````markdown
---
name: {framework-name}
description: Build {type of apps} with {Framework}. Use when agents need to create, modify, or debug {framework} applications.
@@ -248,7 +248,7 @@ For detailed deployment: `microsoft_docs_search(query="{framework} deploy {targe
| {Advanced feature} | `microsoft_docs_search(query="{framework} {feature}")` |
| {Integration} | `microsoft_docs_fetch(url="{url}")` |
| {Samples} | `microsoft_code_sample_search(query="{framework} {scenario}")` |
```
````
---
@@ -256,7 +256,7 @@ For detailed deployment: `microsoft_docs_search(query="{framework} deploy {targe
For APIs, protocols, and specifications (e.g., Microsoft Graph, OOXML).
```markdown
````markdown
---
name: {api-name}
description: Interact with {API/Protocol}. Use when agents need to {primary operations}. Covers authentication, endpoints, and common operations.
@@ -321,7 +321,7 @@ description: Interact with {API/Protocol}. Use when agents need to {primary oper
| Full endpoint reference | `microsoft_docs_fetch(url="{url}")` |
| Permissions | `microsoft_docs_search(query="{api} permissions {resource}")` |
| SDKs | `microsoft_docs_search(query="{api} SDK {language}")` |
```
````
---