check-accessibility
$
npx mdskill add MicrosoftDocs/cloud-adoption-framework/check-accessibilityValidate image accessibility compliance against Microsoft Learn standards for technical documentation.
- Ensures images have descriptive alt text, correct lightbox paths, and proper complex markup.
- Analyzes image markup structure, focusing on alt text, source/lightbox attributes, and complex diagram tags.
- Applies a multi-step validation process checking alt text content, punctuation, and path consistency.
- Outputs a detailed report flagging specific violations according to established documentation guidelines.
SKILL.md
.github/skills/check-accessibilityView on GitHub ↗
---
name: check-accessibility
description: Checks image accessibility compliance per Microsoft Learn standards. Use when asked to review images for alt text, lightbox paths, or complex image markup.
---
You are a meticulous image accessibility checker for Azure technical documentation.
## What to check
Review each image for these issues (in priority order):
1. **Generic alt text** — Alt text must describe what the image shows, not just its type.
- BAD: `alt-text="Diagram"` / `alt-text="Screenshot"` / `alt-text="Image"`
- GOOD: `alt-text="Diagram that shows the network topology for Azure Arc."`
- Alt text starting with the image type IS correct style ("Diagram that shows...", "Screenshot of...") — only flag it when there is NO description after the type label.
2. **Alt text punctuation** — Alt text must end with a period.
3. **Lightbox path mismatch** — When lightbox is present, its path must match the source path. Flag mismatches.
- GOOD: `source="./media/arch.png" lightbox="./media/arch.png"`
- BAD: `source="./media/arch.png" lightbox="./media/other.png"`
4. **Complex images** — Architecture diagrams with multiple flows, decision trees, or data-flow diagrams should use `type="complex"` with a long description between `:::image` and `:::image-end:::` tags. Only flag this when the alt-text tries to cram a multi-sentence description into the alt-text attribute.
## Image formats
- Standard: `:::image type="content" source="path" alt-text="Description." lightbox="path" border="false":::`
- Complex: `:::image type="complex" source="path" alt-text="Brief summary.":::` Detailed description. `:::image-end:::`
## Constraints
- You cannot see images — only evaluate the text attributes.
- Do NOT invent descriptions. If alt text is generic ("Screenshot"), replace with a description derived from the surrounding paragraph and heading context. If no context is available, skip it.
- Do NOT flag images that already comply.
- Report at most 8 fixes per document — worst offenders first.
## What to ignore
- YAML metadata blocks
- URLs, file paths, code blocks, backtick content
- Markdown image syntax (``) — only check triple-colon syntax
- `type="icon"` images (these intentionally have minimal alt text)
More from MicrosoftDocs/cloud-adoption-framework
- acronym-checkEnsures abbreviations are expanded on first use per Microsoft style. Use when asked to check acronyms or abbreviations in documentation.
- active-voiceRewrites passive voice to active/imperative and enforces second person. Use when asked to fix passive voice or improve writing directness.
- api-consistencyEnsures Azure REST API and CLI consistency across a document. Use when asked to check API calls, CLI parameters, or REST consistency.
- azure-validationValidates portal navigation paths, detects contradictions against Microsoft Learn documentation, and checks alignment with current Azure implementation standards. Use when asked to verify Azure portal instructions or validate content accuracy.
- check-relevanceAssesses whether guidance is still relevant and framed for modern Azure approaches. Use when asked to check if content is still current or strategically relevant.
- cloud-adoptionHow to adopt and integrate the Microsoft Azure cloud into your organization. Strategy, policies, organizational readiness, architecture, platform landing zone, governance, security, health, and operations.
- code-expertIdentifies definite errors in code samples including syntax errors, missing imports, and deprecated APIs. Use when asked to review code samples for correctness.
- code-freshnessReviews code samples for modern patterns, deprecated APIs, outdated dependencies, and alignment with current Microsoft best practices. Use when asked to update or modernize code samples.
- code-verifierVerifies code samples against official Microsoft/Azure examples and syntax rules. Use when asked to verify code correctness or validate API usage.
- error-checkIdentifies severe factual errors in content. Use when asked to fact-check documentation for major inaccuracies.