Sign in Start free

Heading outline repair

Headings form a document outline that both assistive technology and search engines rely on. Levels chosen for visual size rather than hierarchy produce an outline that says something different from the page. This skill repairs the structure without changing the design.

CATEGORY
On-page SEO
FORMAT
heading-outline-repair.md
STEPS
6
PRICE
Free - no account
WHEN TO REACH FOR THIS

Use when a page reads well to a person but its heading structure is illegible to a crawler or a screen reader.

The skill file

heading-outline-repair.md 
---
name: heading-outline-repair
description: Use when a page reads well to a person but its heading structure is illegible to a crawler or a screen reader.
---

# Heading outline repair

Headings form a document outline that both assistive technology and search engines rely on. Levels chosen for visual size rather than hierarchy produce an outline that says something different from the page. This skill repairs the structure without changing the design.

## What you need first

- The rendered page
- Its visual hierarchy as designed

## Method

1. Extract every heading in document order with its level, ignoring styling entirely.
2. Check for the three structural faults: no H1, more than one H1, and skipped levels such as an H2 followed directly by an H4.
3. Read the extracted outline on its own. If it does not describe the page, the levels are wrong regardless of how the page looks.
4. Check what is inside the H1. Hidden text intended for screen readers, or a rotating headline element, can inflate the heading to hundreds of characters - a human sees a short headline while a crawler reads a paragraph.
5. Fix by changing levels to match meaning, then restore appearance with CSS. Size and level are independent.
6. Move any screen-reader-only sentence out of the heading to a sibling element, so assistive technology keeps it while the heading stays short.

## What this produces

A corrected outline, plus any hidden content removed from headings and relocated without loss.

## Where this goes wrong

- Choosing heading level by font size
- Leaving visually-hidden text inside an H1, which inflates it for crawlers
- Using multiple H1s because a framework template emits them

---

From the QuQi skill library - https://www.quqi.io/skills/heading-outline-repair
Free to download · no account, no email

What you need first

  • The rendered page
  • Its visual hierarchy as designed

Method

  1. 01 Extract every heading in document order with its level, ignoring styling entirely.
  2. 02 Check for the three structural faults: no H1, more than one H1, and skipped levels such as an H2 followed directly by an H4.
  3. 03 Read the extracted outline on its own. If it does not describe the page, the levels are wrong regardless of how the page looks.
  4. 04 Check what is inside the H1. Hidden text intended for screen readers, or a rotating headline element, can inflate the heading to hundreds of characters - a human sees a short headline while a crawler reads a paragraph.
  5. 05 Fix by changing levels to match meaning, then restore appearance with CSS. Size and level are independent.
  6. 06 Move any screen-reader-only sentence out of the heading to a sibling element, so assistive technology keeps it while the heading stays short.

What this produces

A corrected outline, plus any hidden content removed from headings and relocated without loss.

Where this goes wrong

  • Choosing heading level by font size
  • Leaving visually-hidden text inside an H1, which inflates it for crawlers
  • Using multiple H1s because a framework template emits them

Use this skill in your own AI

The download is a plain markdown file with the name and trigger in its frontmatter. Where an assistant supports skills it can load itself, that frontmatter is what it reads to decide this one applies.

Claude Code Save it as ~/.claude/skills/heading-outline-repair/SKILL.md and Claude loads it on its own when what you are doing matches the trigger line. Put it in .claude/skills inside a project instead if the whole team should have it.
Claude Upload the file in the skills section of your settings. Once it is there it applies itself in any conversation where the trigger fits, so you do not have to remember it exists.
ChatGPT There is no skills format to install into, so paste the file contents into a Project instruction or a Custom GPT instead. It then applies to every chat in that project rather than only the one you paste it into.
Anything else Paste the markdown into the chat before your question. It works in any assistant, it just has to be pasted again each time.

Questions about this skill

When does the outline need repairing if the page already reads well?

When the page reads well to a person but its extracted outline does not describe it. The alternative most teams pick is nothing, because visually the page is fine. Levels get chosen for font size during design, so an H4 appears under an H2 and the document outline a screen reader announces says something different from the page.

What do I need in hand before starting?

The rendered page, not the template source, and the intended visual hierarchy from whoever designed it. Rendered matters because frameworks inject headings and some components emit a second H1 you will not find in the source. Without the design intent you cannot tell a deliberate subheading from a level chosen for its size, and you will renumber correct headings.

What do I end up with, and which part gets used?

A corrected outline plus any hidden text lifted out of headings and relocated. The relocation is the part that gets used and the part most often skipped: a visually hidden sentence inside an H1 makes a short headline read as a paragraph to a crawler, and deleting it rather than moving it to a sibling element takes something away from screen reader users.

What most often ruins this?

Changing the heading level to change how something looks. Size and level are independent and CSS restores the appearance, so a level should only ever move for meaning. The other recurring one is accepting multiple H1s because a framework template emits them: it is a template fix affecting every page of that type, not a page fix.

More in On-page SEO

Title rewrite diagnosis

Use when Search Console shows impressions for a page but the title in results is not the title y...

Keyword cannibalisation resolution

Use when two or more of your pages trade places for the same query, or when a page that used to...

Internal link equity audit

Use when important pages are buried deep in the site, or when new content takes weeks to be inde...

Intent mismatch repair

Use when a page ranks on page one but gets almost no clicks, or gets clicks and immediate bounce...