smukh/a11y-agent-skills: Tested accessibility skills, CLI, MCP server, and GitHub Action for agent-assisted audits and regression checks.

Tested accessibility skills, CLI, MCP server, and GitHub Action for agent-assisted audits and regression checks. - smukh/a11y-agent-skills

Summary

a11y-agent-skills is an MIT-licensed TypeScript toolkit that pairs agent "skills" (promptable workflows for coding agents) with deterministic accessibility tooling built on Playwright and axe-core. It ships a CLI, an MCP server, and a GitHub Action that scan URLs, capture fingerprintable evidence, and verify whether a fix actually removed a regression. The repository positions itself as a quality layer for teams using coding agents on UI code.

What it is useful for

The toolkit targets engineers who want accessibility checks they can run during agent-driven edits and in CI. The CLI can audit a URL (a11y-agent scan https://example.com), diff two reports (a11y-agent compare), replay a state and verify a repair (a11y-agent verify), and run bounded keyboard journeys. Reports emit as JSON, Markdown, or SARIF, and the GitHub Action enforces explicit thresholds while uploading both JSON and SARIF.

The twelve Agent Skills give coding agents concrete instructions for auditing, fixing, and adding regression tests, plus five specialist workflows covering accessible authentication, data tables and grids, dynamic updates, combobox and autocomplete, and charts and dashboards. Each specialist ships reference material, standards links, and fixtures, so an agent can be asked, for example, to "review this city selector, reproduce an out-of-order response, and protect the selected value with a regression test."

How engineers can use it

The published CLI runs 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

For an MCP host: npx --yes @a11y-agent/mcp. Building from source requires Node.js 22.13+ and pnpm 11.19, then pnpm install, pnpm exec playwright install chromium, pnpm build, and pnpm fixtures:serve, which prints a local URL such as http://127.0.0.1:4173/gallery-broken.html. The agent can audit that page, save evidence to .a11y-agent/checkout-before.json, repair it, then run a11y-agent verify with --baseline and a --ready-selector to confirm it disappeared.

Skills install per host: Codex via npx [email protected] add smukh/a11y-agent-skills --agent codex --yes, Claude Code via /plugin marketplace add smukh/a11y-agent-skills then /plugin install a11y-agent-skills@a11y-agent-skills, and Cursor by selecting it during the same npx skills command.

The README is explicit about limits. They cannot certify WCAG compliance, judge content meaning, or replace testing by disabled users; axe-core supplies the rule engine and only its mappings are preserved. Source-location repair currently targets React conventions, though packages are framework-independent, and CI exercises Chromium only. Reports contain bounded page evidence and should be treated as potentially sensitive, authentication inputs are never serialized, and private-network targets other than loopback require --allow-private-network.