Guide · Agent skill
How to use the Heading Hierarchy Checker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The heading-hierarchy skill is a set of written instructions that tells an AI agent how to review a web page's headings so they form a logical outline. It is aimed at front-end developers, designers and QA reviewers who want heading structure checked before release. After reading this guide you will know what the skill does, how to install it, how to ask for a review in plain language and where its limits are.
Heading Hierarchy Checkerthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the ZIP. Get the heading-hierarchy skill ZIP from the skill's page.
- 2Unzip into a skills folder. Place it in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for a team.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there.
- 4Ask for a heading review. Describe the page or HTML and ask the agent to check its heading hierarchy.
- 5Verify the findings. Confirm flagged issues with browser accessibility tools or an expert before relying on them.
What is an agent skill, and what does this one do?
An agent skill is a folder of instructions that an AI agent can load when a task matches it. This one comes from the Front-End-Checklist project and is licensed MIT.
When installed, the agent gets guidance for reviewing web pages and components so their headings form a logical outline. It checks that a page has one main h1 title, that heading levels follow in order without skipping (h1 then h2 then h3), and that heading text describes the content beneath it.
The reason this matters: screen reader users jump between headings like a table of contents, so skipped levels make content harder to understand and navigate.
- Checks for exactly one h1 per page
- Checks that heading levels never skip, for example h1 to h3
- Checks that heading text describes the content that follows
- Flags headings used only for visual styling, with CSS suggested instead
How do you install the heading-hierarchy skill?
There are two routes. For Claude Code, download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to share it with a team.
In the Claude apps, you can upload the skill instead under Settings → Capabilities → Skills.
- Claude Code, personal: unzip into ~/.claude/skills/
- Claude Code, per project: unzip into .claude/skills/ in the project
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with natural requests?
You do not need a special command. Describe the task in plain language and mention headings or page structure. The skill's description covers reviewing rendered HTML and components, so requests about those are the best fit.
- Check the heading structure of this page for accessibility issues.
- Review this HTML for heading hierarchy problems and list each one with its element.
- Does this component have logical headings? Flag any skipped levels.
- Make an outline of the headings on this page and tell me if there is more than one h1.
What does a good heading structure look like?
The skill's reference example shows a page with one h1 for the title, h2 for major sections and h3 for subsections under them. Each heading names the content that follows it.
- Good: one h1, then h2 sections, with h3 subsections inside them
- Bad: two h1 elements on one page
- Bad: jumping from h1 straight to h3
<h1>Web Accessibility Guide</h1>
<h2>Getting Started</h2>
<h3>Prerequisites</h3>
<h3>Tools</h3>
<h2>Core Principles</h2>
<h3>Perceivable</h3>What are the limits of this skill?
The skill covers only heading structure. It does not check keyboard behaviour, colour contrast or other accessibility rules. Its checks depend on the agent's judgement, and no automated testing is included. It is a checklist, not a certified test, so for sites that need legal compliance sign-off, confirm results with dedicated tools or an expert.
- Scope: heading structure only
- Method: agent judgement, not automated testing
- Not a substitute for a full audit or compliance sign-off
Is the skill safe to run?
The skill is a set of written instructions and does not itself run any code. It runs no scripts and uses no network access, and it lists no required tools or other dependencies.
- Runs scripts: no
- Uses network: no
- Requires: nothing listed
What people use it for
- Reviewing a landing page's heading outline before launch
- Checking a component's markup for skipped heading levels
- Giving a designer a list of headings that are used only for styling
- Adding a heading check to a team's accessibility review checklist
Frequently asked questions
Is the heading-hierarchy skill free to use?
The skill is licensed under MIT. The source does not list any price for it, so check the skill's page for current terms.
What do I need to install the heading-hierarchy skill?
The source lists no requirements. You download the ZIP, unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
Does the heading-hierarchy skill run code or access the internet?
No. It is a set of written instructions, runs no scripts and uses no network.
Can this skill replace a full accessibility audit?
No. It covers only heading structure, not keyboard, colour contrast or other rules, and it relies on the agent's judgement. Use dedicated tools or an expert for compliance sign-off.
How do I check heading structure without a skill?
You can use browser accessibility tooling to generate a heading outline and check for exactly one h1 and no skipped levels. The skill's guidance follows the same rules.
Why do heading levels need to be in order?
Screen reader users navigate by headings like a table of contents. Skipped levels make the page outline harder to understand.
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, designer or QA reviewer who wants an agent to check heading order and clarity on pages or components. Pick a full accessibility testing tool or an expert if you need keyboard, contrast or legal compliance checks.
Download the skill