Guide · Agent skill
How to use the Empty Heading Checker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Empty Heading Checker is an agent skill that asks your AI agent to review HTML or components for heading tags (h1 to h6) that contain no visible text. It is written for front-end developers, designers and QA reviewers who want to catch empty headings that confuse screen reader users. By the end of this guide you will know what an agent skill is, how to install this one, how to ask for a review in plain language, and what its limits are.
Empty Heading Checkerthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the ZIP. Get the empty-heading skill ZIP from the page where you found this guide.
- 2Unzip the skill folder. Extract it so the empty-heading folder contains SKILL.md and references/rule.md.
- 3Place it in a skills folder. Move it to ~/.claude/skills/ for personal use, or to a project's .claude/skills/ folder for one repository.
- 4Or upload it in the Claude apps. Open Settings, then Capabilities, then Skills, and upload the skill there.
- 5Paste your markup. Give the agent the rendered HTML or component code you want reviewed.
- 6Ask for a heading check. Use a plain request such as checking the markup for empty h1 to h6 tags.
- 7Verify the fix. Confirm the changes with browser accessibility tooling or assistive technology.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. This skill's description says it applies when reviewing rendered HTML, interactive components, or design-system patterns related to ensuring headings contain text.
When the skill is active, the agent looks for heading tags (h1 through h6) that are empty or contain only non-perceivable whitespace. It reports the offending elements and suggests either adding descriptive text or removing the heading if it is not needed. It also points you to browser accessibility tools or assistive technology for checking the fix.
The reason behind the rule: empty headings still appear in the document outline, so screen reader users who jump from heading to heading hit a dead end with no information about the section.
Install the empty-heading skill
Download the ZIP for this skill from the page where you found this guide. Unzip it so that the skill folder, which contains SKILL.md and references/rule.md, lands in one of these locations:
Use ~/.claude/skills/ to make the skill available across your projects, or use a project's .claude/skills/ folder to share it with one codebase.
Alternatively, in the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/empty-heading/
- Project install: .claude/skills/empty-heading/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need a special command. Describe the review you want in ordinary language that matches the skill's purpose, and the agent should pick it up. Paste the markup or component code directly into the conversation so the agent has something concrete to inspect.
- Check this rendered HTML for empty headings.
- Review these React components for h1 to h6 tags with no text.
- Is there any heading in this page that has only whitespace or an icon with no label?
- Look at our design-system card component and flag heading structure problems.
Examples of what the agent reports
The rule's reference page gives these patterns as the kinds of markup the skill should flag. A good result names each element and explains the fix.
Good markup has descriptive heading text. Bad markup includes an empty h2, an h3 that contains only whitespace, and an h4 used only for an icon with no accessible label. For the icon case, the reference notes that the heading needs an aria-label or screen-reader-only text.
<!-- ✅ Good -->
<h1>Product Specifications</h1>
<!-- ❌ Bad: Empty heading -->
<h2></h2>
<!-- ❌ Bad: Heading with only whitespace -->
<h3> </h3>
<!-- ❌ Bad: Heading used only for an icon without text -->
<h4><i class="fas fa-user"></i></h4>What the skill needs and how it runs
The skill lists no requirements. It does not run scripts and does not use the network, so it works by reading the code or output you give it and reasoning about it. Because of this, it cannot see anything you do not paste or otherwise make available to the agent.
Its guidance is prompt-driven. It is not a validated scanner, so treat its findings as a review to confirm, not a final audit.
- Runs scripts: no
- Uses network: no
- Requirements listed: none
Tips for getting useful results
Give the agent the rendered output where you can, not only source templates, because the skill only sees what you provide and may miss elements generated at runtime.
After the agent flags an element, verify the fix with browser accessibility tooling or assistive technology, as the skill itself suggests.
- Paste rendered HTML from the browser rather than unrendered templates when possible.
- Ask the agent to name the exact element and suggest either descriptive text or removal.
- Re-run the review after editing, then confirm with a browser accessibility tool or a screen reader.
What people use it for
- Reviewing a page's rendered HTML for h1 to h6 tags that show no text before a release.
- Checking a design-system card or panel component where an icon-only heading may have slipped in.
- Working through a front-end accessibility checklist item by item with an agent.
- Giving QA reviewers a first-pass list of heading structure problems to confirm by hand.
Frequently asked questions
Is the Empty Heading Checker skill free?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the repository for the full terms before you reuse it.
What do I need to use this skill?
The skill lists no requirements. It does not run scripts and does not use the network, so you mainly need an agent that supports skills and the markup you want reviewed.
Where do I install an agent skill?
Unzip the skill folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
Can this skill find every empty heading on a site?
No. It is a prompt-driven review, not a validated scanner, and it only sees the code or output you provide. It may miss headings generated at runtime, so paste rendered HTML where you can.
Does this skill give me WCAG compliance proof?
No. The skill gives guidance, not a formal audit, so it is not suitable as certified WCAG compliance evidence.
How is this different from a dedicated accessibility scanner?
A scanner checks pages automatically at scale. This skill reviews the markup or components you share and explains the fix in plain language, and it points you to browser accessibility tools or assistive tech to verify the result.
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 want a quick, plain-language review of heading tags in markup or components, especially as part of a front-end accessibility checklist. Pick a dedicated automated scanner or a formal audit if you need coverage across many pages or certified compliance evidence.
Download the skill