Accessibility skill: audit and fix WCAG 2.2 issues with your coding agent

Source: addyosmani/web-quality-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 23 October 2026

What is the accessibility skill?

The accessibility skill teaches a coding agent like Claude Code, Codex or Cursor to audit a web page against WCAG 2.2 and then fix what it finds: missing labels, low contrast, keyboard traps, invisible focus, small tap targets and misused ARIA. It is for front-end developers who want accessibility checked as part of normal work, not left for a separate audit at the end.

It lives in addyosmani/web-quality-skills, which the README calls "An (unofficial) measurement-first collection of Agent Skills" for Lighthouse, Core Web Vitals, WCAG and search. The skill's description reads: "Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible"."

As of 23 October 2026 the repo had about 3,000 GitHub stars and was last pushed on 24 August 2026. Its skills.sh page listed about 63,500 installs.

What does the accessibility skill do?

The agent loads it when you ask for an accessibility review, an a11y audit, WCAG compliance, screen reader support or keyboard navigation, matching the trigger phrases in the description.

It starts from evidence. The first section of the SKILL.md is an "evidence-led audit workflow". When a rendered page is available, the agent should:

1. Run a live Lighthouse Accessibility audit. With Chrome DevTools MCP that is the lighthouse_audit tool, in snapshot mode when a reload would lose a logged-in state.
2. Use the failing nodes to find the component or template at fault, instead of searching the whole repo for generic patterns.
3. Read the rendered accessibility tree (take_snapshot) for names, roles, states, landmarks and headings, and walk the flow with the keyboard.
4. Fix the source, then re-run the same audit and the same manual steps.

It then works through WCAG by principle. The body is organized around the four POUR principles (Perceivable, Operable, Understandable, Robust), with before and after HTML, CSS and JavaScript for each rule. It calls out the six level A and AA criteria that are new in WCAG 2.2, which the W3C's What's New in WCAG 2.2 page lists alongside three new AAA ones: Focus Not Obscured (2.4.11), Dragging Movements (2.5.7), Target Size of at least 24 by 24 CSS pixels (2.5.8), Consistent Help (3.2.6), Redundant Entry (3.3.7) and Accessible Authentication (3.3.8).

It ranks problems by impact. A closing list sorts common issues into critical (missing form labels, missing alt text, low contrast, keyboard traps, no focus indicator), serious (no page language, broken headings, vague link text, autoplaying media, no skip link) and moderate.

What's in the folder:

• SKILL.md: the workflow, the POUR rules with code, a testing checklist and the impact list.
• references/WCAG.md: success criteria by level A, AA and AAA, common ARIA patterns and what changed from 2.1 to 2.2.
• references/A11Y-PATTERNS.md: longer code for a modal focus trap, skip link, error handling, form labels, dragging alternatives, ARIA tabs, live regions and screen reader shortcuts.

There are no scripts. The skill is instructions and examples only.

How do you install the accessibility skill?

Just this skill, with the skills CLI. The command on its skills.sh page, using the skills CLI:

npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility

Add -g to install it for every project instead of the current one. For Claude Code the folder lands in .claude/skills/accessibility/, or ~/.claude/skills/accessibility/ with -g, the standard Claude Code skill locations. The CLI needs Node.js 22.20 or later, per its README.

The whole set as a Claude Code plugin. The repo README gives these two commands, run inside Claude Code:

/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skills

Plugin skills are namespaced, so it appears as /web-quality-skills:accessibility and updates with /plugin update.

Codex. The README documents codex plugin marketplace add addyosmani/web-quality-skills (Codex CLI v0.122 or later), then calling the skill with @accessibility. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

claude.ai. Zip the accessibility folder and upload it under Customize, then Skills, as the Claude Help Center describes.

How do you use it?

Ask in plain words; the skill activates when your request matches its description. Example prompts (suggestions, not quotes from the repo):

• Run an accessibility audit on http://localhost:3000/signup and fix what fails.
• Check every icon-only button in src/components for an accessible name.
• Our modal traps keyboard focus. Fix it and make Escape close it.
• Review this checkout flow against the new WCAG 2.2 criteria, especially target size and accessible authentication.
• Make the pricing page work with prefers-reduced-motion and 200% zoom.

Requirements. None are mandatory. The skill works best with Chrome DevTools MCP connected, which its own client configuration guide adds to Claude Code with:

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

Without it, the SKILL.md falls back to two command-line tools:

npx lighthouse https://example.com --only-categories=accessibility
npm install @axe-core/cli -g
axe https://example.com

Tips and limits

From the skill's own files, not from testing:

• A score is not conformance. The SKILL.md says automated tools detect only a subset of barriers: "a score of 100 is not WCAG conformance." Keep the manual checklist (keyboard, a real screen reader such as VoiceOver or NVDA, 200% zoom, high contrast, reduced motion, focus order).
• Native elements first. The skill steers the agent toward <button>, <a href>, real form controls and <dialog> before ARIA, and warns against adding key handlers to native buttons, which would fire twice.
• Legal claims are general. The conformance table says AA is a legal requirement "in many jurisdictions". It does not tell you which rules apply to you, so check your own obligations.
• It can't see what isn't rendered. Without a running page, the agent can only review source, which misses contrast on real backgrounds and focus order in the browser.
• Privacy with DevTools MCP. The Chrome DevTools MCP README warns that it exposes the browser's content to the agent, and its performance tools may send URLs to Google's CrUX API unless you pass --no-performance-crux. Use a test account, not your personal profile.

Security audits. On 23 October 2026, the skill's skills.sh page showed Pass from all three listed audits (Gen Agent Trust Hub, Socket and Snyk). The skill ships no scripts, but read the files before installing any skill.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its references files; for a repo with many skills, like this one, it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Addy Osmani or web-quality-skills.

Similar skills

• Web performance skill: Cloudflare's Core Web Vitals audit, which also takes a quick accessibility snapshot.
• Frontend design skill: Anthropic's skill for the look of an interface, a good pair for this one.
• Playwright best practices skill: includes a reference on automated accessibility tests with axe-core, so fixes stay fixed.
• Best Claude Code skills: a wider list to browse.