Guide · Agent skill
How to use the Accessibility Audit agent skill (a11y-audit)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The a11y-audit skill gives an AI agent a structured accessibility review workflow for web code. It covers React, Next.js, Vue, Angular, Svelte and plain HTML, and checks against WCAG 2.2 Level A and AA. This guide explains what the skill does, how to install it, how to trigger it, and where its limits are, so you can run a first-pass audit on your own project.
Accessibility Auditalirezarezvani/claude-skills · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm Python 3 is available. The bundled scanner and contrast checker run on Python 3. Make sure it is installed and that the agent can access your project's source files.
- 3Ask for an audit. Describe the goal in plain language, such as auditing a component or checking a colour pair, and name the file or folder to review.
- 4Review the findings. Check each violation, its WCAG criterion and severity. Confirm the issue is real before changing code.
- 5Apply fixes in version control. Make changes on a branch or after committing, then review the before-and-after code the agent proposes.
- 6Re-run the scan to verify. Run the scanner again, using a baseline if you have one, to confirm the violations are gone and no new ones appeared.
What the a11y-audit skill makes the agent do
An agent skill is a folder of instructions and supporting files that an AI agent loads when your request matches the skill's description. This one is for accessibility work. The source describes a three-phase workflow: Scan, Fix and Verify. The agent scans your source for WCAG 2.2 Level A and AA violations, sorts each one by severity, suggests a before-and-after code fix for your framework, and re-runs the scan to check that the fix worked and nothing regressed.
- Scan: finds violations such as missing image alt text, unlabeled form fields, poor colour contrast and keyboard-inaccessible controls.
- Classify: labels each issue Critical, Major or Minor, and maps it to a WCAG criterion.
- Fix: proposes framework-specific before-and-after code.
- Report: produces a summary suitable for developers, product managers and compliance stakeholders.
- Integrate: provides pipeline configs for GitHub Actions, GitLab CI and Azure DevOps.
Install the a11y-audit skill
Download the skill ZIP from this directory page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
Check what you need before you start
The skill runs two bundled Python 3 scripts, so Python 3 must be installed. The agent needs access to the source files you want scanned. A CI/CD platform is optional and only needed if you plan to add checks to a pipeline.
The skill runs scripts but does not use the network, according to its listing.
- Python 3 for scripts/a11y_scanner.py and scripts/contrast_checker.py
- Access to the project source files
- Optional: GitHub Actions, GitLab CI or Azure DevOps
Trigger the skill with natural requests
You do not need to memorise commands. The skill's description lists the situations it fits: auditing accessibility, fixing a11y violations, checking colour contrast, generating compliance reports, and adding accessibility checks to CI/CD pipelines. Describe what you want in plain language and point the agent at the code.
The skill also lists slash-command forms. These are the documented options.
- Audit this component for accessibility problems: src/components/ProductCard.tsx
- Check whether #777777 text on white passes WCAG AA contrast
- Write a stakeholder summary of the accessibility gaps in src/
- Fix the missing alt text and unlabeled inputs in the signup form, then verify with a re-scan
- Add an accessibility check to our GitHub Actions workflow
/a11y-audit # Audit current project
/a11y-audit --scope src/ # Audit specific directory
/a11y-audit --fix # Audit and auto-apply fixes
/a11y-audit --report # Generate stakeholder report
/a11y-audit --ci # Output CI-compatible resultsRun the scripts directly
You can also call the scanner and contrast checker yourself. These commands come from the skill's Quick Start section. Replace the paths with your own.
- Scanner output can be a table, CSV or JSON, and can be compared with a baseline file.
- The contrast checker can test a colour pair, scan a CSS file, or scan a directory for Tailwind colour classes.
python scripts/a11y_scanner.py /path/to/project
python scripts/a11y_scanner.py /path/to/project --json
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"
python scripts/contrast_checker.py --file /path/to/styles.cssRead an example result
The skill's sample contrast output shows how a result is reported. Grey #777777 on white gives a contrast ratio of 4.48:1. That fails AA for normal text, which needs 4.5:1, but passes for large text, which needs 3.0:1. The same output shows that #1a1a2e on white reaches 17.06:1 and passes AAA as well.
The skill's React example flags an image with no alt attribute and a clickable div with no keyboard support as Critical, and two grey text colours as Major contrast failures. Its fix replaces the div with a native anchor element and adds alt text.
Use the CI/CD integration
The scanner has a --ci mode that returns a non-zero exit code when critical issues are found. The bundled reference guide covers integrating checks into pipelines. Use it to stop accessibility regressions from reaching release.
- Run the scanner in CI with --ci to fail the build on critical issues.
- Use --baseline to compare a new scan against a saved previous result.
python scripts/a11y_scanner.py /path/to/project --ciSafety notes before you use --fix
The --fix option applies changes automatically. Commit your work to version control first, so you can review and revert every change. Review all fixes before merging, because a static scan cannot judge whether alt text is accurate or whether a control behaves correctly with a screen reader.
- Commit or stash your changes before running --fix.
- Review diffs before merging.
- Human testing is still needed for screen reader behaviour and content meaning.
What people use it for
- Reviewing a single React component for missing alt text, click handlers without keyboard support and low-contrast text.
- Checking brand colour pairs against AA and AAA ratios from a CSS file or Tailwind classes.
- Producing a stakeholder summary of accessibility gaps for a product or compliance review.
- Adding an accessibility scan step to a GitHub Actions, GitLab CI or Azure DevOps pipeline.
- Re-checking a project after fixes to confirm that the original violations are resolved.
Frequently asked questions
Is the a11y-audit skill free to use?
The source file lists the licence as MIT. It does not list any price, so check the repository license file for the full terms before you rely on it.
What do I need to install the a11y-audit skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills. The scripts need Python 3.
Does the a11y-audit skill make my project pass WCAG certification?
No. A static code scan cannot cover everything WCAG requires, such as real screen reader behaviour or whether content makes sense. The skill is best used for a first-pass review, and human testing is still needed.
Which frameworks does the a11y-audit skill support?
The skill covers React, Next.js, Vue, Angular, Svelte and plain HTML. It can auto-detect the framework or you can force one with the --framework option of the scanner.
Does the skill need an internet connection?
The listing says it uses no network. It does run local Python scripts, so it needs access to your project files.
Can the a11y-audit skill fix accessibility problems automatically?
It can. The --fix option applies changes automatically, so commit your code first and review every change. The skill also suggests before-and-after fixes that you can apply yourself.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a front-end developer who wants a quick, structured first pass on a component or project, or a team that wants accessibility checks in CI. Pick something else, or add human testing, if you need legal or compliance certification, because a static scan cannot judge screen reader behaviour or content meaning.
Download the skill