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…
Use this skill
$ npx skills add seoskills.sh/heading-structure-auditorSKILL.md
---
name: Heading Structure Auditor
description: Crawls each page and reconstructs its H1–H6 tree to check for a single H1, no skipped levels, and keyword-relevant, non-generic headings, returning the corrected outline per page. Use when the user wants a heading/hierarchy audit, semantic-structure check, or to fix H1 and outline problems at scale.
category: on-page-seo
---
# 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[]) OR `sitemap_url`.
- `target_keywords` (OPTIONAL): map `url → primary_keyword` to 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 if `target_keywords`): the primary keyword tokens are absent from the H1.
STEP 3 — OUTLINE: build the nested outline tree; mark where it breaks.
STEP 4 — SCORE `structure_score` (0–100) by deducting per issue; classify `pass | 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
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".