---
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.

```text
Run the skill "markdown-scanner": read <skills-root>/markdown-scanner/SKILL.md
and follow it. It is a specialist, hidden from the skill catalog to save
context; running it this way is intended. Replace a leading skills/ in any path it
names with <skills-root>/.
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.
```

<skills-root> is the absolute path of the folder that holds this skill's own
folder: the parent of the directory this SKILL.md was loaded from. Send it
resolved, never as the relative path skills/...: the subagent starts in the
user's project, where no skills/ folder exists. If the load path is not shown,
it is the folder that contains a11y-core/SKILL.md.

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:

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

## Gates

Never auto-fix anchors or diagrams, and fix emoji only in the emoji mode the
user chose in Phase 0. These change meaning, and the user decides. Present
anything else 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-root>/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`.