Preface¶

After completing functional integration testing for frontend pages, accessibility (a11y) audits often get stuck on manual walkthroughs: checking whether icon buttons have readable names, whether forms have associated labels, whether the Tab order is reasonable, and whether contrast ratios are sufficient. It’s easy to miss these issues with a quick visual scan, and running a full axe/Lighthouse audit is overly heavyweight. If you already use Cursor Agent, you can directly use its built-in browser to grab the accessibility tree that is consistent with what screen readers use, then identify and fix issues one by one in the source code.

The accessibility-auditing skill is designed for this exact scenario: it does not rely on external scanners, follows a fixed workflow to open pages, capture ARIA trees, check keyboard accessibility, then output a tiered report and guide you through fixes.

What it is¶

accessibility-auditing is included in the open source list awesome-cursor-skills maintained by spencerpauly, categorized as Cursor-Native (depends on the built-in browser capabilities of Cursor Agent). The repository is licensed under Creative Commons Zero (CC0), and the directory only contains a single SKILL.md file.

Its official one-sentence positioning is: Use the ARIA/accessibility snapshot from the Cursor browser to audit missing labels, incorrect Tab order, contrast issues, and improper ARIA usage on your page. The frontmatter has user-invocable: true, so you can actively invoke it in a chat conversation.

It solves the problem of “lightweight a11y walkthroughs during development”: the Agent performs structured checks against the accessibility tree of the actually rendered page, rather than guessing from static HTML files.

Core Features and Highlights¶

According to the official SKILL.md, the workflow is divided into six steps, with specific check items defined:

1. Open the target page
Use browser_navigate to open the URL to be tested (both local development addresses and preview environments are supported).

2. Capture the accessibility tree
Call browser_snapshot to get the page’s aria/accessibility tree. The skill explicitly states: this is exactly the tree that screen readers rely on.

3. Audit against the checklist
The official requirements mandate checking five categories of issues item by item:
- Missing accessible names: Buttons with no text and no aria-label, images without alt text, inputs without associated label/aria-label, links with no text, and buttons that only have icons.
- Semantic HTML: Using clickable div/span instead of button/a; missing landmark elements like nav/main/header/footer; heading level jumps (such as going directly from h1 to h3); lists not using ul/ol/li.
- Keyboard navigation: Interactive elements not included in the Tab order; custom controls lacking role and keyboard handling; focus traps and Escape key closing for modals; no skip-to-content link.
- Misused ARIA: aria-hidden="true" applied to focusable elements; invalid role values; aria-expanded without corresponding collapsible content; aria-controls pointing to a non-existent ID.
- Contrast (visual inspection with screenshots): Light gray text on white backgrounds, overly faint placeholder text, disabled states that are hard to distinguish from normal states.

4. Test keyboard behavior in practice
Use browser_press to simulate Tab presses, verify whether each interactive element can receive focus, whether the focus order follows top-to-bottom/left-to-right logic, whether focus rings are visible, and whether the Escape key can close modals and dropdowns.

5. Output a tiered report
The official provides a report template divided into Critical, Warnings, and Passed categories to facilitate review and scheduling.

6. Fix the code directly
Make fixes in the source code for each issue, and list common correction methods: add aria-label to icon buttons, associate input fields with label/htmlFor, replace clickable divs with real buttons, add missing alt text, fix heading level order, etc.

This skill aligns with Cursor’s official Browser documentation, which also lists “accessibility improvements” as a built-in browser use case, with examples including checking contrast ratios, semantic HTML, ARIA labels, keyboard navigation, and missing alt text. This skill packages these actions into a reusable checklist and report format.

Installation and Activation¶

The skill itself is a standard SKILL.md file that follows the conventions of Agent Skills / agentskills.io. Cursor will automatically discover skills from project-level or user-level directories.

Method 1: Manual copy (consistent with the awesome-cursor-skills README)
Place the official file into the project skill directory:

mkdir -p .cursor/skills/accessibility-auditing
curl -fsSL \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/accessibility-auditing/SKILL.md \
  -o .cursor/skills/accessibility-auditing/SKILL.md

To make it available globally for your user account, place it at ~/.cursor/skills/accessibility-auditing/SKILL.md. Cursor also supports .agents/skills/, as well as paths like .claude/skills/ and .codex/skills/ for Claude Code / Codex.

Method 2: Install via the skills CLI
The vercel-labs/skills tool supports installing individual skills from GitHub by name. For Cursor, you can run a similar command:

npx skills add spencerpauly/awesome-cursor-skills \
  --skill accessibility-auditing \
  -a cursor

If you are using it primarily with Claude Code, replace -a cursor with -a claude-code (this will install it to the corresponding skills directory). Add -g to install to the global user directory.

After installation, type /accessibility-auditing in a Cursor Agent chat, or simply describe “run an accessibility audit on the current page”; the Agent will automatically match this skill based on its description.

Note: The workflow relies on browser tools like browser_navigate / browser_snapshot / browser_press. In Cursor, you will generally use the built-in Browser directly; in other Agents, the same skill list will only work fully if you have mounted a browser MCP/tool with equivalent capabilities.

Typical Usage Examples¶

After starting your local server, you can invoke the skill like this (replace the URL with your page):

/accessibility-auditing
Please audit http://localhost:3000/login
Output the report in Critical / Warnings / Passed categories, and fix the source code for Critical issues directly.

You can also trigger it without explicitly using the slash command, using natural language:

Open the homepage with the browser, grab the aria tree, check for missing labels, Tab order, ARIA misuse and contrast issues,
then provide an accessibility audit report and fix each item one by one.

The official report format example is as follows (structure sourced from SKILL.md):

Accessibility Audit:
  Critical:
    - 3 buttons with no accessible name (header icons)
    - Login form inputs missing labels
  Warnings:
    - Heading levels skip from h1 to h3
    - No skip-to-content link
    - 2 clickable divs should be buttons
  Passed:
    - All images have alt text
    - Landmarks present (nav, main, footer)
    - Focus order is logical

During the fix phase, you can compare the source code against the official common correction methods, for example:

<!-- Add accessible name to icon button -->
<button type="button" aria-label="Close">×</button>

<!-- Associate input with label -->
<label for="email">Email</label>
<input id="email" name="email" type="email" />

<!-- Use semantic element for clickable area -->
<button type="button">Submit</button>

Applicable Scenarios and Notes¶

These are suitable scenarios:
- During mid-development, wanting to quickly perform basic a11y checks on forms, navigation, and modals.
- Before Code Review, having the Agent generate a Critical/Warnings checklist first.
- For products that need to meet WCAG / accessibility compliance requirements, as an auxiliary method during iterative development.

Please note the following when using it:
1. Contrast checks rely on visual inspection of screenshots, not precise contrast ratio calculations; for formal compliance, you should still use axe, Lighthouse, or professional contrast tools for verification.
2. Depends on whether the browser snapshot returns a complete accessibility tree. If the tool results only contain metadata without ARIA trees and element references, auditing and keyboard operations will be blocked. You need to first confirm that the Cursor Browser / used MCP is working properly.
3. The skill will not declare that you have “passed WCAG compliance”; it provides actionable check processes and repair guidance, and the final acceptance conclusion still needs to be backed up by team standards and specialized tools.
4. The repository marks this skill as Cursor-Native, with core capabilities tied to Cursor’s built-in browser; when copying it to other Agents, please confirm that they have equivalent navigation, snapshot, and keypress capabilities.

Summary¶

accessibility-auditing固化了 the workflow of “open page → capture ARIA tree → audit against checklist → test Tab navigation → output tiered report → fix source code” into a reusable Agent Skill, making it easy to integrate accessibility checks into daily AI-assisted development, rather than waiting until right before launch to rush through compliance fixes.

Official address:
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/accessibility-auditing

Original SKILL.md:
https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/accessibility-auditing/SKILL.md

# Accessibility Auditing: Performing Accessibility Audits Using Cursor Browser's ARIA Tree