Guide · Agent skill
How to use the Better Accessibility agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The better-accessibility skill gives an AI coding agent a structured method for reviewing a website or app interface against WCAG 2.2. It checks keyboard and focus behavior, ARIA use, accessible names, forms, screen-reader announcements, motion and zoom. This guide explains what an agent skill is, how to install this one, how to ask for a review, and where its limits are.
Better Accessibilityjakubkrehel/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the better-accessibility ZIP from this page and unzip it.
- 2Place the folder. Move it into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder.
- 3Or upload in the apps. In the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill.
- 4Describe the task. Name the component or page and the accessibility concern, such as keyboard access or form labels.
- 5Review the findings. Check each finding against the WCAG 2.2 criterion it cites and the code it points to.
- 6Test for real. Confirm fixes with keyboard-only use and a screen reader before shipping.
What an agent skill is and what this one makes the agent do
An agent skill is a folder of instructions that an AI agent loads when a task matches it. This one is named better-accessibility and its main file is SKILL.md, supported by reference files on focus and keyboard, forms, hit areas, motion and zoom, screen readers, and semantics and ARIA.
Once installed, the agent reviews an interface for problems such as missing keyboard access, invisible focus indicators, unlabeled form fields and misused ARIA attributes. Each failure is reported against the specific WCAG 2.2 success criterion it breaks, and fixes are written in the project's own styling system. The skill favors native HTML elements over custom widgets.
Install the better-accessibility skill
Download the ZIP for the skill from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and add it there.
- Personal: ~/.claude/skills/better-accessibility
- Project only: .claude/skills/better-accessibility inside your project
Trigger the skill with natural requests
You do not need a special command. Describe the accessibility task in plain language and name the component or page. The agent will load the skill when the request matches its description, which covers keyboard and focus behavior, ARIA, accessible names, forms, screen-reader announcements, motion and zoom against WCAG 2.2.
Be specific about scope. A review of one dialog gives a more useful result than a request to audit the whole product.
- Audit the checkout form in src/components/Checkout.tsx for keyboard and screen-reader problems.
- Check this dropdown menu for keyboard support and focus management, and report WCAG 2.2 criteria it fails.
- Review our modal dialog for focus trapping and focus return on close.
- Fix the icon-only buttons in the header so they have accessible names.
Example workflow: reviewing a form
Point the agent at a form and ask for a review. The skill checks that every input has a real label, that placeholders are not used as labels, that autocomplete and input types are set, and that errors are announced. For failing fields it expects aria-invalid, aria-describedby pointing at the error text, and focus moved to the first invalid field.
The skill's form guidance shows the pattern it expects for a labelled email field with an inline error:
<label for="email">Email</label>
<input id="email" type="email" autocomplete="email" aria-invalid="true" aria-describedby="email-error" />
<p id="email-error">...What the skill will and will not decide
The skill reports findings tied to WCAG 2.2 Level A or AA criteria, or to a concrete task an assistive-technology user cannot complete. Other suggestions are recommendations. Contrast measurement and color changes are handed to a separate better-colors skill, and the agent does not change colors unless asked. Text, layout and writing work belongs to better-typography, better-layout and better-writing.
The skill gives guidance from its files. It is not a certified conformance result and cannot replace testing with real assistive technology and users.
Requirements and safety notes
The skill lists no required dependencies. It does not run scripts and does not use the network, according to its listing. It is made of Markdown instructions and an agents/openai.yaml file.
Because it has no scripts, installing it means copying in instruction files only. Review the files yourself if your team has a policy on third-party skills, since the agent will follow what they say.
Tips for better results
Give the agent the real code, including the component file and its styling, so fixes match your project's styling system.
Re-run the review after fixes and test with a keyboard and a screen reader you actually use. Dynamically inserted alerts vary in support across screen readers.
- Test every flow with the keyboard alone before and after changes.
- Ask for the criterion behind each finding so you can check it against the WCAG 2.2 text.
- Keep contrast questions for the better-colors skill.
What people use it for
- Auditing a checkout or sign-up form for labels, error announcements and focus on the first invalid field.
- Checking a custom dropdown or menu for arrow-key and Escape behavior from the ARIA Authoring Practices patterns.
- Fixing a modal dialog so focus moves in on open and returns to the trigger on close.
- Adding accessible names to icon-only buttons and removing decorative images from the screen-reader tree.
- Preparing a component library for WCAG 2.2 review by listing failing criteria per component.
Frequently asked questions
How do I install the better-accessibility skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
Does the better-accessibility skill require anything else?
The listing states that it requires nothing. It does not run scripts and does not use the network.
Is the better-accessibility skill free?
The skill is published under the MIT licence. The source does not state pricing, so check the licence text on the source page for the terms.
Can this skill make my site WCAG 2.2 compliant?
No. The skill gives guidance from its files and reports failures against WCAG 2.2 criteria, but it is not a certified conformance result. It cannot replace testing with real assistive technology and users.
Does the skill change colors or check contrast?
Contrast measurement and color changes belong to the separate better-colors skill. This skill does not change colors itself unless you ask it to.
Why isn't the agent using my skill?
Make sure the folder is in ~/.claude/skills/ or the project's .claude/skills/ folder, and that the request names an accessibility task the skill covers, such as keyboard, focus, forms, ARIA or screen-reader announcements.
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 or team that wants a structured WCAG 2.2 review of components and pages, especially forms, dialogs and menus. Pick something else if you need certified compliance sign-off, contrast measurement, or text and layout work, which other skills cover.
Download the skill