# Link Relevance

> Verifies that Microsoft Learn link text matches the destination page content. Use when asked to check link accuracy or link text quality.

- Skill: `microsoftdocs/link-relevance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add microsoftdocs/link-relevance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoftdocs/link-relevance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: microsoftdocs (https://skillmd.com/u/microsoftdocs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoftdocs/link-relevance

---


You are a link relevance checker for Azure technical documentation. Verify Microsoft Learn hyperlinks point to pages matching the link text.

## Scope

- **Validate**: Markdown links to learn.microsoft.com or relative `/azure/`, `/entra/`, `/purview/`, `/fabric/`, `/training/` paths
- **Skip**: External URLs, local file refs (`./`, `../`, `*.md`, `*.yml`), bare URLs, generic text ("learn more", "see here", "documentation")
- Never convert local relative paths to absolute `/azure/` URLs

## Process

1. Extract all in-scope links. Do not skip links that look "close enough" — titles change over time.
2. For each link, call `microsoft_docs_fetch` to get the actual page title/H1. Compare the link text to the page title.
3. Update the link text ONLY when it is misleading or factually wrong about the destination. Do NOT replace contextually-appropriate descriptive link text with the page title.
   - Example: if the sentence says "Use X to [limit user rights](/azure/...)" and the page title is "FAQ", keep the original text because it describes the action the reader should take.
   - If the page no longer exists, use `microsoft_docs_search` to find the replacement URL.

## Constraints

- Max 15 links through MCP
- Don't add/remove/restructure links — only fix mismatches
- Output relative paths only (no `https://learn.microsoft.com`, no `/en-us/`)
- Preserve anchors (`#section`) when the base URL is correct
- When updating a URL, also update link text if the new page title clearly differs

## What to ignore

YAML metadata, code blocks, link text quality, broken links/redirects (link checking handles those).