Guide · Agent skill
How to use the ARIA Role Checker agent skill (aria-roles)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The aria-roles skill is a reusable instruction pack for an AI agent that reviews HTML and interactive components for invalid or misused ARIA role values. It is aimed at front-end developers, designers and QA reviewers who want a second pair of eyes on accessibility markup before release. After following this guide you will know what the skill checks, how to install it, how to ask for a review in plain language, and what its limits are.
ARIA Role Checkerthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the skill. Download the aria-roles ZIP from the page and unzip it.
- 2Place the folder. Move the aria-roles folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. Open Settings, go to Capabilities, and upload the skill under Skills.
- 4Ask for a review. Describe the component or markup you want checked in plain language.
- 5Review the findings. Check each flagged element, role and suggested native replacement.
- 6Verify in a browser. Confirm the changes with browser accessibility tooling or assistive technology.
What is an agent skill and what does aria-roles make the agent do?
An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to perform a specific task. This one is licensed under MIT and comes from the Front-End-Checklist project, under skills/aria-roles.
Once installed, the agent checks rendered HTML and interactive components for ARIA role attributes that are misspelled, non-standard, or applied to the wrong elements. It reports the exact elements and suggests replacing them with standard WAI-ARIA values, or preferably with native HTML controls such as button or select. It also looks at keyboard behaviour, focus flow and accessible names where relevant.
- Flags misspelled roles such as btn or check-box
- Checks that roles sit on appropriate elements
- Recommends native HTML controls over custom ARIA widgets
- Notes keyboard, focus and accessible-name issues where relevant
How do you install the aria-roles skill?
Download the ZIP of the skill from the page where you found it and unzip it. To make it available across your own projects, place the aria-roles folder in ~/.claude/skills/. To limit it to a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/aria-roles
- Project install: .claude/skills/aria-roles inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/aria-roles/
├── SKILL.md
└── references/
└── rule.mdHow do you trigger the skill with a natural request?
You do not need a special command. Describe the review you want in ordinary language and mention the HTML or components involved. The skill's description tells the agent to use it when reviewing rendered HTML, interactive components or design-system patterns for valid ARIA role values.
Good requests name the thing being reviewed and the concern, for example whether a custom widget is announced correctly. Paste the markup or point the agent at the component file.
- "Review this dropdown component for invalid ARIA roles."
- "Check our design-system tabs for misspelled or misapplied roles."
- "Is this custom toggle announced correctly by screen readers? Check roles and accessible names."
What does a typical review look like?
The skill's reference examples show the kinds of problems it targets. Valid roles such as button, navigation and status are correct. Typos such as btn, check-box and tooltip-item are not, and should become button, checkbox and tooltip. The preferred fix for a clickable div with role="button" is a native button element, which already carries the right meaning.
The agent is expected to flag the exact element, the role, labels, focus behaviour or keyboard interactions that break the rule, and to suggest how to verify the fix with browser accessibility tools or assistive technology.
<!-- Invalid -->
<div role="btn">Incorrect</div>
<!-- Preferred: native control -->
<button type="button">Click me</button>What does the skill need and what are its safety limits?
The skill lists no requirements. It does not run scripts and does not use the network, so it works only with the content you give it. It reviews markup, not live behaviour: it cannot run a screen reader, so it is not a full accessibility audit. Confirm its suggestions with browser accessibility tooling and real assistive technology before shipping.
Because it runs no scripts and makes no network calls, there are no extra permissions to review. Still, read the SKILL.md and references/rule.md files before installing any skill you did not write.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Files: SKILL.md and references/rule.md
What tips help you get better results?
Give the agent complete markup, including the parent containers, because a role's correctness depends on where it sits. Ask it to check native semantics first, since the skill itself recommends that order. For custom widgets, include the script that handles keyboard input so focus and key behaviour can be reviewed too.
- Paste full components, not fragments, when possible
- Ask for native alternatives before accepting ARIA-based fixes
- Re-run the review after changes and verify in a browser
What people use it for
- Catching a misspelled role such as btn before a component ships
- Deciding whether a clickable div should become a native button
- Reviewing a design-system tab or dropdown for consistent ARIA usage
- Checking that a status message uses an appropriate role
Frequently asked questions
How do I install the aria-roles skill?
Download the ZIP, unzip it, and place the aria-roles folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings, Capabilities, Skills.
Is the aria-roles skill free to use?
The skill is published under the MIT licence, as stated on the source page. Check the licence file included with the project for the exact terms.
What does the aria-roles skill require?
The skill lists no requirements. It runs no scripts and does not use the network, so it works from the markup you provide.
Can the skill replace a full accessibility audit?
No. It reviews markup only and cannot run a screen reader or test with real assistive technology. Use it as one step alongside manual and assistive technology testing.
What is the difference between a valid role and a misspelled one?
Valid roles are standard values from the WAI-ARIA specification, such as button or checkbox. Misspelled values such as btn or check-box are ignored by browsers and assistive technologies.
Should I use ARIA or a native HTML control?
Prefer native HTML controls such as button, input or select whenever they can do the job, because they already carry the right meaning. The skill recommends this order before adding more ARIA.
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 aria-roles if you are a front-end developer, designer or QA reviewer who wants a quick, markup-focused check for invalid ARIA roles and a push toward native controls. Pick a different approach if you need a full accessibility audit with real screen-reader testing, or if your project has no HTML to review.
Download the skill