A11y Agent Skills

a11y-agent-skills

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

An open-source accessibility quality layer for teams building interfaces with AI. Twelve 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 playwright@1.58.0 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 twelve directories under skills/; hosts should use them directly.

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

npx skills@1.5.9 add . --agent codex --yes

Install directly from GitHub:

npx skills@1.5.9 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 skills@1.5.9 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.

Specialist skills in 0.2.0

The second release adds five specialist workflows to the original seven skills. All twelve remain portable and use the canonical skills/ tree.

| Skill | Use it for | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [accessible-authentication](skills/accessible-authentication/SKILL.md) | Login, MFA, OTP paste, recovery, and reauthentication | | [accessible-data-tables-and-grids](skills/accessible-data-tables-and-grids/SKILL.md) | Table/grid decisions, editing, sorting, focus, and virtualization review | | [accessible-dynamic-updates](skills/accessible-dynamic-updates/SKILL.md) | Status, SPA transitions, streaming, cancellation, and announcement review | | [accessible-combobox-and-autocomplete](skills/accessible-combobox-and-autocomplete/SKILL.md) | Suggestion popups, keyboard selection, and stale async responses | | [accessible-charts-and-dashboards](skills/accessible-charts-and-dashboards/SKILL.md) | Data alternatives, filtering, chart interpretation, and equivalent tasks |

For example: “Use accessible-combobox-and-autocomplete to review this city selector, reproduce an out-of-order response, and protect the selected value with a regression test.”

Each specialist includes a focused reference guide, standards links, manual assistive-technology procedures, and paired behavioral fixtures. See the [specialist evaluation guide](docs/SPECIALIST-EVALUATION.md) for runnable tests, agent prompts, coverage limits, and negative controls. Browser assertions do not prove screen-reader speech or task usability with every AT combination. See [release notes](docs/releases/0.2.0.md) for version and packaging details.

CLI

a11y-agent scan 
a11y-agent scan-html 
a11y-agent compare  
a11y-agent verify  --baseline 
a11y-agent keyboard  --journey 
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

| Package | Responsibility | | --------------------------- | ------------------------------------------------------------------------------------------------------ | | @a11y-agent/core | Browser execution, schemas, normalization, fingerprints, comparison, verification, journeys, reporters | | @a11y-agent/cli | Local command-line adapter | | @a11y-agent/mcp | Bounded MCP adapter with private-network denial by default | | @a11y-agent/github-action | Explicit-threshold CI adapter that uploads JSON and SARIF |

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](docs/ARCHITECTURE.md)
• [Evidence model](docs/EVIDENCE-MODEL.md)
• [Manual review](docs/MANUAL-REVIEW.md)
• [Security and privacy](docs/SECURITY.md)
• [Standards boundary](docs/STANDARDS.md)
• [Public evaluations](docs/EVALUATION.md)
• [Contributing](CONTRIBUTING.md) and

[third-party notices](THIRDPARTYNOTICES.md)

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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: smukh
• Source: smukh/a11y-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.