Guide · Agent skill
How to use the Custom Element Accessibility Review agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains the custom-element-accessibility agent skill, which asks your AI agent to review custom element class definitions and Web Component source code for common accessibility gaps. You do not need prior experience with agent skills. By the end you will know what the skill checks, how to install it, how to ask for a review in plain language, and where its limits are.
Custom Element Accessibility Reviewthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the ZIP. Download the custom-element-accessibility skill ZIP from the page where you found this guide.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project for use in that project only.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 4Share the component code. Give the agent the custom element class file or Web Component source you want reviewed.
- 5Ask for a review in plain language. Request a review for ARIA reflection, keyboard handling or form association, and name the component.
- 6Act on the findings. Apply the suggested ElementInternals, ARIA or keyboard fixes, or replace the component with a native control if the agent recommends it.
- 7Test with a screen reader. Confirm the result with manual screen reader testing, since the skill covers only custom element patterns.
What does the skill make the agent do?
When you ask the agent to review custom element or Web Component code, the skill tells it to check the class definitions for accessibility problems. The source describes four main areas: missing ElementInternals setup, ARIA roles and labels that never reach screen readers, incomplete keyboard handling (Tab, Enter, Space and arrow keys), and custom form inputs that do not take part in native forms.
The skill also asks whether a built-in HTML control could do the job without custom code. If it could, the skill suggests replacing the component with the native control. The underlying problem it targets is that ARIA attributes set inside the shadow DOM do not automatically reach the accessibility tree, so a custom element can look correct on screen and still be announced as a generic group or not at all.
- Checks for ElementInternals attachment in the constructor
- Checks ARIA reflection such as role and label
- Checks keyboard interaction and focus management
- Checks formAssociated on input-like elements
- Flags cases where a native control would remove the burden entirely
How do you install the skill?
Download the skill ZIP from the page where you found this guide. Then unzip it into one of two locations: your personal skills folder at ~/.claude/skills/, or a project-level .claude/skills/ folder inside the project you are working on. Use the personal folder if you want the skill in every project, and the project folder if you want it limited to one codebase.
If you use the Claude apps instead of a folder, you can upload the skill there under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need a special command. The skill's description tells the agent when to use it, which is when reviewing custom element class definitions or Web Component source code. Ask in plain language and name the file or component you want checked, so the agent knows which code to read.
Requests that work well mention the component and the concern. For example, you can ask the agent to check a component for missing ARIA reflection, or to see whether a custom input participates in native forms.
- Review this custom element class for accessibility problems.
- Check my Web Component source for missing ARIA reflection and keyboard handling.
- Does this form-associated custom input work with native forms?
- Would a native control do this job without custom code?
What does an example finding look like?
The source uses a custom checkbox as its main example. Consider this element:
The skill explains why this is a problem. A screen reader sees an unknown element with no role, no accessible name and no state. The checked attribute has no semantic meaning unless the component explicitly maps it, so the fix is to set up ElementInternals and expose the state properly. If a native input type checkbox would do the job, the skill points that out instead.
<my-checkbox checked></my-checkbox>What does the skill need and what are the safety notes?
The source lists no required tools or prerequisites. The skill does not run scripts and does not use the network, so it only reads the code you give it and the reference material bundled with it. The bundled files are SKILL.md and references/rule.md.
The skill's scope is narrow. It covers custom element patterns only. The source says it should be paired with manual screen reader testing, because automated or rule-based review can miss real issues. Do not treat a clean review as a complete accessibility audit.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for getting useful results
Give the agent the full class file, not only a fragment, so it can see the constructor and whether ElementInternals is attached. Ask about one component at a time for clearer findings.
Skip this skill for projects that only use standard HTML, CSS or a framework's built-in controls, because the checks target custom element classes and will not help there. Also remember that the skill is advanced and suits developers who already know what Web Components are.
- Include the constructor and the static formAssociated property in what you share
- Review one component at a time
- Follow up any finding with manual screen reader testing
What people use it for
- Reviewing a custom checkbox or toggle for missing ARIA state and an accessible name
- Checking a form-associated custom input before it ships in a design system
- Auditing Web Component code for incomplete Tab, Enter, Space and arrow key handling
- Deciding whether a custom dropdown should be replaced with a native select or details element
Frequently asked questions
How do I install the custom-element-accessibility skill?
Download the skill ZIP from the page, then unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings, Capabilities, Skills.
What are the requirements for this agent skill?
The source lists no requirements. The skill does not run scripts and does not use the network.
Is the custom-element-accessibility skill free?
The skill is published under the MIT licence, as stated in the source. The source does not mention any price.
Does this skill replace a full accessibility audit?
No. It covers only custom element patterns and should be paired with manual screen reader testing, because automated or rule-based review can miss real issues.
When should I not use this skill?
Skip it if your project only uses standard HTML, CSS or a framework's built-in controls, since the checks target custom element classes and offer no benefit there.
What should I use instead if I only need to build with native controls?
The skill itself recommends native elements such as button, input, select and details before building a custom widget. Using those controls removes much of the accessibility burden the skill checks for.
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
This skill suits front-end developers building Web Components, teams auditing a design system before release, and developers adding form-associated custom inputs. It is not useful for projects that rely only on standard HTML or built-in framework controls, and it is not a replacement for a full accessibility audit or manual screen reader testing.
Download the skill