| name | heading-tree |
| description | Generates H1-H4 heading structure for a page. SEO-optimized hierarchy. Stateless, deterministic. |
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
Definition of Done