Teach Your AI Coding Agent to Run Accessibility Audits

4 min read

You’ve got an AI coding agent. It can scaffold components, write tests, refactor modules. But ask it to check whether your app is accessible and you get one of two things: a vague summary of WCAG principles with no actionable output, or a hallucinated audit that references guidelines it didn’t actually check against.

The problem isn’t that the agent is incapable. It’s that nobody told it how. What tool to install. What rules to run. How to map a violation to a specific WCAG success criterion. What to put in the report. What still needs a human.

skill-a11y-audit is a reusable agent skill that solves this. Drop it into your project, and your agent gets a structured protocol for running real accessibility audits with real tooling.

What it does

The skill packages a complete audit workflow:

  • Runs axe-core against your pages, targeting WCAG 2.1 AA
  • Optionally runs Lighthouse accessibility checks for a second signal
  • Maps every violation to the specific WCAG success criterion it fails
  • Generates a markdown report with severity, affected elements, and remediation guidance
  • Flags what automation can’t catch and provides manual follow-up guidance for the things that need a human (keyboard navigation, screen reader behavior, content meaning)

The output is a report you can hand to a developer, file as a ticket, or use as a punch list. Not a score. Not a badge. A list of specific things that are broken and what to do about them.

How to install it

For Claude Code, copy the a11y-audit/ folder into .claude/skills/ in your project:

git clone https://github.com/snapsynapse/skill-a11y-audit.git
cp -r skill-a11y-audit/a11y-audit .claude/skills/

For Codex, copy or symlink the same folder into your Codex skills directory. The skill is platform-agnostic by design – any agent that reads a SKILL.md file can use it.

Once installed, you can trigger it with natural language:

  • “Run an accessibility audit on this project.”
  • “Audit this app for WCAG 2.1 AA issues and generate a markdown report.”
  • “Use $a11y-audit to scan the homepage, about page, and contact page.”

Why a skill instead of just a tool

axe-core exists. Lighthouse exists. pa11y exists. You could tell your agent to install and run any of them. But here’s what actually happens when you do that:

The agent installs axe-core. Runs it with default settings. Dumps raw JSON. Doesn’t map violations to WCAG criteria. Doesn’t distinguish between things it can verify and things that need manual checking. Doesn’t structure the output so anyone can act on it.

A skill isn’t a wrapper around a CLI. It’s the knowledge of how to use the tool well. Which rules to run. How to structure the output for a developer who needs to fix things. When to stop and say “a human needs to check this part.” That operational knowledge is what the agent is missing, and it’s what this skill provides.

What the report looks like

The skill generates structured markdown. Each violation gets:

  • The WCAG success criterion it fails (e.g., 1.4.3 Contrast)
  • Impact level (critical, serious, moderate, minor)
  • The specific elements affected
  • What to fix and how

The report also includes a manual review section: things like keyboard trap testing, focus order verification, and screen reader behavior that no automated tool can fully assess. The skill doesn’t pretend automation covers everything. It draws a clear line between what it checked and what still needs a human.

Scope and constraints

This skill targets WCAG 2.1 Level AA, which is the standard most organizations are working toward and the baseline for most legal compliance requirements. It uses axe-core’s rule set, which is the same engine behind Google Lighthouse’s accessibility score and Deque’s commercial products.

Automated tooling catches a meaningful portion of accessibility issues, but not all of them. The skill is explicit about this boundary. It will find missing alt text, insufficient contrast, missing form labels, improper ARIA usage, and similar machine-verifiable failures. It won’t tell you whether your tab order makes sense to a human, whether your error messages are comprehensible, or whether your modal traps keyboard focus. That’s what the manual follow-up section is for.

Who this is for

  • Developers who want accessibility checks as part of their agent-assisted workflow, not as a separate step they forget
  • Teams using Claude Code or Codex who want consistent, structured audit output across projects
  • Anyone building agent skills who wants a reference implementation for how to package tool knowledge as a reusable skill

The skill follows the agentskills.io open standard and uses skill-provenance for cross-platform version tracking.

Get it

GitHub repo – MIT licensed.

If you’re building agent skills and want to see how this one is structured, the SKILL.md is the whole thing. No build step, no dependencies beyond the audit tools themselves. Read it, fork it, improve it.

Built by SnapSynapse. If you want to see this skill in action on a real project, check out the AI Capability Reference, which was audited using it.