Shawn McBurnie

AI agents that test accessibility: two skills, released

· 4 min read

I am releasing two of my Claude Code skills as open source: accessibility-audit (comprehensive WCAG 2.1/2.2 testing of a live URL or HTML snippet) and wcag-check (a targeted pass on specific success criteria: contrast ratios, semantic markup, ARIA usage, keyboard access). They are available at github.com/shawnmcb/claude-a11y-skills.

These are two of the 68 skills I have authored for the Claude Code ecosystem, 64 of which declare test-contracts (counts verified 2026-07-03; sourcing on the colophon). Until now that number has been an unverifiable claim on my homepage. This release makes a slice of it inspectable.

What an accessibility skill actually does

A skill is a structured instruction set that an AI agent loads on demand. When I invoke /accessibility-audit https://example.com, the agent:

  1. Drives a real browser session against the target page (via an accessibility scanner toolchain; the repo documents the dependency).
  2. Evaluates what it finds against WCAG 2.1/2.2 success criteria, AA level minimum, AAA on request.
  3. Categorizes each violation by severity: Critical (blocks access), Major (significant barrier), Minor (usability issue).
  4. Produces a remediation report with specific code fixes: ARIA corrections, contrast solutions, keyboard-navigation repairs, prioritized by impact against effort.

wcag-check is the smaller sibling for mid-development loops: point it at one criterion (1.4.3 Contrast, 2.1.1 Keyboard, 4.1.2 Name/Role/Value, 1.3.1 Info and Relationships) and get a fast, evidence-backed pass/fail with the failing elements identified. The audit skill is for milestones; the check skill is for the ten-minute loop between writing a component and committing it.

Neither of these is a product. They are working tools from my own pipeline, published as they run.

The test-contract is the interesting part

Each skill carries a declared test-contract in its frontmatter: trigger phrases it must respond to, anti-triggers it must decline, an expected-output specification with must-contain and must-not-contain lists, and named edge cases (unreachable URL, zero violations found, AAA requested instead of AA, scanner unavailable).

The must-not-contain list is the piece I would defend hardest. It includes phrases like “I cannot access” and “I’m unable to.” An agent that politely declines has failed, and the contract makes that failure detectable by inspection instead of by a human noticing that the report reads like an apology. Behavior is gated on what the output demonstrably contains. This is the same discipline that gates my commercial work: the NetterTech Events plugin suite ships WCAG 2.2 AA across its user surfaces behind 10,000+ automated tests, with the free core published on WordPress.org, and these skills run inside that pipeline and in the audits of this site.

What agent testing catches, and what it cannot

The received wisdom in accessibility engineering is that automated scanners catch a minority of real-world barriers, and my working assumption (baked into wcag-check’s own instructions) is roughly a third. Agent-driven testing improves on static scanning because the agent can operate the page: tab through interactive elements, observe focus order, exercise disclosure widgets, compare rendered contrast in context. It catches more than a linter does.

It still does not terminate verification. A human judgment does. Whether alt text is meaningful rather than merely present, whether a focus order makes sense for the task rather than merely existing, whether an error message helps a screen-reader user recover: these are judgment calls, and the skills are written to flag them for manual testing rather than paper over them. An accessibility report that never says “needs human review” is a report you should distrust. Twenty years of accessibility work (HIPAA-regulated healthcare systems, WCAG AAA client engagements, an accessible React Aria component library, design-system work) has made that the most durable lesson: tooling raises the floor, and people confirm the ceiling.

Why release these two

Accessibility tooling and AI evaluation are usually separate conversations. I think they are one conversation: in both cases the question is whether a system actually works for the person in front of it, measured against explicit criteria, with failures surfaced loudly. If you run Claude Code, you can install these skills and get that discipline in your own loop today. If you maintain a different agent stack, the skill files are short and the pattern (structured instructions plus a declared, inspectable test-contract) ports without much ceremony.

Get them at github.com/shawnmcb/claude-a11y-skills. Issues and adaptations welcome.