Use a single descriptive H1
SkillDev toolsA skill for auditing a page's heading structure. It guides an AI agent through parsing a page's rendered DOM to check that each page has exactly one descriptive H1 tag, flagging pages with none, several, empty, or brand-only H1s. It can also generate H1 text for landing pages or blog posts and review CMS templates that may produce empty or missing H1 elements, suggesting fixes such as rewriting the H1 around the page's main topic or moving extra headings down to H2.
Available today. Use it from your connected AI after setup.
No other account needed.
Have an AI agent that can load and use skills.
Then ask your AI: use the Use a single descriptive H1 skill
What your AI can do with it
- Parse a page's rendered DOM to inspect its heading structure
- Flag pages with no H1, several H1s, empty H1s, or brand-only H1s
- Generate H1 text for landing pages or blog posts
- Review CMS templates that may produce empty or missing H1 elements
- Suggest fixes, such as rewriting the H1 around the page's main topic
- Recommend moving extra headings down to H2
Getting started
- Have an AI agent that can load and use skills.
- Add the h1 skill to the agent's available skills.
- Give the agent a page URL, HTML, or CMS template to review and ask it to audit the heading structure or write an H1.
What this skill tells your AI
The instructions your AI receives, as published by thedaviddias/front-end-checklist in skills/h1/SKILL.md and read by ahel’s review.
The H1 is the most prominent heading on a page and a strong on-page ranking signal. Google uses it to understand the page's primary topic. Missing, duplicate, or keyword-free H1 tags reduce topical clarity, hurting rankings for the page's target terms.
Quick Reference
- Each page should have exactly one
<h1>tag that describes the page's primary topic with relevant keywords - The H1 does not need to be identical to the
<title>tag, but they should be topically consistent - Empty
<h1>tags, multiple<h1>tags on one page, or H1s containing only the brand name are all issues to fix
Check
Parse the rendered DOM of each page. Count all <h1> elements. Flag: (1) Pages with zero <h1> tags. (2) Pages with more than one <h1> tag. (3) <h1> elements whose text content is empty or contains only whitespace. (4) <h1> elements that contain only the brand name with no page-specific topic. (5) <h1> text that does not reflect the page's primary content topic.
Fix
- Ensure every page template outputs exactly one
<h1>. - The H1 text should describe the page's specific topic, not just the site name.
- Include the primary target keyword naturally in the H1 — do not force it awkwardly.
- If the page has multiple sections with separate H1 candidates, choose one main topic and demote others to H2.
- Verify the H1 is visible in the rendered DOM (not hidden via CSS
display:noneorvisibility:hidden). - In Next.js/React: ensure the H1 is in the page component, not in the shared layout.
Before:
<h1>Acme Corp</h1>(brand only) After:<h1>Project Management Software for Enterprise Teams</h1>
Explain
Google's John Mueller has confirmed that H1 tags help Google understand page structure. While H1 is not the strongest ranking factor in isolation, it contributes to on-page topical relevance signals. Multiple H1 tags on one page dilute the primary topic signal; a missing H1 leaves a structural gap that reduces confidence in what the page is about.
Code Review
Query the DOM for all <h1> elements. Assert exactly one exists per page. Check that innerText.trim() is non-empty. Compare H1 text to the page <title> — they should share core topic keywords. Flag if H1 is inside a <header> element shared across all pages (often the site logo alt text) rather than specific to the page content.
For full implementation details, code examples, and framework-specific guidance,
see references/rule.md.
Rule page: https://frontendchecklist.io/en/rules/seo/h1
Signals
- GitHub stars
- 74k
- Forks
- 7k
- Last commit
- Aug 2026
Questions
- What does this skill check for?
- It checks that each web page has exactly one descriptive H1 tag by parsing the rendered DOM, and flags pages with none, several, empty, or brand-only H1s.
- Can it write an H1 for me?
- Yes. It can generate H1 text for landing pages or blog posts, rewriting the H1 around the page's main topic.
- Does it work with CMS templates?
- Yes. It can review a CMS template that may produce empty or missing H1 elements and suggest fixes.
- What fixes does it suggest?
- It suggests rewriting the H1 around the page's main topic and moving extra headings down to H2.
Advanced
- Item type
- skill
- Key
h1- Source
- github.com/thedaviddias/front-end-checklist