Check and Fix Accessibility (a11y) Skill

A reusable accessibility (a11y) skill for AI coding assistants. It teaches the agent how to audit and fix front-end accessibility issues (WCAG 2.2 Level A/AA), including semantics, keyboard navigation, ARIA, forms, contrast, and screen readers—for web (React, Next.js, Vue, Angular) and with pointers for native mobile.

Use this skill when you or your team work on accessibility, a11y, WCAG, screen readers, keyboard navigation, focus management, ARIA, semantic HTML, or fixing accessibility issues in HTML/React/Next.js/Vue or other front-end code.

---

What’s in this repo

The repo root holds LICENSE, README, and .gitignore. The skill is in the review-fix-a11y subfolder: copy that folder into your tool's skills directory.

check-fix-accessibility/          ← repo root
├── LICENSE
├── README.md
├── .gitignore
└── review-fix-a11y/             ← the skill (copy this folder when installing)
    ├── SKILL.md                 ← main skill (required by all platforms)
    └── reference.md            ← WCAG, ARIA, testing, native mobile

Path	Purpose
review-fix-a11y/SKILL.md	Main skill: workflow, checklist, fix patterns, corner cases.
review-fix-a11y/reference.md	Deeper reference: WCAG summary, ARIA patterns, testing tools, screen readers, native mobile.
README.md	This file: setup for Cursor, Claude, Kiro, Codex, Google Antigravity.

When installing, use the review-fix-a11y folder so your tool sees a skill directory named review-fix-a11y containing SKILL.md and reference.md.

---

Setup by platform

Install the skill so your AI assistant loads it when you work on accessibility. Choose your editor/tool below.

---

Cursor

Cursor uses skills as directories with a SKILL.md file. You can use this as a project skill (shared with the repo) or a personal skill (all your projects).

Option A: Project skill (recommended for teams)

1. Clone this repo, then copy the review-fix-a11y folder into your project’s Cursor skills directory:

   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   mkdir -p .cursor/skills
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y .cursor/skills/

   Or from the repo root after cloning: cp -r review-fix-a11y .cursor/skills/

2. Resulting layout:

   .cursor/skills/review-fix-a11y/
   ├── SKILL.md
   └── reference.md
   

3. Restart Cursor or start a new chat. The agent will use the skill when you mention accessibility, a11y, WCAG, etc.

Option B: Personal skill (all projects)

1. Create your personal skills directory if needed, then copy the review-fix-a11y folder there:

   mkdir -p ~/.cursor/skills
   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y ~/.cursor/skills/

2. Restart Cursor. The skill is now available in every project.

Note: Do not put this under ~/.cursor/skills-cursor/; that directory is reserved for Cursor’s built-in skills.

---

Claude (Claude Code)

Claude Code can use project instructions (e.g. CLAUDE.md) or a rules directory (.claude/rules/). This skill fits well as a rule or as content referenced from CLAUDE.md.

Option A: Single rule file

1. Create the rules directory:

   mkdir -p .claude/rules

2. Copy the skill into a rule file (e.g. accessibility.mdc). You can either:

   • Paste the contents of review-fix-a11y/SKILL.md into the rule body, or
   • Keep the repo in your project and add a rule that points to the skill folder.

   Example .claude/rules/accessibility.mdc:

   ---
   description: Check and fix front-end accessibility (a11y, WCAG). Use when the user asks about accessibility, a11y, WCAG, screen readers, keyboard navigation, ARIA, semantic HTML, or fixing a11y issues.
   paths: "**/*.tsx","**/*.jsx","**/*.vue","**/*.html","**/*.css"
   ---
   
   [Paste contents of review-fix-a11y/SKILL.md here, or instruct the agent to read review-fix-a11y/SKILL.md and review-fix-a11y/reference.md when working on a11y.]

3. For a smaller rule, reference the files in your repo:

   ---
   description: Accessibility (a11y) audit and fix guidance
   paths: "**/*.tsx","**/*.jsx","**/*.vue","**/*.html"
   ---
   
   When working on accessibility, a11y, WCAG, screen readers, or keyboard/ARIA issues, read and follow:
   - review-fix-a11y/SKILL.md (workflow, checklist, fix patterns)
   - review-fix-a11y/reference.md (WCAG, ARIA, testing, native mobile)

Option B: User-level instructions

1. Copy the review-fix-a11y folder to your Claude config, e.g.:

   mkdir -p ~/.claude/skills
   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y ~/.claude/skills/

2. In ~/.claude/CLAUDE.md (or your project’s CLAUDE.md), add a line such as:

   When the user asks about accessibility, a11y, WCAG, screen readers, or fixing a11y issues, use the instructions in ~/.claude/skills/review-fix-a11y/SKILL.md and reference.md.

Scopes (project vs user) follow Claude Code’s hierarchy: project (.claude/) overrides user (~/.claude/).

---

Kiro

Kiro uses steering files (e.g. in .kiro/) and skills with YAML frontmatter. Skills are loaded on demand based on metadata.

1. In your project root, create the Kiro skills directory and copy the review-fix-a11y folder into it:

   mkdir -p .kiro/skills
   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y .kiro/skills/

2. Ensure SKILL.md has YAML frontmatter (it already includes name and description). Kiro uses that to know when to load the skill.

3. Layout:

   .kiro/skills/review-fix-a11y/
   ├── SKILL.md
   └── reference.md
   

4. Restart Kiro or start a new session.

For global (user-wide) use, copy the same folder under Kiro’s global skills path (if your Kiro version supports it; see Kiro docs).

---

Codex

Codex loads skills from $CODEX_HOME/skills (default ~/.codex/skills). You can install from this GitHub repo using the Codex skill-installer or manually.

Option A: Install from GitHub (skill-installer)

If you have the skill-installer skill in Codex:

1. In Codex, ask: "Install the skill from GitHub repo YOUR_USERNAME/check-fix-accessibility, path review-fix-a11y" (so the installer uses the review-fix-a11y subfolder).
2. The installer will put the skill in $CODEX_HOME/skills/review-fix-a11y.
3. Restart Codex to load the new skill.

Option B: Manual install

1. Clone this repo, then copy the review-fix-a11y folder into your Codex skills directory:

   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   mkdir -p ~/.codex/skills
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y ~/.codex/skills/

   Or, if CODEX_HOME is set:

   cp -r /path/to/check-fix-accessibility-repo/review-fix-a11y "$CODEX_HOME/skills/"

2. Ensure this structure:

   $CODEX_HOME/skills/review-fix-a11y/
   ├── SKILL.md
   └── reference.md
   

3. Restart Codex. The skill will be available when you work on accessibility-related tasks.

---

Google Antigravity

Antigravity uses Agent Skills in a directory with SKILL.md and optional scripts/, references/, or assets/. Skills can be workspace-scoped or global.

Option A: Workspace (project) skill

1. In your project root, create the agent skills directory and copy the review-fix-a11y folder:

   mkdir -p .agent/skills
   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y .agent/skills/

2. Layout:

   .agent/skills/review-fix-a11y/
   ├── SKILL.md
   └── reference.md
   

3. Restart Antigravity or start a new agent session. The skill's description in the frontmatter is used to match user intent (e.g. "accessibility", "a11y", "WCAG").

Option B: Global (user-wide) skill

1. Create the global skills directory and copy the review-fix-a11y folder there:

   mkdir -p ~/.gemini/antigravity/skills
   git clone https://github.com/YOUR_USERNAME/check-fix-accessibility.git /tmp/check-fix-accessibility-repo
   cp -r /tmp/check-fix-accessibility-repo/review-fix-a11y ~/.gemini/antigravity/skills/

Reference: Antigravity Skills (Google Codelabs), Antigravity docs.

---

Quick reference: where files go

Platform	Project scope	User scope (global)
Cursor	.cursor/skills/review-fix-a11y/	~/.cursor/skills/review-fix-a11y/
Claude	.claude/rules/ (e.g. accessibility.mdc) or reference from CLAUDE.md	~/.claude/skills/review-fix-a11y/ + CLAUDE.md
Kiro	.kiro/skills/review-fix-a11y/	(Check Kiro docs for global path)
Codex	—	$CODEX_HOME/skills/review-fix-a11y/ (default ~/.codex/skills/)
Antigravity	.agent/skills/review-fix-a11y/	~/.gemini/antigravity/skills/review-fix-a11y/

---

Skill contents (summary)

• Audit: Use Lighthouse, axe, pa11y, ESLint a11y plugins.
• Checklist: Semantics, landmarks, headings, focus, keyboard, forms, labels, images/alt, ARIA, contrast, motion, zoom.
• Corner cases: Screen readers, voice control, SPAs, modals, live regions, RTL, CAPTCHA.
• Fix patterns: Custom controls, modals, expand/collapse, tabs, error messages.
• reference.md: WCAG 2.2 summary, ARIA patterns, testing tools, screen reader testing, native mobile (React Native, iOS, Android) pointers. In review-fix-a11y/reference.md.

---

License

This project is licensed under the MIT License. See LICENSE.

---

Contributing

Improvements and fixes are welcome. Suggested focus:

• Keeping WCAG and ARIA guidance aligned with current standards.
• Adding short examples or scripts that match the checklist (e.g. running axe or pa11y).
• Clarifying setup steps for any of the five platforms.

Open an issue or pull request on the GitHub repo.