Prevent new accessibility barriers across large web estates.
Open, self-hosted regression evidence for maintainers and coding agents. Template-aware sampling, stable findings, and legacy-friendly CI.
Strict accessibility gates are hard to adopt when a site already has debt. skill-a11y-audit discovers representative templates, preserves selector-level evidence, and can block only newly introduced findings instead of demanding a perfect first run.
Why skill-a11y-audit?
Framework tests cover components and enterprise platforms cover full programs. skill-a11y-audit occupies the repository-native middle: deterministic evidence across large public sites without a hosted dashboard or a zero-violation prerequisite.
Template-aware sampling
Large sites have hundreds of pages but only a handful of distinct templates. The skill identifies your templates, scans representatives from each group, and maps every violation to the template it affects. Fix one component; resolve issues across hundreds of pages.
Legacy-friendly regression gates
Review and commit the current findings as an accepted baseline, then fail CI only when a change introduces a new rule, route, and selector fingerprint. Existing debt stays visible without blocking adoption.
Zero configuration
Install once with the cross-agent Skills CLI, or use it temporarily without a persistent install. Validated axe-core and Puppeteer versions resolve automatically without changing the target project's dependencies.
Where it fits
This is deliberately narrower than an accessibility-agent suite and lighter than an enterprise monitoring platform. It handles the repository-native regression layer between them.
| Layer | Best for | What this project adds |
|---|---|---|
| Storybook, Playwright, axe | Components, states, and authored test journeys | Site-wide route discovery and deterministic template representatives |
| Accessibility agent suites | Guidance, remediation, standards research, and broad orchestration | A small executable evidence pipeline they can invoke without recreating scan logic |
| Enterprise platforms | Hosted monitoring, dashboards, manual programs, and organizational reporting | Open, self-hosted artifacts and CI policy stored with the repository |
Best fit: public sites, documentation systems, government information services, static generators, and content estates with many URLs generated by shared templates.
Adopt the gate without fixing everything first
A baseline is an explicit record of accepted findings—not a claim that they are harmless. Review it, commit it, and let CI reject only newly introduced rule, route, and selector fingerprints.
1. Create a reviewed baseline
node a11y-audit/scripts/scan.js \ --urls http://127.0.0.1:3000/ \ --write-baseline .a11y-audit/baseline.json
Create or update this file only after reviewing the current findings.
2. Block new barriers
node a11y-audit/scripts/scan.js \ --urls http://127.0.0.1:3000/ \ --baseline .a11y-audit/baseline.json \ --fail-on new
The scan reports accepted, new, and resolved findings and guards axe-core version drift.
3. Reuse the GitHub Action
- uses: snapsynapse/skill-a11y-audit/.github/actions/scan@v2.6.0
with:
serve-path: dist
discover-url: http://127.0.0.1:8088/
surface-map: .a11y-audit/surface-map.json
changed-base: ${{ github.event.pull_request.base.sha }}
baseline: .a11y-audit/baseline.json
fail-on: new
An explicit ownership map narrows scans to changed template groups only when every changed path is mapped. Changed maps, unknown ownership, missing history, and shared-code rules retain the full representative sample with selection evidence. The repository exercises this consumer path end to end and statically checks workflow semantics and security.
Install
Options are listed from simplest to most manual. The recommended path is the reviewed assistant install: a plain-text, hash-pinned GuideCheck guide your assistant verifies and you approve before anything runs.
1. Reviewed assistant install (recommended)
Fetch and verify https://skilla11y.dev/.well-known/assistant-guide.txt with GuideCheck (https://guidecheck.org/verify), report the achieved level and SHA-256, then follow its install action with my approval.
Paste into any coding agent. The guide is GuideCheck Level 3: the text you review is the text the assistant executes, every action needs your approval, and each script it runs is SHA-256 pinned. Read the guide first — it fits on one page.
2. Interactive install
npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit
The open Skills CLI detects supported agents and lets you choose project or global scope. Review the source, then select Claude Code, Codex, or another supported agent.
Try without installing
npx skills use \ snapsynapse/skill-a11y-audit \ --skill a11y-audit
The CLI prepares a temporary skill invocation and leaves no persistent project installation.
3. Choose an agent
# Claude Code, current project npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit \ --agent claude-code \ --yes # Codex, current project npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit \ --agent codex \ --yes
Add --global to make the skill available across projects.
4. Manual fallback
Claude project: .claude/skills/a11y-audit/ Claude personal: ~/.claude/skills/a11y-audit/ Codex project: .agents/skills/a11y-audit/ Codex personal: ~/.agents/skills/a11y-audit/
Copy the repository's a11y-audit/ folder to one of these supported locations.
Then: ask your coding agent
Run an accessibility audit on this project.
The skill runs discover → scan → report automatically.
5. Run from a repository clone
node a11y-audit/scripts/discover.js \ --url http://localhost:3000 \ --output /tmp/discover.json node a11y-audit/scripts/scan.js \ --discover /tmp/discover.json \ --root . --summary \ --output /tmp/scan.json node a11y-audit/scripts/report.js \ --input /tmp/scan.json \ --output-dir ./audits
These paths assume the repository is cloned locally. Each script writes JSON the next step reads.
Sample output
A structured markdown report plus versioned JSON. Configure output_mode in .a11y-audit/PROJECT_CONTEXT.md; direct report.js runs write both files.
## Executive Summary Pages scanned: 22 of 746 · Template groups: 16 Violations: 3 · Severity: 1 critical, 1 serious, 1 moderate Baseline: 27 accepted · 1 new · 2 resolved ## Findings by Rule Rule Impact Instances Affects color-contrast critical 6 regulation/*, requires/* aria-required-attr serious 2 nav, footer landmark-one-main moderate 1 homepage ## Shared Template Patterns Shared issues on regulation/*, requires/*, authority/*: dlitem → Fix the shared build template once → resolves across 144 pages.
What it does not claim
Not certification
Automated evidence does not prove WCAG or legal conformance. Reports identify manual checks that still require people and assistive technology.
Not an automatic fixer
The project preserves an auditor/fixer boundary. It reports evidence and remediation guidance but does not modify application source.
Not hosted monitoring
Artifacts and policy stay in your repository. Use an enterprise platform when you need dashboards, organizational workflows, or managed manual testing.