a11y-agent-skills

Find the regression, fix the source, prove the repair.

An open-source accessibility quality layer for teams building interfaces with
AI. Seven portable Agent Skills guide coding agents through reproducible
evidence, conservative source fixes, scoped verification, and durable regression
tests. Framework-independent Playwright and axe-core packages provide the
deterministic core; React is the first tested framework fixture.

One complete workflow

Published core, CLI, and MCP packages support Node.js 20+. Run the CLI without
cloning the repository:

npx --yes [email protected] install chromium
npx --yes @a11y-agent/cli doctor
npx --yes @a11y-agent/cli scan https://example.com

To keep the command available locally, use
npm install --global @a11y-agent/cli and run a11y-agent doctor.

For an MCP host, launch the stdio server with:

npx --yes @a11y-agent/mcp

Building from source requires Node.js 22.13+ and pnpm 11.19. From a clone:

pnpm install
pnpm exec playwright install chromium
pnpm build
pnpm fixtures:serve

The fixture server prints its local URL. In another terminal, ask your coding
agent:

Use accessibility-audit to audit the checkout state at
http://127.0.0.1:4173/gallery-broken.html. Save JSON evidence to
.a11y-agent/checkout-before.json.

The equivalent deterministic command is:

pnpm exec a11y-agent scan http://127.0.0.1:4173/gallery-broken.html \
  --state checkout-invalid --route /checkout --output .a11y-agent/checkout-before.json

Review a fingerprint and its bounded DOM evidence, then ask:

Use fix-accessibility-issue to locate the source of this finding, make the
smallest supported repair, replay checkout-invalid, verify the fingerprint is
gone, and add the narrowest regression test.

The agent should run:

pnpm exec a11y-agent verify http://127.0.0.1:4173/gallery-repaired.html \
  --state checkout-invalid --route /checkout --baseline .a11y-agent/checkout-before.json \
  --ready-selector '#main' \
  --output .a11y-agent/checkout-verification.json

The verification report records state reproduction, resolved and remaining
fingerprints, new serious/critical findings, and exact run IDs. The regression
test protects behavior such as an error being programmatically exposed—not
merely the presence of one attribute.

Install the skills

The canonical skills are the seven directories under skills/; hosts should use
them directly.

From a local clone, install all seven for Codex without prompts:

npx [email protected] add . --agent codex --yes

Install directly from GitHub:

npx [email protected] add smukh/a11y-agent-skills --agent codex --yes

• Codex: install the repository as a plugin, or copy skills/* into
  ~/.agents/skills/.
• Claude Code: run /plugin marketplace add smukh/a11y-agent-skills, then
  /plugin install a11y-agent-skills@a11y-agent-skills. You can also copy the
  folders into .claude/skills/.
• Cursor: use npx [email protected] add smukh/a11y-agent-skills and select
  Cursor, or copy the folders into .cursor/skills/.
• Generic Agent Skills hosts: point the host at skills/, following the
  Agent Skills specification.

All supported hosts use the same canonical skill files.

CLI

a11y-agent scan <url>
a11y-agent scan-html <file>
a11y-agent compare <before.json> <after.json>
a11y-agent verify <url> --baseline <report.json>
a11y-agent keyboard <url> --journey <journey.json>
a11y-agent doctor

Every evidence command supports JSON, Markdown, and SARIF. Scans support
explicit output, state, viewport, axe tags, include/exclude selectors,
Playwright storage state, request headers, failure thresholds, baselines,
readiness selectors, and reduced-motion emulation. Authentication inputs are not
serialized, and credential-shaped output is redacted. Reports still contain
bounded page evidence and must be handled as potentially sensitive artifacts.
Loopback URLs are treated as an explicit local target; other private networks
require --allow-private-network.

What this can determine

The tools can scan route-addressable states, wait for an observable readiness
selector, preserve deterministic engine findings, stabilize their fingerprints,
compare compatible runs, execute bounded keyboard journeys, and verify a defined
repair. They distinguish automated detection from heuristic inference and
required human review.

They cannot certify WCAG, decide whether content meaning is correct, replace
disabled participants, or represent every browser and assistive-technology
combination. axe-core is used because its maintained rule engine, metadata,
tests, and ecosystem should not be reimplemented here. The project preserves
axe-provided mappings and provenance without inventing standards relationships.

Automated and agent-assisted testing identifies a subset of accessibility
barriers. This result is not a declaration of WCAG conformance.

Packages

Reports default to stdout. Project artifacts should live in .a11y-agent/,
which is ignored unless a team deliberately force-adds a reviewed baseline.

Documentation

• Architecture
• Evidence model
• Manual review
• Security and privacy
• Standards boundary
• Public evaluations
• Contributing and
  third-party notices

Support boundary

Chromium, Firefox, and WebKit are exposed by core through Playwright; CI
exercises Chromium. The browser layer is framework-independent. Source-location
guidance currently targets React conventions, but packages do not require a
framework. The repository is local-first, has no telemetry, needs no LLM or API
key, and does not auto-edit source or open pull requests.