Heading Structure Audit Claude Skill
This skill audits a website's heading hierarchy (H1 through H6) and produces an actionable SEO and accessibility report. It crawls pages to find missing or multiple H1s, skipped heading levels, empty headings, headings that do not start at H1, overly long headings, and duplicate heading text, then recommends a clean, logical outline for each page.
Quick Take
Point the skill at a site URL, sitemap, URL list, or local HTML folder. It builds a heading inventory for every page, runs severity-ranked checks against the document outline, and returns a prioritized report so each page lands on one H1 and a logical, gap-free heading progression.
What The Skill Checks
- High-severity structure failures: pages with no H1 at all and pages with no headings whatsoever, each of which leaves search engines and assistive technology without a machine-readable outline of what the page is about.
- Medium-severity outline problems: multiple H1s that dilute the primary topic signal, skipped heading levels (an H2 jumping straight to an H4) that break the logical outline, and empty heading elements that add confusing entries to the accessibility tree.
- Low-severity and informational signals: a first heading that is not an H1, headings longer than the 70-character default threshold, duplicate heading text on a single page, title/H1 mismatch, very deep H5/H6 nesting, and CSS-styled fake headings that look like headings but carry no heading markup.
How The Skill Is Packaged
The skill follows the standard Claude Agent Skill structure: a SKILL.md file with YAML frontmatter and workflow instructions, a references/ folder with the full audit check definitions and report template, and a scripts/ folder with Python scripts that extract every heading from pages and audit the resulting inventory. Copy the skill folder into your Claude skills directory and Claude invokes it automatically when a request matches its description.
Skill Files
Every file in the skill is embedded below directly from the Claude-SEO-Skills repository, so you can review exactly what the skill instructs Claude to do before installing it.
SKILL.md
The skill definition: frontmatter, inputs to collect (including the long-heading threshold), the audit workflow, and the resources the skill relies on.
Audit Checks Reference (references/audit-checks.md)
Full definitions, severity levels, and rationale for every audit check, from missing and multiple H1s to skipped levels, empty headings, and CSS-styled fake headings.
Report Template (references/report-template.md)
The output structure the skill follows when writing the final audit report, including the per-page outline listing and prioritized action items.
Heading Extractor Script (scripts/extract_headings.py)
Crawls a live site, URL list, or local HTML folder within the configured page limits and collects every heading element with its level and text into a JSON inventory.
Heading Auditor Script (scripts/audit_headings.py)
Runs the audit checks against the heading inventory, applying the long-heading threshold and severity classifications, and outputs the structured audit report data.