Heading Tree Skill Skill

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

Definition of Done

[ ] Exactly 1 H1
[ ] H2s match sections list
[ ] H3s have parent H2
[ ] No H4 (unless article)
[ ] Primary keyword in H1
[ ] Primary keyword in 1-2 H2s
[ ] Location in H1 + 2-3 H2s (if local)

Agent Skills: Heading Tree Skill

Install this agent skill to your local

Skill Files