A11y Ally Skill: WCAG Audits with axe-core, pa11y and Lighthouse

What is the a11y-ally skill?

The a11y-ally skill is a WCAG audit workflow inside the Agentic QE Fleet repository. You invoke it as /a11y-ally with a URL, and your agent runs the whole pipeline without stopping to ask permission between steps.

Its core idea is that scanners flag problems and the agent supplies judgment. A button with no name becomes a fix such as "Add to wishlist", built from the icon class, the parent element and nearby text.

What the scan runs

• axe-core for ARIA and semantic issues, pa11y for contrast, links and HTML validation, and Lighthouse for accessibility scoring.
• All three run in parallel with per-tool timeouts of 60, 60 and 90 seconds.
• A failed tool is retried with exponential backoff, and the audit continues if at least one of the three succeeds.
• Coverage by success: about 95% with 3 of 3 tools, about 85% with 2 of 3 and about 70% with 1 of 3.

How findings are ranked

Each violation gets a user impact class: blocks usage, impairs usage or minor inconvenience. A priority score then divides impact weight times the share of users affected by the estimated fix hours, so cheap high-impact fixes rise to the top.

The skill ends with a production readiness check. A page is ready at a compliance score of 85% or higher, zero critical violations, fewer than 3 serious violations and every user journey reachable by keyboard.

Video and screen reader coverage

When the page contains videos, the skill downloads each one, extracts frames, has the agent look at every frame, and writes WebVTT captions and audio descriptions. A guide for testing with NVDA, VoiceOver and JAWS completes the manual side.

Who the a11y-ally skill is for

Best for

• Teams that want a full WCAG 2.2 audit of a live URL with fixes they can paste into code.
• Projects that need EU compliance mapping from WCAG to EN 301 549 and the EU Accessibility Act.
• Pages that include video, where captions and audio descriptions are required.

Not for

• A quick checklist pass, where the accessibility-testing skill in the same repository is a short reference card.
• Reviewing a design against WCAG 2.2 with severity labels, where the accessibility-audit skill fits.
• Reviewing a Figma design or a written description against WCAG 2.1 AA, where the accessibility-review skill fits.
• Small code edits to existing HTML, where the fixing-accessibility skill fits.
• Replacing manual testing, since the skill itself notes axe-core catches about 30% of WCAG issues.

How to install A11y Ally Skill: WCAG Audits with axe-core, pa11y and Lighthouse

npm install -g agentic-qe
cd your-project
aqe init --auto

1. Check the requirements

   The repository requires Node.js 22.13.0 or newer and npm 10.0.0 or newer, and works with the coding agent you already have configured.

2. Install and initialize

   Run the three commands above. aqe init --auto analyzes your project and configures the default Claude Code surface, including MCP. Run aqe health to check the setup.

3. Pick another client if needed

   Add a setup flag such as --with-codex, --with-cursor, --with-copilot, --with-cline or --with-windsurf to aqe init --auto.

4. Run an audit

   Invoke /a11y-ally https://example.com in your agent. The skill drives the browser through the qe-browser engine and falls back to pa11y and Lighthouse commands when axe alone is not enough.

Check that it loaded

After the run, open docs/accessibility-scans/ and look for a folder named after the page with audit-summary.md, remediation.md and violations.json inside.

Read the official instructions on GitHub

Key features

• Three-tool scanaxe-core, pa11y and Lighthouse run against the same URL, so the report combines ARIA and semantic checks, contrast and link checks, and a Lighthouse accessibility score.
• Parallel and resilient executionThe tools run through Promise.allSettled with 60, 60 and 90 second timeouts. Failed tools retry with exponential backoff, and one successful tool is enough to continue.
• Context-aware remediationThe agent reads icon classes, parent elements and nearby text to write specific names and labels, and uses vision on images to describe their actual content for alt text.
• Video accessibility pipelineVideos are downloaded, split into frames and described frame by frame. The output is a captions VTT file and an audio description VTT file for each video.
• User impact analysisViolations map to affected groups such as blind, low-vision, deaf and motor-impaired users, and are classed as blocks usage, impairs usage or minor inconvenience.
• ROI-based prioritiesPriority equals impact weight times users affected, divided by effort hours. Weights are Critical 10, Serious 7, Moderate 4 and Minor 1, and effort runs from 0.25 to 8 hours.
• Compliance thresholdsLevel A needs a 70% score with at most 5 serious issues, AA needs 85% with at most 3, and AAA needs 95% with none. Critical violations must be zero at every level.
• Report filesOutput goes to docs/accessibility-scans/{page-slug}/ as audit-summary.md, remediation.md, violations.json, implementation.md for videos, and the VTT files.
• EU compliance mappingA table maps WCAG criteria such as 1.1.1, 1.4.3 and 4.1.2 to their EN 301 549 clauses and the matching EU Accessibility Act principles.
• Multi-page and crawl modesAn optional script audits several URLs with up to 6 running at once, and a crawl mode follows same-domain links across up to 50 pages by default.

Frequently asked questions