Guide · Agent skill
How to use the Duplicate ID ARIA Checker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Duplicate ID ARIA Checker is an agent skill, a set of instructions that an AI agent such as Claude can load, for finding one specific accessibility bug: two elements sharing the same id, so that an ARIA attribute points at the wrong element. This guide is for front-end developers, accessibility reviewers and design-system teams. By the end you will know what the skill does, how to install it, how to ask for it in plain language and what to check before trusting its output.
Duplicate ID ARIA Checkerthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the skill ZIP. Download the ZIP file for the Duplicate ID ARIA Checker from the page where you found this guide.
- 2Unzip into a skills folder. Unzip the file into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 4Ask for a review in plain words. Ask the agent to check a page, component or dialog for duplicate IDs referenced by ARIA attributes.
- 5Verify the suggested fix. Apply the renamed IDs and updated references, then check the page with browser accessibility tooling or assistive technology.
What the skill makes the agent do
When ARIA attributes point to duplicate IDs, assistive technologies may read the wrong label or description, which gives the user misleading information. The skill teaches the agent to review web page markup for this problem.
Once the skill is installed, the agent checks rendered HTML and components for elements where an ARIA attribute references an id that appears more than once in the DOM. It then suggests unique IDs and updates the references to match, and it can explain why unique IDs matter.
- Ensure IDs referenced by ARIA attributes such as aria-labelledby are unique
- Avoid duplicate IDs that create ambiguous accessibility relationships
- Verify that ARIA controls target the elements they are meant to target
Install the Duplicate ID ARIA Checker skill
Download the ZIP file for the skill from the page where you found this guide. Then choose one of the two install routes below.
For Claude Code, unzip the download into ~/.claude/skills/ to make the skill available everywhere, or into a project's .claude/skills/ folder to make it available only in that project. The skill folder contains SKILL.md and references/rule.md.
In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need to type the skill name. The skill's description says it applies when reviewing rendered HTML, interactive components or design-system patterns related to unique IDs for ARIA references. Ask for that kind of review in ordinary words and the agent should pick the skill up.
Name the page, component or file you want checked so the agent looks at the right markup. Mentioning the ARIA attribute you suspect, such as aria-labelledby or aria-describedby, helps it focus on the right references.
- Check this modal for duplicate IDs that aria-labelledby might point to
- Review the shipping option buttons for aria-describedby references that resolve to the wrong element
- Audit the rendered HTML of this settings dialog for ARIA references to duplicated ids and suggest unique ids
Example: a duplicate ID bug and its fix
The reference material includes a shipping-options example. Two descriptions share the id desc, so both buttons end up described by the first one a screen reader finds. The fix gives each description its own id and points each button at its own description.
Expect the agent to flag the exact elements involved, then propose renamed ids and matching reference updates. Its explanation should cover why screen readers rely on these references to announce labels and descriptions.
<!-- Bad: duplicate IDs referenced by ARIA -->
<div id="desc">Standard shipping</div>
<button aria-describedby="desc">Option A</button>
<div id="desc">Express shipping</div>
<button aria-describedby="desc">Option B</button>
<!-- Good: unique IDs for ARIA mapping -->
<div id="desc-standard">Standard shipping</div>
<button aria-describedby="desc-standard">Option A</button>
<div id="desc-express">Express shipping</div>
<button aria-describedby="desc-express">Option B</button>What the skill needs and how it runs
The skill lists no requirements. It does not run scripts and does not use the network. It works from the markup you give it and from its own written guidance.
Because it only reads markup, its output is general guidance. It does not replace testing with real assistive technology or a full accessibility audit. The skill's own guidance says to verify fixes with browser accessibility tooling or assistive tech.
- Requirements: none listed
- Runs scripts: no
- Uses network: no
- Not for non-web projects or static documents with no HTML, where this rule does not apply
Tips for getting reliable results
Give the agent rendered HTML, not only source templates, when you can. The skill's review covers rendered markup and interactive states, so the output reflects what the browser actually produces.
Always test the fix. Load the page, then check the labels and descriptions with browser accessibility tooling or a screen reader. Treat the agent's suggestions as a starting point for review.
- Paste or point to the rendered markup of the component
- Mention the ARIA attribute you suspect is involved
- Re-check the fixed page with browser accessibility tools or assistive technology
What people use it for
- Checking a modal dialog before release to confirm aria-labelledby points to its own title
- Reviewing a set of option buttons whose aria-describedby links might collide
- Auditing a shared design-system component for duplicated ids that break ARIA relationships
- Explaining to a teammate why a duplicate id produces misleading screen reader output
Frequently asked questions
What is the Duplicate ID ARIA Checker skill?
It is an agent skill that teaches an AI agent to find elements where an ARIA attribute, such as aria-labelledby, references an id that appears more than once in the page. The agent then suggests unique IDs and updates the references. It is licensed under MIT.
How do I install the duplicate-id-aria skill?
Download the ZIP from the page where you found this guide and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.
Does the skill need any requirements or run scripts?
The skill lists no requirements. It does not run scripts and does not use the network. It only reads the markup you provide and works from its written guidance.
Is the Duplicate ID ARIA Checker free?
The skill is licensed under MIT. The source does not list any price, so check the license file in the source repository for the full terms.
Can this skill replace a full accessibility audit?
No. The skill only reads markup and gives general guidance. Verify fixes with browser accessibility tooling and real assistive technology testing, since the skill cannot test how a screen reader actually behaves.
What should I do if the skill does not trigger?
Ask more specifically, naming the component, page or ARIA attribute involved, such as aria-labelledby or aria-describedby. Confirm the skill folder, with SKILL.md inside, is in the right skills directory or uploaded in Settings under Capabilities.
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 review components or pages for accessibility and want an agent to catch duplicate IDs that break ARIA references and to suggest fixes. Pick something else if you need a complete accessibility audit, testing with real assistive technology, or a check for problems beyond duplicate IDs, since this skill covers only that one rule.
Download the skill