---
name: community-access-markdown-a11y-assistant
description: "Guided WCAG audit of markdown docs: link text, alt text, heading order, tables, emoji, diagrams and anchors."
license: "MIT"
metadata:
  decimalai-skill-id: "a13e84c9-e625-4adb-a700-3cd7ebab2687"
  decimalai-version-id: "fd1c3445-db62-4e4a-b034-eaf67da27b3c"
  decimalai-version: "3"
  decimalai-body-sha256: "10c6441041d5bd8eb36257ed7d7cbd57a76430f91970dade5416cde1904828fc"
  decimalai-name: "community-access/markdown-a11y-assistant"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "documentation"
  decimalai-source: "https://app.decimal.ai/s/community-access-markdown-a11y-assistant@3/SKILL.md"
---
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
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:

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