Drop-in accessibility audit for AI coding agents. Point it at any web project and get a WCAG 2.1 AA compliance report with prioritized findings, actionable fix suggestions, and progress tracking — without the target project needing any accessibility tooling installed.
Developers and AI coding agents who need a WCAG 2.1 AA audit of any web project without installing accessibility tooling into it.
Most accessibility tools require manual setup and produce raw violation dumps with no prioritization. Skill A11y Audit is a drop-in WCAG 2.1 AA audit that runs against any web project and returns prioritized, actionable fixes.
Most accessibility tools require manual setup, produce raw violation dumps, and leave you to figure out what to fix first. This skill:
- Discovers your site structure automatically — reads your sitemap (or crawls navigation links) and identifies which page templates exist, so a 700-page site gets audited by scanning ~20 representative pages instead of all of them.
- Tells you what to fix and where — groups violations by shared
template, so you know that fixing one
<nav>element resolves the issue across 200 pages, not just the one you scanned. - Installs its own dependencies — axe-core and Puppeteer are
resolved automatically. No
npm installrequired in your project. - Tracks progress over time — pass a previous audit and the report shows what's fixed, what's new, and what changed.
A structured report with:
| Section | What it contains |
|---|---|
| Executive Summary | Total issues by severity, pages scanned |
| Findings by Rule | Each violation with impact, instance count, affected pages, WCAG mapping |
| Quick Fixes | One-liner remediation guidance for each detected rule |
| Color Contrast Details | Exact selectors, ratios, and expected thresholds |
| WCAG 2.1 AA Matrix | Pass/fail/manual status for all 50 success criteria |
| Delta from Previous | Fixed, new, changed, and unchanged rules since last audit |
| Remediation Priority | Violations ranked by severity |
| Sampling Strategy | Template groups, page counts, selection rationale |
| Shared Template Patterns | Which template groups have identical issues |
Output modes:
| Mode | Output | Use case |
|---|---|---|
markdown |
Markdown report | Human review, docs, PRs |
markdown+json |
Report + JSON data file | CI, dashboards, trend tracking |
markdown+issues |
Report + issue tracker tickets | GitHub, GitLab, Linear, Jira |
Copy the a11y-audit/ folder into .claude/skills/ in the target project:
cp -r a11y-audit/ /path/to/your-project/.claude/skills/a11y-audit/Copy or symlink into your Codex skills directory.
Ask your agent:
Run an accessibility audit on this project.
The skill will discover your site structure, scan representative pages, and generate a report. For large sites, it runs the discover → scan → report pipeline automatically.
You can also run the scripts directly:
# 1. Discover site structure and select pages to scan
node a11y-audit/scripts/discover.js \
--url http://localhost:3000 \
--output /tmp/discover.json
# 2. Scan the selected pages
node a11y-audit/scripts/scan.js \
--urls $(node -e "const d=require('/tmp/discover.json'); console.log(d.scanList.join(','))") \
--output /tmp/scan.json \
--summary
# 3. Generate the report
node a11y-audit/scripts/report.js \
--input /tmp/scan.json \
--output-dir ./audits \
--project-name "My Project" \
--discover /tmp/discover.jsonNo prior setup needed. scan.js auto-installs axe-core and Puppeteer on first run if they aren't already available.
This repository publishes a GuideCheck assistant-guide.txt for bounded
assistant use:
- Web: https://skilla11y.dev/.well-known/assistant-guide.txt
- Repository copy: assistant-guide.txt
The guide is a plain-text instruction surface for installing the skill, running audits, generating reports, and making narrow maintenance edits. It does not make audit results a legal conformance certification.
Large sites have hundreds of pages but only a handful of distinct
templates. discover.js classifies every URL by its path pattern and
selects representatives from each group:
746 pages found via sitemap
→ 16 template groups identified
→ 22 pages selected for scanning
regulation/* (25 regulations): 34 pages → 2 selected (by DOM complexity)
requires/*/* (81 provisions): 82 pages → 2 selected (by DOM complexity)
compare/*: 561 pages → 2 selected (by DOM complexity)
...plus all 9 unique top-level pages
Within each group, pages are ranked by structural complexity (count of tables, forms, interactive elements) so the scan covers the most and least complex variants.
After scanning, the report cross-references violation fingerprints with template groups:
Shared issues on `regulation/*`, `requires/*/*`, `authority/*`: dlitem
→ Fix the shared build template once → resolves across 144 pages
scan.js resolves axe-core and Puppeteer in this order:
- Skill-local
deps/(auto-installed, gitignored) - Target project
node_modules/ - Global npm modules
- Auto-install to skill-local
deps/if not found anywhere
This repository has three release identifiers because the published surfaces move at different compatibility levels:
package.jsonuses the public repository release line, currently 2.x.a11y-audit/MANIFEST.yamluses the internal bundle inventory version, incremented whenever the skill bundle changes.assistant-guide.txtuses the GuideCheck guide version, incremented only when the assistant guide contract changes.
Release notes should mention each identifier when more than one surface changes.
Pass a previous audit JSON to see progress:
node a11y-audit/scripts/report.js \
--input /tmp/scan.json \
--previous ./audits/audit-2026-03-01.json \
--output-dir ./auditsOutput:
## Delta from Previous Audit
| Metric | Previous | Current | Change |
|----------|----------|---------|--------|
| Total | 130 | 33 | -97 |
Fixed: ~~landmark-one-main~~, ~~region~~
Changed: color-contrast 26 → 2 (↓24)
| Script | Purpose |
|---|---|
scripts/discover.js |
Sitemap-first page discovery with template-aware sampling |
scripts/scan.js |
axe-core scanning with self-contained dependency resolution |
scripts/report.js |
Deterministic report generation (markdown + JSON) |
scripts/bootstrap-context.js |
Create workspace-local project configuration |
scripts/plan-issues.js |
Dry-run issue planning for tracker integration |
| Site | Pages | Groups | Scanned | Violations | Key findings |
|---|---|---|---|---|---|
| AI Regulation Reference | 746 | 16 | 22 | 12 | dlitem, nested-interactive, color-contrast on detail templates |
| Virtual Meeting Reference | 449 | 15 | 20 | 130 | color-contrast on group badges, missing landmarks site-wide |
| sam-rogers.com (Zola blog) | 206 | 12 | 15 | 33 | list structure in theme nav, landmark-unique on every page |
This bundle follows the
Skill Provenance
open standard. Every file carries embedded version metadata
(skill_bundle, file_role, version, version_date,
previous_version, change_summary), and MANIFEST.yaml tracks the
full bundle inventory with versioned hashes. This means any agent or
human can verify which version of which file produced a given audit
report, trace changes across sessions, and detect drift between
installed copies and the canonical source.
a11y-audit/
SKILL.md # Core skill instructions (read by agents)
MANIFEST.yaml # Bundle inventory with versioned hashes
CHANGELOG.md # Version history
HANDOFF.md # Current state and next steps
scripts/ # Reusable Node.js helpers
references/ # Output contract, platform notes, templates
evals/ # Eval definitions and recorded results
assets/ # Sample outputs, CI starter assets
Skill A11y Audit is free and open. If your team uses this skill, consider sponsoring its development. See SPONSORS.md.
Skill A11y Audit is an open skill under Snap Synapse LLC stewardship, authored by Sam Rogers. It is used in every public web page across the PAICE portfolio and is MIT-licensed for any use.
MIT