SEO Optimizer

Content optimization

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

When the user wants to optimize content for SEO—word count, H2 keywords, keyword density, multimedia, tables, lists. Also use when the user mentions "content length," "word count," "keyword stuffing," "H2 keywords," "keyword density,"…

---
name: content-optimization
description: When the user wants to optimize content for SEO—word count, H2 keywords, keyword density, multimedia, tables, lists. Also use when the user mentions "content length," "word count," "keyword stuffing," "H2 keywords," "keyword density," "tables," "bullet points," or "content structure." For keywords, use keyword-research.
metadata:
  version: 1.2.1
---

# SEO Content: Content Optimization

Guides on-page content optimization: word count, heading keywords, keyword density vs stuffing, multimedia, tables, and lists. Complements **heading-structure** (structure) and **content-strategy** (planning).

**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

- **Word count**: For articles, see **article-content** (word count by type). This skill covers generic content length strategy.
- **H2 keywords**: Placement, quantity, variation
- **Keyword density vs stuffing**: Natural use; avoid manipulation

Overview

Guides on-page content optimization: word count, heading keywords, keyword density vs stuffing, multimedia, tables, and lists. Complements heading-structure (structure) and content-strategy (planning).

What you get

Word countrecommendation by content type
H2 outlinewith keyword placement
Keyword densitycheck (avoid stuffing)
Structure(tables, lists) for Featured Snippet opportunity; see featured-snippet
Multimediachecklist (images per image-optimization; tables, lists)

Manual install (npx, ZIP)

Claude Codenpx skills add kostja94/marketing-skills --skill content-optimization -g -a claude-code

Claude Code (degit)npx degit kostja94/marketing-skills/skills/seo/content/content-optimization#main ~/.claude/skills/content-optimization

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.md8.2 KB

Read SKILL.md here

kostja94/main1 file shown

SKILL.md8.2 KB

Browse every file on GitHub↗

SKILL.md

Show the full text178 lines

Guides on-page content optimization: word count, heading keywords, keyword density vs stuffing, multimedia, tables, and lists. Complements heading-structure (structure) and content-strategy (planning).

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

Word count: For articles, see article-content (word count by type). This skill covers generic content length strategy.
H2 keywords: Placement, quantity, variation
Keyword density vs stuffing: Natural use; avoid manipulation
Multimedia: Images, tables, lists, video for structure and Featured Snippets. See featured-snippet for snippet-specific optimization; video-optimization for video SEO.

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:

Content type: Article, guide, listicle, pillar, news
Target keyword: Primary and secondary
Competitors: Top 10 average length and structure — see competitor-research

Word Count

Google does not rank by word count. Length should match search intent and topic depth. A 1,000-word post that satisfies intent can outrank a 3,000-word thin piece.

Reference Ranges by Content Type

For article word count by type (news, how-to, listicle, pillar, etc.), see article-content. Generic ranges:

Content type	Word count	Notes
News / announcements	300–600	Time-sensitive; concise
Standard articles / how-tos	1,000–1,500	Single topic; actionable
Listicles / guides	1,200–2,000	"Top 10," "Best X"
Pillar / cornerstone	2,000–3,500+	Comprehensive; cluster hub

Strategy

Analyze top 10 for target keyword — average length and depth
Match intent — informational often needs ~40% longer than transactional
Value over padding — each section must add genuine value; avoid fluff
Comprehensive coverage — answer the query and related questions

H2 Heading Keywords

Placement

Primary keyword: Include naturally in at least one H2 when relevant
Related keywords: Use LSI and long-tail in other H2s for topical coverage
Avoid stuffing: Headings must stay clear and readable; organic placement only

Quantity

No strict limit — one H2 per major section; structure follows content
Typical article: 4–8 H2s; pillar: 8–15+ H2s
Hierarchy: H1 → H2 (major sections) → H3 (subsections); don't skip levels

Best Practices

Practice	Purpose
Descriptive H2s	Search engines understand context; users scan
Answer-first	Place direct answer in first 40–50 words after H2 for Featured Snippets; see featured-snippet
Keyword variation	Use related terms; avoid repeating exact phrase in every H2
Logical flow	H2s outline the article; support topical authority

Keyword Density vs Keyword Stuffing

Definitions

Term	Meaning
Keyword density	(Keyword count / Total words) × 100; a metric, not a ranking factor
Keyword stuffing	Excessive, unnatural repetition to manipulate rankings; black-hat

Current Guidance

Keyword density is not a direct ranking factor — Google has stated since 2011 that repetition alone doesn't improve rankings
Reference range: 0.5%–1.5% for most content; some sources cite up to 2.5%
Use density mainly to avoid stuffing — if density exceeds ~2–3% and reads unnaturally, reduce
Prioritize natural placement: title, H1, first 100 words, 1–2 H2s, body; avoid forced repetition

How to Avoid Stuffing

Write for users first; keywords should fit naturally
Use synonyms, related terms, and question phrasing
If a sentence sounds awkward with the keyword, rewrite
Monitor: if every paragraph repeats the exact phrase, simplify

Multimedia: Images, Tables, Lists

Images

Practice	Purpose
Alt, file names, captions	See image-optimization for full image SEO (alt, format, responsive, lazy loading, image sitemap, LCP, captions for Featured Snippets)
Original over stock	Unique images signal E-E-A-T — see eeat-signals

Content placement: Put images near relevant text; captions support snippet thumbnails. See image-optimization for captions; featured-snippet for snippet context.

Video

Practice	Purpose
Embed + metadata	VideoObject schema, video sitemap, thumbnail; see video-optimization
YouTube	Google prioritizes YouTube in search; GEO citation; see youtube-seo, generative-engine-optimization
Featured Snippet (video)	Video schema; timestamps/chapters; see featured-snippet

Tables

Use for: Comparisons, stats, specs, "X vs Y"
Semantic HTML: <table>, <thead>, <tbody>, clear column headers
Featured Snippets: ~6% of snippets are tables; optimize headers with target keywords. See featured-snippet
Mobile: Responsive; avoid horizontal scroll when possible
Data quality: No empty cells; consistent units; accurate, current data

Lists: Ordered vs Unordered

Type	Use case	SEO / Snippet
Ordered (`<ol>`)	Steps, rankings, sequences, "Top 10"	List snippets (~19% of Featured Snippets); how-to; see featured-snippet
Unordered (`<ul>`)	Non-sequential items, features, options	Bullet snippets; definitions, options

Best practices:

Use semantic <ol> and <ul>; avoid divs styled as lists
Answer-first: For snippet targets, put the direct answer in the first 40–50 words after the heading
Concise items: List items should be scannable; expand in body if needed
Logical order: Ordered lists = sequence matters; unordered = no sequence

GEO / AI Citation

Answer-first (direct answer in first 40–60 words after H2) supports both Featured Snippets and GEO. For article-level GEO (TL;DR, Key Takeaways, QAE pattern), see article-content and generative-engine-optimization. For Featured Snippet formats and optimization, see featured-snippet.

Content Audit Checklist

For article content audit (hook, QAE, product connection, CTA, references, gaps), see article-content. This skill covers generic content optimization (H2 keywords, multimedia, keyword density).

Output Format

Word count recommendation by content type
H2 outline with keyword placement
Keyword density check (avoid stuffing)
Structure (tables, lists) for Featured Snippet opportunity; see featured-snippet
Multimedia checklist (images per image-optimization; tables, lists)

heading-structure: H1–H6 hierarchy; H2 keyword placement
content-strategy: Topic clusters, pillar + cluster
keyword-research: Target keywords inform placement
featured-snippet: Snippet formats, structure; answer-first
howto-section-generator: How-to step sections; <ol> lists; HowTo vs FAQ
eeat-signals: E-E-A-T; original images, trust
image-optimization: Alt, captions, format, LCP, responsive, image sitemap
video-optimization: Video SEO; VideoObject; video sitemap
competitor-research: Competitor length and structure as reference
article-content: Article word count by type; Content Audit Checklist; article body creation

1	---
2	name: content-optimization
3	description: When the user wants to optimize content for SEO—word count, H2 keywords, keyword density, multimedia, tables, lists. Also use when the user mentions "content length," "word count," "keyword stuffing," "H2 keywords," "keyword density," "tables," "bullet points," or "content structure." For keywords, use keyword-research.
4	metadata:
5	version: 1.2.1
6	---
7
8	# SEO Content: Content Optimization
9
10	Guides on-page content optimization: word count, heading keywords, keyword density vs stuffing, multimedia, tables, and lists. Complements heading-structure (structure) and content-strategy (planning).
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
15
16	- Word count: For articles, see article-content (word count by type). This skill covers generic content length strategy.
17	- H2 keywords: Placement, quantity, variation
18	- Keyword density vs stuffing: Natural use; avoid manipulation
19	- Multimedia: Images, tables, lists, video for structure and Featured Snippets. See featured-snippet for snippet-specific optimization; video-optimization for video SEO.
20
21	## Initial Assessment
22
23	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.
24
25	Identify:
26	1. Content type: Article, guide, listicle, pillar, news
27	2. Target keyword: Primary and secondary
28	3. Competitors: Top 10 average length and structure — see competitor-research
29
30	---
31
32	## Word Count
33
34	Google does not rank by word count. Length should match search intent and topic depth. A 1,000-word post that satisfies intent can outrank a 3,000-word thin piece.
35
36	### Reference Ranges by Content Type
37
38	For article word count by type (news, how-to, listicle, pillar, etc.), see article-content. Generic ranges:
39
40	\| Content type \| Word count \| Notes \|
41	\|--------------\|-------------\|-------\|
42	\| News / announcements \| 300–600 \| Time-sensitive; concise \|
43	\| Standard articles / how-tos \| 1,000–1,500 \| Single topic; actionable \|
44	\| Listicles / guides \| 1,200–2,000 \| "Top 10," "Best X" \|
45	\| Pillar / cornerstone \| 2,000–3,500+ \| Comprehensive; cluster hub \|
46
47	### Strategy
48
49	1. Analyze top 10 for target keyword — average length and depth
50	2. Match intent — informational often needs ~40% longer than transactional
51	3. Value over padding — each section must add genuine value; avoid fluff
52	4. Comprehensive coverage — answer the query and related questions
53
54	---
55
56	## H2 Heading Keywords
57
58	### Placement
59
60	- Primary keyword: Include naturally in at least one H2 when relevant
61	- Related keywords: Use LSI and long-tail in other H2s for topical coverage
62	- Avoid stuffing: Headings must stay clear and readable; organic placement only
63
64	### Quantity
65
66	- No strict limit — one H2 per major section; structure follows content
67	- Typical article: 4–8 H2s; pillar: 8–15+ H2s
68	- Hierarchy: H1 → H2 (major sections) → H3 (subsections); don't skip levels
69
70	### Best Practices
71
72	\| Practice \| Purpose \|
73	\|----------\|---------\|
74	\| Descriptive H2s \| Search engines understand context; users scan \|
75	\| Answer-first \| Place direct answer in first 40–50 words after H2 for Featured Snippets; see featured-snippet \|
76	\| Keyword variation \| Use related terms; avoid repeating exact phrase in every H2 \|
77	\| Logical flow \| H2s outline the article; support topical authority \|
78
79	---
80
81	## Keyword Density vs Keyword Stuffing
82
83	### Definitions
84
85	\| Term \| Meaning \|
86	\|------\|---------\|
87	\| Keyword density \| (Keyword count / Total words) × 100; a metric, not a ranking factor \|
88	\| Keyword stuffing \| Excessive, unnatural repetition to manipulate rankings; black-hat \|
89
90	### Current Guidance
91
92	- Keyword density is not a direct ranking factor — Google has stated since 2011 that repetition alone doesn't improve rankings
93	- Reference range: 0.5%–1.5% for most content; some sources cite up to 2.5%
94	- Use density mainly to avoid stuffing — if density exceeds ~2–3% and reads unnaturally, reduce
95	- Prioritize natural placement: title, H1, first 100 words, 1–2 H2s, body; avoid forced repetition
96
97	### How to Avoid Stuffing
98
99	- Write for users first; keywords should fit naturally
100	- Use synonyms, related terms, and question phrasing
101	- If a sentence sounds awkward with the keyword, rewrite
102	- Monitor: if every paragraph repeats the exact phrase, simplify
103
104	---
105
106	## Multimedia: Images, Tables, Lists
107
108	### Images
109
110	\| Practice \| Purpose \|
111	\|----------\|---------\|
112	\| Alt, file names, captions \| See image-optimization for full image SEO (alt, format, responsive, lazy loading, image sitemap, LCP, captions for Featured Snippets) \|
113	\| Original over stock \| Unique images signal E-E-A-T — see eeat-signals \|
114
115	Content placement: Put images near relevant text; captions support snippet thumbnails. See image-optimization for captions; featured-snippet for snippet context.
116
117	### Video
118
119	\| Practice \| Purpose \|
120	\|----------\|---------\|
121	\| Embed + metadata \| VideoObject schema, video sitemap, thumbnail; see video-optimization \|
122	\| YouTube \| Google prioritizes YouTube in search; GEO citation; see youtube-seo, generative-engine-optimization \|
123	\| Featured Snippet (video) \| Video schema; timestamps/chapters; see featured-snippet \|
124
125	### Tables
126
127	- Use for: Comparisons, stats, specs, "X vs Y"
128	- Semantic HTML: `<table>`, `<thead>`, `<tbody>`, clear column headers
129	- Featured Snippets: ~6% of snippets are tables; optimize headers with target keywords. See featured-snippet
130	- Mobile: Responsive; avoid horizontal scroll when possible
131	- Data quality: No empty cells; consistent units; accurate, current data
132
133	### Lists: Ordered vs Unordered
134
135	\| Type \| Use case \| SEO / Snippet \|
136	\|------\|----------\|---------------\|
137	\| Ordered (`<ol>`) \| Steps, rankings, sequences, "Top 10" \| List snippets (~19% of Featured Snippets); how-to; see featured-snippet \|
138	\| Unordered (`<ul>`) \| Non-sequential items, features, options \| Bullet snippets; definitions, options \|
139
140	Best practices:
141	- Use semantic `<ol>` and `<ul>`; avoid divs styled as lists
142	- Answer-first: For snippet targets, put the direct answer in the first 40–50 words after the heading
143	- Concise items: List items should be scannable; expand in body if needed
144	- Logical order: Ordered lists = sequence matters; unordered = no sequence
145
146	### GEO / AI Citation
147
148	Answer-first (direct answer in first 40–60 words after H2) supports both Featured Snippets and GEO. For article-level GEO (TL;DR, Key Takeaways, QAE pattern), see article-content and generative-engine-optimization. For Featured Snippet formats and optimization, see featured-snippet.
149
150	---
151
152	## Content Audit Checklist
153
154	For article content audit (hook, QAE, product connection, CTA, references, gaps), see article-content. This skill covers generic content optimization (H2 keywords, multimedia, keyword density).
155
156	---
157
158	## Output Format
159
160	- Word count recommendation by content type
161	- H2 outline with keyword placement
162	- Keyword density check (avoid stuffing)
163	- Structure (tables, lists) for Featured Snippet opportunity; see featured-snippet
164	- Multimedia checklist (images per image-optimization; tables, lists)
165
166	## Related Skills
167
168	- heading-structure: H1–H6 hierarchy; H2 keyword placement
169	- content-strategy: Topic clusters, pillar + cluster
170	- keyword-research: Target keywords inform placement
171	- featured-snippet: Snippet formats, structure; answer-first
172	- howto-section-generator: How-to step sections; `<ol>` lists; HowTo vs FAQ
173	- eeat-signals: E-E-A-T; original images, trust
174	- image-optimization: Alt, captions, format, LCP, responsive, image sitemap
175	- video-optimization: Video SEO; VideoObject; video sitemap
176	- competitor-research: Competitor length and structure as reference
177	- article-content: Article word count by type; Content Audit Checklist; article body creation
178