Heading Structure Optimizer

Heading structure

by kostja94 · MIT license · ★ 1,006 on GitHub

When the user wants to optimize heading structure (H1-H6), fix heading hierarchy, or improve content structure. Also use when the user mentions "H1," "heading," "heading hierarchy," "content structure," "H2," "H3," "heading tags,"…

---
name: heading-structure
description: When the user wants to optimize heading structure (H1-H6), fix heading hierarchy, or improve content structure. Also use when the user mentions "H1," "heading," "heading hierarchy," "content structure," "H2," "H3," "heading tags," "heading SEO," "multiple H1," or "heading structure." For SEO workflow, use seo-strategy.
metadata:
  version: 1.0.1
---

# SEO On-Page: Heading Structure

Guides heading (H1-H6) optimization for SEO and content structure.

**When invoking**: On **first use**, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **H1 tag**: One per page; clear headline; matches content; primary keyword near start
- **Header tags (H1-H6)**: Logical hierarchy; keyword in headers; one idea per heading

Overview

Guides heading (H1-H6) optimization for SEO and content structure.

What you get

H1recommendation (with keyword)
H2-H6outline for content
Hierarchycheck
ReferencesGoogle headings

Manual install (npx, ZIP)

Claude Codenpx skills add kostja94/marketing-skills --skill heading-structure -g -a claude-code

Claude Code (degit)npx degit kostja94/marketing-skills/skills/seo/on-page/heading#main ~/.claude/skills/heading-structure

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.1 KB

Read SKILL.md here

kostja94/main1 file shown

SKILL.md3.1 KB

Browse every file on GitHub↗

SKILL.md

Show the full text85 lines

heading-structure/SKILL.md85 lines · 3.1 KB

PreviewCode

Outline

RawView on GitHub

SEO On-Page: Heading Structure

Guides heading (H1-H6) optimization for SEO and content structure.

When invoking: On first use, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On subsequent use or when the user asks to skip, go directly to the main output.

Scope (On-Page SEO)

H1 tag: One per page; clear headline; matches content; primary keyword near start
Header tags (H1-H6): Logical hierarchy; keyword in headers; one idea per heading

Initial Assessment

Project context: Read root contextus.md when present and load only the modules relevant to this task. Without Contextus, use available project material or user-provided facts and ask for missing information; do not create a parallel context system.

Identify:

Page type: Homepage, article, product, etc.
Primary keyword: Target search query
Content outline: Main sections and subsections

Best Practices

H1

Principle	Guideline
One per page	Single H1 per page
Primary keyword	Include target keyword naturally
Descriptive	Clearly describe page content
Match intent	Align with title tag and user intent

H2-H6 Hierarchy

Principle	Guideline
Logical order	H1 -> H2 -> H3; don't skip levels
One idea per heading	Each heading = one topic
Scannable	Headings should summarize section content
Keyword variation	Use related keywords in subheadings

Structure

H1 (page title)
-> H2 (section 1)
   -> H3 (subsection)
   -> H3
-> H2 (section 2)
   -> H3
-> H2 (section 3)

Common Issues

Issue	Fix
Multiple H1s	Use single H1; use H2 for other sections
Skipped levels	Use H2 after H1, H3 after H2
Generic headings	Make descriptive; avoid "Introduction," "Conclusion"
Keyword stuffing	Natural language; avoid forced keywords

Output Format

H1 recommendation (with keyword)
H2-H6 outline for content
Hierarchy check
References: Google headings

featured-snippet: H2/H3 for snippet extraction; semantic HTML for list/table snippets
page-metadata: Hreflang, meta robots; metadata complements heading structure
content-optimization: H2 keyword placement, quantity, tables, lists; complements heading structure
article-page-generator: Article page H1-H3 structure, intro/body/conclusion
title-tag: H1 should align with title tag
schema-markup: Article schema uses headline (often H1)
content-strategy: Content outline informs headings

1	---
2	name: heading-structure
3	description: When the user wants to optimize heading structure (H1-H6), fix heading hierarchy, or improve content structure. Also use when the user mentions "H1," "heading," "heading hierarchy," "content structure," "H2," "H3," "heading tags," "heading SEO," "multiple H1," or "heading structure." For SEO workflow, use seo-strategy.
4	metadata:
5	version: 1.0.1
6	---
7
8	# SEO On-Page: Heading Structure
9
10	Guides heading (H1-H6) optimization for SEO and content structure.
11
12	When invoking: On first use, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On subsequent use or when the user asks to skip, go directly to the main output.
13
14	## Scope (On-Page SEO)
15
16	- H1 tag: One per page; clear headline; matches content; primary keyword near start
17	- Header tags (H1-H6): Logical hierarchy; keyword in headers; one idea per heading
18
19	## Initial Assessment
20
21	Project context: Read root `contextus.md` when present and load only the modules relevant to this task. Without Contextus, use available project material or user-provided facts and ask for missing information; do not create a parallel context system.
22
23	Identify:
24	1. Page type: Homepage, article, product, etc.
25	2. Primary keyword: Target search query
26	3. Content outline: Main sections and subsections
27
28	## Best Practices
29
30	### H1
31
32	\| Principle \| Guideline \|
33	\|-----------\|-----------\|
34	\| One per page \| Single H1 per page \|
35	\| Primary keyword \| Include target keyword naturally \|
36	\| Descriptive \| Clearly describe page content \|
37	\| Match intent \| Align with title tag and user intent \|
38
39	### H2-H6 Hierarchy
40
41	\| Principle \| Guideline \|
42	\|-----------\|-----------\|
43	\| Logical order \| H1 -> H2 -> H3; don't skip levels \|
44	\| One idea per heading \| Each heading = one topic \|
45	\| Scannable \| Headings should summarize section content \|
46	\| Keyword variation \| Use related keywords in subheadings \|
47
48	### Structure
49
50	```
51	H1 (page title)
52	-> H2 (section 1)
53	-> H3 (subsection)
54	-> H3
55	-> H2 (section 2)
56	-> H3
57	-> H2 (section 3)
58	```
59
60	## Common Issues
61
62	\| Issue \| Fix \|
63	\|-------\|-----\|
64	\| Multiple H1s \| Use single H1; use H2 for other sections \|
65	\| Skipped levels \| Use H2 after H1, H3 after H2 \|
66	\| Generic headings \| Make descriptive; avoid "Introduction," "Conclusion" \|
67	\| Keyword stuffing \| Natural language; avoid forced keywords \|
68
69	## Output Format
70
71	- H1 recommendation (with keyword)
72	- H2-H6 outline for content
73	- Hierarchy check
74	- References: [Google headings](https://developers.google.com/search/docs/appearance/title-link)
75
76	## Related Skills
77
78	- featured-snippet: H2/H3 for snippet extraction; semantic HTML for list/table snippets
79	- page-metadata: Hreflang, meta robots; metadata complements heading structure
80	- content-optimization: H2 keyword placement, quantity, tables, lists; complements heading structure
81	- article-page-generator: Article page H1-H3 structure, intro/body/conclusion
82	- title-tag: H1 should align with title tag
83	- schema-markup: Article schema uses headline (often H1)
84	- content-strategy: Content outline informs headings
85