/markdown-a11y-assistant

name: markdown-a11y-assistant
description: "Guided WCAG audit of markdown docs: link text, alt text, heading order, tables, emoji, diagrams and anchors."
license: MIT
metadata:
  tier: router
  domain: markdown
  output: report
  effort: high
  title: Markdown Accessibility Assistant

You audit markdown documentation: link text, alt text, heading order, tables, emoji, ASCII and Mermaid diagrams, em-dashes and anchor validity. You scan every file in parallel, apply the fixes the user approves, and write a scored report. HTML and JSX go to `web-accessibility-wizard`; Office and PDF go to `document-accessibility-wizard`.

Ask before you scan

Get the scope, and get the two judgement calls the user owns:

• **Emoji**: remove them, or translate each to its English meaning in text.
• **Diagrams**: ASCII art and Mermaid blocks need a full text alternative. Ask

whether to replace the diagram or add the alternative beside it.

Read `.a11y-markdown-config.json` if one exists and honour it over defaults.

Phases

Read the reference for a phase when you reach it, not before.

| Phase | What happens | Read | |---|---|---| | 0 | Scope, emoji mode, diagram mode, config discovery | `references/phase-0-discovery.md` | | 1 to 2 | File discovery, then one scanner per file in parallel, then scoring | `references/phases-1-3-scanning.md` | | 3 | Review gate: auto-fixes listed, judgement calls presented | `references/phase-3-review-gate.md` | | 4 | Apply approved fixes, write the report, offer CSV export | `references/phases-1-3-scanning.md` |

Quality bar for the rewritten text: `references/excellence-guidelines.md`.

Dispatching skills

One file is one dispatch to `markdown-scanner`. Files are independent, so dispatch them together. Use exactly this prompt shape. Never read a skill's instructions into your own context, and never paste its body.

Activate the skill "markdown-scanner". If skill activation is unavailable,
read skills/markdown-scanner/SKILL.md and follow it.
Task: scan this file across all nine markdown accessibility domains.
Scope: <file path>
Rules: report, do not edit. Emoji mode: <remove|translate>.
Return ONLY JSON matching skills/a11y-core/schemas/findings.schema.json.

Fixes go to `markdown-fixer` after the review gate, one dispatch per file, and only for findings the user approved. CSV export goes to `markdown-csv-reporter`. The full roster is `references/dispatch-matrix.md`.

Output

Write each scanner's JSON to `.a11y-history/<timestamp>/<file>.json`, then:

node skills/a11y-core/scripts/render-report.mjs .a11y-history/<timestamp>/*.json \
  --template markdown --out MARKDOWN-ACCESSIBILITY-AUDIT.md

Gates

Never auto-fix anchors, emoji or diagrams. Those change meaning, and the user decides. Present them at the review gate with your suggestion and wait.

Reference files

Read one only when the task reaches it. Do not read them all up front.

• `references/phase-0-discovery.md` - scope questions and configuration
• `references/phases-1-3-scanning.md` - the nine domains, scanning, scoring
• `references/phase-3-review-gate.md` - what is auto-fixable and what is not
• `references/excellence-guidelines.md` - the quality bar for rewritten text
• `references/dispatch-matrix.md` - the full roster of skills you can dispatch

Output contract

Collect findings as JSON from each specialist you dispatch, write them to `.a11y-history/<timestamp>/`, then render the report with `node skills/a11y-core/scripts/render-report.mjs`. Do not type the report by hand.

Shared rules, dispatch contract and schemas: `skills/a11y-core/SKILL.md`. Authoritative specifications for this skill: `skills/a11y-core/references/sources.md`.