Heading Tree Skill

Purpose

Outputs H1-H4 heading hierarchy for a page. Structure only, no body copy.

Skill Output

Single deterministic heading tree. No alternatives, no variants.

headings:
  - level: h1
    section: hero
    text: "House Removals Bristol - Stress-Free Moving"
  - level: h2
    section: benefits
    text: "Why Families Choose Our Moving Service"
    children:
      - level: h3
        text: "Fully Insured & Protected"

Output contains text only. Patterns/examples are documentation only.

Input

page_type: landing | service | service-area | article
primary_keyword: "house removals bristol"  # Required
secondary_keywords: ["moving company"]      # Optional
location: "Bristol"                         # Required for local
sections: [hero, benefits, faq, final-cta]  # From allowed list
faq_questions: ["How much..."]              # Optional

Blocking Conditions (STOP)

Condition	Result
Missing `primary_keyword`	STOP - no output
Missing `page_type`	STOP - no output
Unknown section in list	IGNORE section
Empty sections list	STOP - no output

Allowed Sections

Section	H2	H3s
`hero`	No (H1 only)	No
`trust-strip`	No	No
`problem`	Yes	No
`solution`	Yes	No
`benefits`	Yes	3 typical
`how-it-works`	Yes	3 (steps)
`social-proof`	Yes	No
`pricing`	Yes	2-3 (tiers)
`faq`	Yes	6 (questions)
`final-cta`	Yes	No
`gallery`	Yes	No
`coverage`	Yes	Optional

Unknown section → ignored, no error.

Heading Rules

H1 Rules

Rule	Requirement
Count	Exactly 1 per page
Keyword	Primary keyword at START
Location	Include if local business
Length	Max 60 characters
Section	Always `hero`

H2 Rules

Rule	Requirement
Count	1 per section (except hero, trust-strip)
Order	Follow sections order
Primary keyword	In 1-2 H2s max
Location	In 2-3 H2s for local

H3 Rules

Rule	Requirement
Parent	Always under H2 (never orphaned)
Count	3-6 per parent H2
Keyword	Rarely, natural only

H4 Rules

Rule	Requirement
Page type	Article ONLY
Count	Max 5 per page
Forbidden	Landing, service, service-area pages

FAQ Questions

Scenario	Behavior
`faq_questions` provided	Use provided questions as H3s
`faq_questions` empty	Use generic templates
No FAQ section	Skip

Generic FAQ templates:

"How much does {service} cost?"
"What areas do you cover?"
"How do I book?"
"Are you fully insured?"
"How far in advance should I book?"
"Do you provide {related_service}?"

Location Mentions

For local business pages:

Level	Location Required
H1	Always
H2	2-3 headings
H3	Rarely

Keyword Density (Annotation)

keyword_density: primary | secondary | location | none

This is annotation only — helps downstream skills, not a rule.

Density	Max Count
primary	3 total (H1 + 1-2 H2s)
secondary	No limit
location	H1 + 2-3 H2s

Example Output

page_type: landing
primary_keyword: "house removals bristol"

headings:
  - level: h1
    section: hero
    text: "House Removals Bristol - Stress-Free Moving From £299"
    
  - level: h2
    section: benefits
    text: "Why Families Choose Our Moving Service"
    children:
      - { level: h3, text: "Fully Insured & Protected" }
      - { level: h3, text: "Fixed Price, No Hidden Fees" }
      - { level: h3, text: "Professional Packing Service" }
      
  - level: h2
    section: faq
    text: "House Removals FAQs"
    children:
      - { level: h3, text: "How much do Bristol removals cost?" }
      - { level: h3, text: "What areas around Bristol do you cover?" }
      
  - level: h2
    section: final-cta
    text: "Ready for a Stress-Free Move?"

Non-goals

Does NOT write body copy
Does NOT suggest alternatives
Does NOT optimize existing headings
Does NOT do keyword research
Does NOT analyze competitors

Forbidden

❌ Multiple H1s
❌ H4 on non-article pages
❌ Orphaned H3 (no parent H2)
❌ Keyword stuffing (>3 primary mentions)
❌ Providing alternative heading options
❌ Writing body content

References

patterns-landing.md — Landing page patterns
patterns-service.md — Service page patterns
patterns-article.md — Article patterns

heading-tree