Heading Structure Auditor
Crawls each page and reconstructs its H1–H6 tree to check for a single H1, no skipped levels, and keyword-relevant, non…
Updated
Use this skill
$ npx skills add seoskills.sh/heading-structure-auditorAbout this skill
Heading Structure Auditor is a On-Page SEO skill for AI agents, published in the seoskills.sh catalog. Reach for it when your work involves titles, meta tags, headings, internal linking, and content structure that ranks. Install it with one command and it runs inside your own agent, so the work happens in your workflow, not a separate SEO tool.
SKILL.md
Heading Structure Auditor
AGENT ROLE: Autonomous on-page structure agent. Extract each page's heading tree, validate it against the outline rules, and emit the JSON in references/output.schema.json. Report structural facts, not stylistic opinions.
OBJECTIVE
For each page, verify a clean heading hierarchy — exactly one H1, no skipped levels, descriptive headings — and return the specific violations plus a corrected outline.
INPUTS
urls(REQUIRED string[]) ORsitemap_url.target_keywords(OPTIONAL): mapurl → primary_keywordto check H1/heading relevance.max_pages(OPTIONAL, default 2000).
AUTHENTICATION / RUNTIME
- No API key. Keyless HTTPS GET, UA
seoskills-heading-audit/1.0, honor robots.
EXPECTED TOOL CALLS
- Run
scripts/heading_audit.py --urls a,b,c(or--sitemap {url}). - Per URL: GET; extract
<h1>–<h6>in document order with their text.
PROCEDURE (deterministic, per page)
STEP 1 — EXTRACT the ordered list of headings [{level, text}] from the rendered <body> (ignore headings inside <nav>/<header>/<footer> where detectable).
STEP 2 — VALIDATE and collect issues with codes:
NO_H1/MULTIPLE_H1: zero or >1 H1.LEVEL_SKIP: a heading jumps more than one level below its predecessor (e.g., H2→H4).EMPTY_HEADING: a heading with no text.GENERIC_HEADING: heading matches a generic list ("read more", "introduction", "click here", "untitled").H1_KEYWORD_MISSING(only iftarget_keywords): the primary keyword tokens are absent from the H1. STEP 3 — OUTLINE: build the nested outline tree; mark where it breaks. STEP 4 — SCOREstructure_score(0–100) by deducting per issue; classifypass | needs_work | fail. STEP 5 — EMIT per page: issues, the extracted outline, and a suggested corrected level sequence.
RATE LIMITS & ERROR HANDLING
- Crawl politeness: ≤ 5 concurrent, ≥ 150ms per host. Timeout 12s.
- Per-URL fetch failure (non-200, robots, timeout) →
{url, status:"unreachable"}, continue; never abort the batch. - HARD cap at
max_pages(hit_cap=true).
MISSING / INSUFFICIENT DATA
- IF a page has zero headings THEN
NO_H1+no_headings=true(a real finding). - Nav/breadcrumb headings can inflate counts — exclude by container when the markup allows; when it does not, note
heading_source="body_best_effort". - Never rewrite heading copy; only report structure and suggest the corrected level sequence.
OUTPUT
One JSON object per references/output.schema.json. No prose.
FILES
scripts/heading_audit.py— heading extraction, hierarchy validation, scoring.references/output.schema.json— output contract.
Not using the CLI? Copy the SKILL.md and paste it straight into ChatGPT, Claude, or any agent.
Embed a badge
Install into your agent
More in On-Page SEO
schema
When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.
schema-markup
When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.
seo-schema
Detect, validate, and generate Schema.org structured data. JSON-LD format preferred. Use when user says "schema", "structured data", "rich results", "JSON-LD", or "markup".
seo-images
Image optimization analysis for SEO and performance. Checks alt text, file sizes, formats, responsive images, lazy loading, CLS prevention, image SERP rankings (via DataForSEO), and image file optimization (WebP/AVIF conversion, IPTC/XMP metadata injection). Use when user says "image optimization", "alt text", "image SEO", "image size", "image audit", "optimize images", "image metadata", "image SERP", "convert to webp", or "image file optimize".
seo-image-gen
AI image generation for SEO assets: OG/social preview images, blog hero images, schema images, product photography, infographics. Powered by Gemini via nanobanana-mcp. Requires banana extension installed. Use when user says \"generate image\", \"OG image\", \"social preview\", \"hero image\", \"blog image\", \"product photo\", \"infographic\", \"seo image\", \"create visual\", \"image-gen\", \"favicon\", \"schema image\", \"pinterest pin\", \"generate visual\", \"banner\", or \"thumbnail\".
seo-drift
SEO drift monitoring: capture baselines of SEO-critical elements, detect changes, and track regressions over time. Git for SEO: baseline, diff, and track changes to your on-page SEO. Use when user says "SEO drift", "baseline", "track changes", "did anything break", "SEO regression", "compare SEO", "before and after", "monitor SEO changes", or "deployment check".