claude-plugin-wordpress-manager 2.4.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/.claude-plugin/plugin.json +10 -3
  2. package/CHANGELOG.md +42 -0
  3. package/agents/wp-content-strategist.md +104 -0
  4. package/docs/GUIDE.md +183 -23
  5. package/package.json +12 -3
  6. package/servers/wp-rest-bridge/build/tools/comments.d.ts +6 -6
  7. package/servers/wp-rest-bridge/build/tools/gsc.d.ts +3 -0
  8. package/servers/wp-rest-bridge/build/tools/gsc.js +354 -0
  9. package/servers/wp-rest-bridge/build/tools/index.d.ts +38 -38
  10. package/servers/wp-rest-bridge/build/tools/index.js +3 -0
  11. package/servers/wp-rest-bridge/build/tools/media.d.ts +2 -2
  12. package/servers/wp-rest-bridge/build/tools/multisite-sites.d.ts +2 -2
  13. package/servers/wp-rest-bridge/build/tools/plugin-repository.d.ts +1 -1
  14. package/servers/wp-rest-bridge/build/tools/search.d.ts +2 -2
  15. package/servers/wp-rest-bridge/build/tools/unified-content.d.ts +8 -8
  16. package/servers/wp-rest-bridge/build/tools/unified-taxonomies.d.ts +4 -4
  17. package/servers/wp-rest-bridge/build/tools/users.d.ts +6 -6
  18. package/servers/wp-rest-bridge/build/tools/wc-coupons.d.ts +1 -1
  19. package/servers/wp-rest-bridge/build/tools/wc-customers.d.ts +3 -3
  20. package/servers/wp-rest-bridge/build/tools/wc-orders.d.ts +4 -4
  21. package/servers/wp-rest-bridge/build/tools/wc-products.d.ts +8 -8
  22. package/servers/wp-rest-bridge/build/tools/wc-webhooks.d.ts +4 -4
  23. package/servers/wp-rest-bridge/build/wordpress.d.ts +5 -0
  24. package/servers/wp-rest-bridge/build/wordpress.js +39 -0
  25. package/servers/wp-rest-bridge/package.json +1 -0
  26. package/skills/wordpress-router/references/decision-tree.md +6 -2
  27. package/skills/wp-content/SKILL.md +1 -0
  28. package/skills/wp-content-attribution/SKILL.md +2 -0
  29. package/skills/wp-content-optimization/SKILL.md +172 -0
  30. package/skills/wp-content-optimization/references/content-freshness.md +234 -0
  31. package/skills/wp-content-optimization/references/headline-optimization.md +171 -0
  32. package/skills/wp-content-optimization/references/meta-optimization.md +243 -0
  33. package/skills/wp-content-optimization/references/readability-analysis.md +201 -0
  34. package/skills/wp-content-optimization/references/seo-content-scoring.md +245 -0
  35. package/skills/wp-content-optimization/scripts/content_optimization_inspect.mjs +237 -0
  36. package/skills/wp-monitoring/SKILL.md +1 -0
  37. package/skills/wp-programmatic-seo/SKILL.md +2 -0
  38. package/skills/wp-search-console/SKILL.md +121 -0
  39. package/skills/wp-search-console/references/competitor-gap-analysis.md +226 -0
  40. package/skills/wp-search-console/references/content-seo-feedback.md +181 -0
  41. package/skills/wp-search-console/references/gsc-setup.md +110 -0
  42. package/skills/wp-search-console/references/indexing-management.md +182 -0
  43. package/skills/wp-search-console/references/keyword-tracking.md +181 -0
  44. package/skills/wp-search-console/scripts/search_console_inspect.mjs +178 -0
@@ -0,0 +1,243 @@
1
+ # Meta Description and Title Tag Optimization
2
+
3
+ ## Overview
4
+
5
+ Title tags and meta descriptions are the first impression users see in search results. Optimizing these elements directly impacts click-through rate (CTR). Claude generates optimized meta elements by combining best practices with GSC CTR data, then produces A/B variants for testing. This process uses existing WP REST Bridge and GSC tools — no additional APIs needed.
6
+
7
+ ## Title Tag Best Practices
8
+
9
+ ### Rules
10
+
11
+ | Rule | Standard |
12
+ |------|----------|
13
+ | Maximum length | 60 characters (Google truncates at ~60) |
14
+ | Keyword placement | Primary keyword in the first 3-4 words |
15
+ | Uniqueness | Every page must have a unique title |
16
+ | Brand inclusion | Optional, at end with pipe separator |
17
+ | Keyword repetition | Keyword appears once only |
18
+ | Readability | Must make sense as a standalone phrase |
19
+
20
+ ### Title Tag Formula
21
+ ```
22
+ [Primary Keyword] — [Benefit or Differentiator] | [Brand]
23
+ ```
24
+
25
+ ### Character Count Optimization
26
+ ```
27
+ Ideal: 50-60 characters (full display in all search results)
28
+ OK: 40-50 characters (may look short but fully visible)
29
+ Warning: 60-65 characters (partial truncation on some devices)
30
+ Error: 65+ characters (truncated, meaning lost)
31
+ Too Short: <30 characters (underutilizing title space)
32
+ ```
33
+
34
+ ### Examples
35
+ ```
36
+ Good (55 chars): "WordPress Speed Optimization — 10 Proven Techniques | Brand"
37
+ Good (48 chars): "How to Speed Up WordPress in 2026 | Brand"
38
+ Bad (72 chars): "The Complete and Ultimate Guide to WordPress Speed Optimization Tips 2026"
39
+ Bad (18 chars): "Speed Tips"
40
+ ```
41
+
42
+ ## Meta Description Guidelines
43
+
44
+ ### Rules
45
+
46
+ | Rule | Standard |
47
+ |------|----------|
48
+ | Maximum length | 155-160 characters |
49
+ | Minimum length | 120 characters (shorter looks incomplete) |
50
+ | Keyword inclusion | Primary keyword once, naturally |
51
+ | Call to action | Include an action verb (learn, discover, get, try) |
52
+ | Uniqueness | Every page must have a unique description |
53
+ | Emotional trigger | Include benefit or pain point |
54
+ | Specificity | Use numbers, data, or specific outcomes |
55
+
56
+ ### Meta Description Formula
57
+ ```
58
+ [Action verb] [what the reader gets/learns]. [Specific detail or data point]. [CTA].
59
+ ```
60
+
61
+ ### Examples
62
+ ```
63
+ Good (152 chars):
64
+ "Learn 10 proven WordPress speed optimization techniques that cut load time
65
+ by 50%. Step-by-step guide with benchmarks. Start optimizing today."
66
+
67
+ Bad (89 chars):
68
+ "This article is about WordPress speed optimization. Read more on our website."
69
+
70
+ Bad (185 chars):
71
+ "In this comprehensive and detailed guide we will cover everything you need to
72
+ know about optimizing your WordPress website for speed including caching and
73
+ image optimization techniques."
74
+ ```
75
+
76
+ ## Using GSC CTR Data for Optimization
77
+
78
+ ### Identifying Low-CTR Pages
79
+
80
+ #### Step 1: Pull Page Performance Data
81
+ ```
82
+ Use gsc_page_performance to get CTR data for all pages.
83
+ Sort by impressions (descending) to focus on high-visibility pages first.
84
+ ```
85
+
86
+ #### Step 2: CTR Benchmarks by Position
87
+
88
+ | Average Position | Expected CTR | Below Average |
89
+ |-----------------|-------------|---------------|
90
+ | 1 | 25-35% | <20% |
91
+ | 2 | 12-18% | <10% |
92
+ | 3 | 8-12% | <6% |
93
+ | 4-5 | 5-8% | <4% |
94
+ | 6-10 | 2-5% | <2% |
95
+
96
+ #### Step 3: Flag Optimization Candidates
97
+ Pages with high impressions but below-average CTR are prime candidates:
98
+ ```
99
+ Example:
100
+ Page: /wordpress-speed-guide
101
+ Position: 3
102
+ Impressions: 5,000/month
103
+ CTR: 4.2% (expected 8-12% for position 3)
104
+ → META OPTIMIZATION NEEDED — potential to double clicks
105
+ ```
106
+
107
+ #### Step 4: Analyze Current Meta
108
+ ```
109
+ Use get_content to fetch the current title tag and meta description.
110
+ Evaluate against the rules above.
111
+ Identify specific issues (too long, missing keyword, no CTA, etc.).
112
+ ```
113
+
114
+ ### CTR Impact Estimation
115
+ ```
116
+ Current: Position 3, 5000 impressions, 4.2% CTR = 210 clicks/month
117
+ After optimization to 8% CTR: 5000 × 0.08 = 400 clicks/month
118
+ Potential gain: +190 clicks/month (+90% improvement)
119
+ ```
120
+
121
+ ## A/B Variant Generation
122
+
123
+ ### Process
124
+
125
+ #### Step 1: Generate Two Variants
126
+ Claude generates two meta description variants using different approaches:
127
+
128
+ **Variant A: Benefit-focused**
129
+ ```
130
+ "Cut your WordPress load time by 50% with these 10 proven optimization
131
+ techniques. Includes caching, image compression, and CDN setup. Free guide."
132
+ ```
133
+
134
+ **Variant B: Problem-focused**
135
+ ```
136
+ "Slow WordPress site losing visitors? Fix it with 10 tested speed
137
+ techniques. Average improvement: 50% faster. Step-by-step instructions."
138
+ ```
139
+
140
+ #### Step 2: Score Both Variants
141
+
142
+ | Criteria | Variant A | Variant B |
143
+ |----------|-----------|-----------|
144
+ | Keyword presence | Yes (1st sentence) | Yes (1st sentence) |
145
+ | Length | 148 chars ✓ | 142 chars ✓ |
146
+ | CTA | "Free guide" | "Step-by-step" |
147
+ | Emotional trigger | Benefit (cut load time) | Pain (losing visitors) |
148
+ | Specificity | 50%, 10 techniques | 50% faster |
149
+ | Readability | Clear | Clear |
150
+
151
+ #### Step 3: Apply and Monitor
152
+ ```
153
+ Apply the highest-scoring variant via update_content.
154
+ Set a review date 2-4 weeks out.
155
+ Compare CTR data in GSC after the review period.
156
+ ```
157
+
158
+ ### Title Tag A/B Variants
159
+ Same process for title tags:
160
+ ```
161
+ Original: "WordPress Speed Guide"
162
+ Variant A: "WordPress Speed Optimization — 10 Techniques That Work"
163
+ Variant B: "How to Speed Up WordPress by 50% (2026 Guide)"
164
+ ```
165
+
166
+ ## Rich Snippet Optimization
167
+
168
+ ### Content-Type Specific Guidance
169
+
170
+ | Content Type | Rich Snippet Opportunity | Meta Optimization |
171
+ |-------------|------------------------|-------------------|
172
+ | How-to articles | HowTo schema | Include "how to" in title, steps count in meta |
173
+ | FAQ pages | FAQPage schema | Include question in title, "answers" in meta |
174
+ | Product pages | Product schema (rating, price) | Include price/rating in meta |
175
+ | Review posts | Review schema (star rating) | Include rating in title/meta |
176
+ | List posts | ItemList schema | Include count in title ("10 Best...") |
177
+
178
+ ### Meta for Featured Snippets
179
+ To optimize for position zero:
180
+ - Structure content to answer specific questions
181
+ - Use the question as an H2 heading
182
+ - Provide a concise answer in the first paragraph (40-60 words)
183
+ - Follow with detailed explanation
184
+ - Include a summary table or list
185
+
186
+ ## Step-by-Step Workflow
187
+
188
+ ### Step 1: Identify Optimization Targets
189
+ ```
190
+ Use gsc_page_performance to find pages with:
191
+ - High impressions (>500/month)
192
+ - Below-average CTR for their position
193
+ - Sort by potential impact (impressions × CTR gap)
194
+ ```
195
+
196
+ ### Step 2: Fetch Current Meta Elements
197
+ ```
198
+ Use get_content for each target page.
199
+ Extract: title tag, meta description, H1, URL slug.
200
+ ```
201
+
202
+ ### Step 3: Analyze and Score Current Meta
203
+ Claude evaluates each element against rules above:
204
+ - Title: length, keyword position, clarity, brand
205
+ - Description: length, keyword, CTA, emotional trigger, specificity
206
+
207
+ ### Step 4: Generate Optimized Variants
208
+ For each page, Claude produces:
209
+ - 2 title tag variants
210
+ - 2 meta description variants
211
+ - Score comparison with current version
212
+ - Estimated CTR impact
213
+
214
+ ### Step 5: Apply Changes
215
+ ```
216
+ Use update_content to apply the winning variants.
217
+ Document changes for tracking:
218
+ - Page URL
219
+ - Previous title/meta
220
+ - New title/meta
221
+ - Date changed
222
+ - Baseline CTR from GSC
223
+ ```
224
+
225
+ ### Step 6: Monitor Results
226
+ After 2-4 weeks:
227
+ ```
228
+ Use gsc_page_performance to pull updated CTR data.
229
+ Compare against baseline.
230
+ Iterate if CTR did not improve.
231
+ ```
232
+
233
+ ## Best Practices
234
+
235
+ - Prioritize high-impression pages first (biggest impact from small CTR gains)
236
+ - Never duplicate meta descriptions across pages
237
+ - Avoid meta descriptions that do not match page content (causes bounce)
238
+ - Include the year in title tags for time-sensitive content (guides, reviews)
239
+ - Use active voice and power verbs in meta descriptions
240
+ - Test one change at a time to isolate impact
241
+ - Review and refresh meta descriptions quarterly
242
+ - Consider search intent when crafting meta — informational vs transactional queries need different approaches
243
+ - Do not force keywords into meta descriptions unnaturally — readability trumps keyword presence
@@ -0,0 +1,201 @@
1
+ # Readability Analysis
2
+
3
+ ## Overview
4
+
5
+ Readability analysis measures how easy content is to read and understand. Claude performs Flesch-Kincaid scoring, sentence length analysis, passive voice detection, paragraph assessment, and jargon identification directly on WordPress content — no external readability tools required. The goal is web-optimized content that matches the target audience's reading level.
6
+
7
+ ## Flesch-Kincaid Scoring
8
+
9
+ ### Formula
10
+ ```
11
+ Flesch Reading Ease = 206.835 - (1.015 × ASL) - (84.6 × ASW)
12
+
13
+ Where:
14
+ ASL = Average Sentence Length (words per sentence)
15
+ ASW = Average Syllables per Word
16
+ ```
17
+
18
+ ### Score Interpretation
19
+
20
+ | Score | Grade Level | Audience | Action |
21
+ |-------|-------------|----------|--------|
22
+ | 90-100 | 5th grade | Very easy, children | Too simple for most web content |
23
+ | 80-89 | 6th grade | Easy, conversational | Good for broad consumer content |
24
+ | 70-79 | 7th grade | Fairly easy | Good for general web content |
25
+ | 60-69 | 8th-9th grade | Standard | **Target for most WordPress content** |
26
+ | 50-59 | 10th-12th grade | Fairly difficult | Acceptable for professional audience |
27
+ | 30-49 | College | Difficult | Only for specialized/technical content |
28
+ | 0-29 | Graduate | Very difficult | Rewrite for web consumption |
29
+
30
+ ### Target Scores by Content Type
31
+
32
+ | Content Type | Target Score | Rationale |
33
+ |--------------|-------------|-----------|
34
+ | Blog posts | 60-70 | General audience, scannable |
35
+ | Product descriptions | 65-75 | Clear, benefit-focused |
36
+ | Technical documentation | 45-60 | Professional audience |
37
+ | Landing pages | 70-80 | Must be instantly clear |
38
+ | Email newsletters | 65-75 | Quick reading format |
39
+
40
+ ## Sentence Length Analysis
41
+
42
+ ### Guidelines
43
+
44
+ | Metric | Target | Flag Threshold |
45
+ |--------|--------|----------------|
46
+ | Average sentence length | 15-20 words | >20 words average |
47
+ | Maximum sentence length | 35 words | >40 words |
48
+ | Short sentence ratio | 20-30% under 10 words | <10% short sentences |
49
+ | Variety | Mix of short, medium, long | All same length |
50
+
51
+ ### Sentence Length Distribution
52
+ Ideal content alternates between sentence lengths for rhythm:
53
+ ```
54
+ Short sentence (5-10 words). ← Punchy, creates emphasis
55
+ Medium sentence (11-20 words). ← Core information delivery
56
+ Long sentence (21-30 words). ← Complex ideas, supporting detail
57
+ Short sentence (5-10 words). ← Reset reader attention
58
+ ```
59
+
60
+ ### Fixing Long Sentences
61
+ Strategies for breaking up long sentences:
62
+ 1. **Split at conjunctions** — break at "and", "but", "while", "although"
63
+ 2. **Remove relative clauses** — move "which" and "that" clauses to new sentences
64
+ 3. **Use bullet lists** — convert compound sentences into scannable lists
65
+ 4. **Front-load the point** — put the main idea first, details after
66
+
67
+ ### Example
68
+ ```
69
+ Before (38 words):
70
+ "WordPress is a content management system that allows users to create websites
71
+ and blogs with themes and plugins, which can be customized to match any brand
72
+ identity and extended with additional functionality."
73
+
74
+ After (two sentences, 15 + 16 words):
75
+ "WordPress is a content management system for creating websites and blogs.
76
+ Themes and plugins let you customize the design and extend functionality."
77
+ ```
78
+
79
+ ## Passive Voice Detection
80
+
81
+ ### What to Flag
82
+ Passive voice constructions where the subject receives the action:
83
+ ```
84
+ Passive: "The plugin was installed by the user."
85
+ Active: "The user installed the plugin."
86
+ ```
87
+
88
+ ### Target
89
+ - Maximum 10% of sentences in passive voice
90
+ - 5% or less is ideal for web content
91
+
92
+ ### Common Passive Patterns
93
+ | Passive Pattern | Active Rewrite |
94
+ |----------------|----------------|
95
+ | "was created by" | "[subject] created" |
96
+ | "is recommended" | "we recommend" |
97
+ | "can be configured" | "you can configure" |
98
+ | "has been updated" | "we updated" / "[subject] updated" |
99
+ | "should be installed" | "install" (imperative) |
100
+
101
+ ### When Passive Is Acceptable
102
+ - Scientific or technical writing where the actor is irrelevant
103
+ - When the object is more important than the subject
104
+ - Policy or legal statements
105
+
106
+ ## Paragraph Length Guidelines
107
+
108
+ | Metric | Target | Flag |
109
+ |--------|--------|------|
110
+ | Sentences per paragraph | 2-4 | >5 sentences |
111
+ | Words per paragraph | 40-80 | >100 words |
112
+ | One-sentence paragraphs | Occasional for emphasis | >3 consecutive |
113
+ | Wall of text | Never | Any paragraph >150 words |
114
+
115
+ ### Web-Specific Rules
116
+ - Break up paragraphs more aggressively than print
117
+ - Use subheadings every 200-300 words
118
+ - Include visual breaks (images, lists, blockquotes) every 300-400 words
119
+ - One idea per paragraph
120
+
121
+ ## Jargon and Complexity Detection
122
+
123
+ ### Flag These Patterns
124
+ 1. **Industry jargon** — terms unknown to general audience (e.g., "canonical URL", "transclusion")
125
+ 2. **Acronyms without definition** — first use must define the acronym
126
+ 3. **Multi-syllable alternatives** — when simpler words exist
127
+ 4. **Nominalization** — turning verbs into nouns ("optimization" instead of "optimize")
128
+ 5. **Double negatives** — "not uncommon" instead of "common"
129
+
130
+ ### Simplification Table
131
+
132
+ | Complex | Simple |
133
+ |---------|--------|
134
+ | utilize | use |
135
+ | implement | add / set up |
136
+ | functionality | feature |
137
+ | methodology | method |
138
+ | in order to | to |
139
+ | at this point in time | now |
140
+ | a large number of | many |
141
+ | in the event that | if |
142
+ | prior to | before |
143
+ | subsequent to | after |
144
+
145
+ ## Step-by-Step Workflow
146
+
147
+ ### Step 1: Fetch Content
148
+ ```
149
+ Use get_content with the post ID to retrieve full body content.
150
+ Strip HTML tags for text-only analysis.
151
+ ```
152
+
153
+ ### Step 2: Compute Metrics
154
+ Claude analyzes the plain text and computes:
155
+ - Total word count
156
+ - Total sentence count
157
+ - Average sentence length (words/sentences)
158
+ - Estimated Flesch-Kincaid score
159
+ - Passive voice percentage
160
+ - Average paragraph length
161
+ - Jargon terms identified
162
+
163
+ ### Step 3: Generate Report
164
+ ```
165
+ Readability Report for: "Post Title"
166
+ ═══════════════════════════════════
167
+ Flesch-Kincaid Score: 58 (target: 60-70) ⚠ Below target
168
+ Average Sentence Length: 22 words (target: <20) ⚠ Too long
169
+ Passive Voice: 15% (target: <10%) ⚠ Too high
170
+ Avg Paragraph Length: 95 words (target: <80) ⚠ Long paragraphs
171
+ Jargon Terms Found: 3 (canonical, transclusion, REST endpoint)
172
+
173
+ Top Issues:
174
+ 1. 5 sentences over 35 words — break into shorter sentences
175
+ 2. 3 paragraphs over 100 words — split with subheadings
176
+ 3. "canonical URL" used without definition — add brief explanation
177
+ ```
178
+
179
+ ### Step 4: Suggest Improvements
180
+ Claude generates specific rewrite suggestions:
181
+ - Rewrites for the 3 longest sentences
182
+ - Paragraph split points with suggested subheadings
183
+ - Passive-to-active voice conversions
184
+ - Jargon simplifications or definitions to add
185
+
186
+ ### Step 5: Apply Changes (Optional)
187
+ ```
188
+ Use update_content to apply approved changes.
189
+ Preserve all HTML structure, links, and media.
190
+ Only modify text content for readability improvements.
191
+ ```
192
+
193
+ ## Best Practices
194
+
195
+ - Always analyze the full post body, not just excerpts
196
+ - Consider the target audience when evaluating scores (technical docs have lower target)
197
+ - Preserve the author's voice — readability improvements should not flatten style
198
+ - Do not oversimplify to the point of losing nuance or accuracy
199
+ - Run readability analysis after SEO optimization to ensure keyword insertion did not harm readability
200
+ - Check readability on both desktop and mobile (shorter paragraphs matter more on mobile)
201
+ - Use transition words (however, therefore, for example) to maintain flow after sentence splitting
@@ -0,0 +1,245 @@
1
+ # SEO Content Scoring
2
+
3
+ ## Overview
4
+
5
+ SEO content scoring evaluates how well a piece of WordPress content is optimized for search engines. Claude performs keyword density analysis, heading hierarchy assessment, internal and external linking checks, image alt text coverage, and content structure evaluation. When GSC data is available, Claude cross-references actual search queries to validate keyword targeting.
6
+
7
+ ## Keyword Density Analysis
8
+
9
+ ### Target Ranges
10
+
11
+ | Keyword Type | Target Density | Minimum | Maximum |
12
+ |-------------|---------------|---------|---------|
13
+ | Primary keyword | 1-2% | 0.5% | 3% |
14
+ | Secondary keywords | 0.5-1% each | 0.3% | 1.5% |
15
+ | LSI/related terms | Natural occurrence | — | — |
16
+
17
+ ### Density Calculation
18
+ ```
19
+ Keyword Density = (Number of keyword occurrences / Total word count) × 100
20
+ ```
21
+
22
+ ### Placement Rules
23
+ 1. **Title (H1)** — primary keyword must appear (preferably front-loaded)
24
+ 2. **First paragraph** — primary keyword within first 100 words
25
+ 3. **Subheadings** — primary or secondary keyword in at least 1 H2
26
+ 4. **Body distribution** — keyword spread throughout, not clustered
27
+ 5. **Last paragraph** — primary keyword in conclusion
28
+ 6. **URL slug** — primary keyword in the URL
29
+
30
+ ### Keyword Stuffing Detection
31
+ Flag when:
32
+ - Primary keyword density exceeds 3%
33
+ - Same keyword appears in consecutive sentences
34
+ - Keyword is forced into unnatural phrasing
35
+ - Multiple exact-match keyword repetitions in one paragraph
36
+
37
+ ### Example Analysis
38
+ ```
39
+ Post: "WordPress Speed Optimization Guide" (1500 words)
40
+ Primary keyword: "wordpress speed optimization"
41
+
42
+ Occurrences: 18 times
43
+ Density: 18/1500 × 100 = 1.2% ✓ Within target
44
+
45
+ Distribution:
46
+ - Title: ✓ Present
47
+ - First paragraph: ✓ Present (word 12)
48
+ - H2 headings: ✓ 1 of 4 H2s contains keyword
49
+ - Last paragraph: ✓ Present
50
+ - URL: ✓ /wordpress-speed-optimization-guide
51
+ ```
52
+
53
+ ## H2/H3 Hierarchy Coverage
54
+
55
+ ### Structure Requirements
56
+
57
+ | Element | Requirement | Check |
58
+ |---------|------------|-------|
59
+ | H1 | Exactly 1 per page, contains primary keyword | Required |
60
+ | H2 | 2-6 per post, secondary keywords in 50%+ | Required |
61
+ | H3 | As needed under H2, long-tail keywords | Recommended |
62
+ | H4+ | Rare, deep detail only | Optional |
63
+ | Skip levels | Never (H1 → H3 without H2) | Flag as error |
64
+
65
+ ### Heading Optimization Checklist
66
+ - [ ] One H1 only, matching the post title
67
+ - [ ] H2s outline the main sections (scannable table of contents)
68
+ - [ ] At least one H2 contains the primary keyword
69
+ - [ ] H3s provide detail under their parent H2
70
+ - [ ] No heading level is skipped
71
+ - [ ] Headings are descriptive (not generic like "More Info")
72
+ - [ ] Secondary keywords distributed across H2/H3 headings
73
+
74
+ ### Example Heading Audit
75
+ ```
76
+ H1: WordPress Speed Optimization: Complete Guide ✓ Primary keyword
77
+ H2: Why WordPress Speed Matters ✓ Descriptive
78
+ H3: Impact on SEO Rankings ✓ Secondary keyword
79
+ H3: Impact on User Experience ✓ Related term
80
+ H2: How to Measure WordPress Speed ✓ Secondary keyword
81
+ H2: 10 WordPress Speed Optimization Techniques ✓ Primary keyword
82
+ H3: Enable Caching ✓ Specific
83
+ H3: Optimize Images ✓ Specific
84
+ H3: Minimize CSS and JavaScript ✓ Specific
85
+ H2: Conclusion ⚠ Generic, add keyword
86
+ ```
87
+
88
+ ## Internal Linking Analysis
89
+
90
+ ### Minimum Standards
91
+
92
+ | Content Length | Internal Links | Rationale |
93
+ |---------------|---------------|-----------|
94
+ | < 500 words | 1-2 links | Short content, few linking opportunities |
95
+ | 500-1000 words | 2-3 links | Standard blog post |
96
+ | 1000-2000 words | 3-5 links | In-depth article |
97
+ | 2000+ words | 5-8 links | Pillar content, extensive topic |
98
+
99
+ ### What to Check
100
+ 1. **Link count** — meets minimum for content length
101
+ 2. **Anchor text** — descriptive, keyword-rich (not "click here")
102
+ 3. **Link relevance** — linked pages are topically related
103
+ 4. **Link distribution** — links spread throughout content, not clustered
104
+ 5. **Orphan detection** — identify posts with zero inbound internal links
105
+ 6. **Reciprocal links** — pillar pages link to cluster posts and vice versa
106
+
107
+ ### Link Opportunity Detection
108
+ Claude identifies linking opportunities by:
109
+ - Finding mentions of topics that have dedicated pages on the site
110
+ - Detecting keyword phrases that match other post titles
111
+ - Identifying related content that could provide context
112
+ - Suggesting links to pillar pages from cluster content
113
+
114
+ ## External Linking
115
+
116
+ ### Guidelines
117
+
118
+ | Metric | Target |
119
+ |--------|--------|
120
+ | External links per post | 1-2 minimum |
121
+ | Link targets | Authoritative, relevant sources (.gov, .edu, industry leaders) |
122
+ | Link freshness | Source content should be current (not outdated) |
123
+ | Nofollow | Use for sponsored or untrusted links |
124
+ | Open in new tab | Yes for external links (target="_blank") |
125
+
126
+ ### What to Avoid
127
+ - Linking to direct competitors' commercial pages
128
+ - Linking to low-authority or spammy sites
129
+ - Excessive external links (>5 per 1000 words)
130
+ - Broken external links (check periodically)
131
+
132
+ ## Image Alt Text Coverage
133
+
134
+ ### Requirements
135
+ | Check | Standard |
136
+ |-------|----------|
137
+ | All images have alt text | 100% coverage required |
138
+ | Alt text includes keyword | At least 1 image per post |
139
+ | Alt text is descriptive | Describes the image content |
140
+ | Alt text length | 5-15 words |
141
+ | Decorative images | Empty alt="" (not missing alt) |
142
+
143
+ ### Example
144
+ ```
145
+ Good: alt="WordPress performance optimization dashboard showing page load times"
146
+ Bad: alt="image1" or alt="" (on informational image) or alt missing
147
+ ```
148
+
149
+ ## Combining with GSC Data
150
+
151
+ When Google Search Console is available, enrich the SEO scoring with real search data:
152
+
153
+ ### Step 1: Fetch Search Queries for the Page
154
+ ```
155
+ Use gsc_search_analytics with the page URL to get actual queries driving traffic.
156
+ ```
157
+
158
+ ### Step 2: Compare Target vs Actual Keywords
159
+ ```
160
+ Target keyword: "wordpress speed optimization"
161
+ Actual top queries from GSC:
162
+ 1. "wordpress speed" (pos 8, 500 impressions)
163
+ 2. "wordpress performance" (pos 12, 300 impressions)
164
+ 3. "how to speed up wordpress" (pos 15, 200 impressions)
165
+
166
+ Analysis: Content ranks for related terms but not the exact target.
167
+ Action: Strengthen primary keyword presence, add "how to speed up wordpress" as H2.
168
+ ```
169
+
170
+ ### Step 3: Identify Keyword Gaps
171
+ - Queries with high impressions but low CTR → meta description issue
172
+ - Queries with high position (>10) → content depth issue
173
+ - Queries the page ranks for that are not in the content → add sections
174
+
175
+ ## SEO Content Score Card
176
+
177
+ ### Scoring Template
178
+ ```
179
+ SEO Content Score for: "Post Title"
180
+ ═════════════════════════════════════
181
+ Keyword Density: 1.2% ✓ (target: 1-2%)
182
+ Keyword in H1: Yes ✓
183
+ Keyword in First 100: Yes ✓
184
+ Keyword in URL: Yes ✓
185
+
186
+ H2 Count: 4 ✓ (target: 2-6)
187
+ H2 with Keywords: 2/4 ✓ (target: 50%+)
188
+ H3 Count: 6 ✓
189
+ Heading Hierarchy: Valid ✓ (no skipped levels)
190
+
191
+ Internal Links: 2 ⚠ (target: 3-5 for 1200 words)
192
+ External Links: 1 ✓ (target: 1-2)
193
+ Anchor Text Quality: Good ✓
194
+
195
+ Image Alt Coverage: 3/4 ⚠ (1 image missing alt text)
196
+ Keyword in Alt: 1/4 ✓
197
+
198
+ Overall Score: 7.5/10
199
+ Priority Fixes:
200
+ 1. Add 1-2 more internal links to related content
201
+ 2. Add alt text to image in section 3
202
+ ```
203
+
204
+ ## Step-by-Step Workflow
205
+
206
+ ### Step 1: Fetch Content
207
+ ```
208
+ Use get_content to retrieve the full post HTML.
209
+ Parse headings, links, images, and body text.
210
+ ```
211
+
212
+ ### Step 2: Identify Target Keyword
213
+ Either provided by user or extracted from:
214
+ - Post title analysis
215
+ - GSC top query for the URL
216
+ - Content theme analysis
217
+
218
+ ### Step 3: Run All Checks
219
+ Claude analyzes in sequence:
220
+ 1. Keyword density and placement
221
+ 2. Heading hierarchy and keyword coverage
222
+ 3. Internal and external link audit
223
+ 4. Image alt text coverage
224
+ 5. GSC data cross-reference (if available)
225
+
226
+ ### Step 4: Generate Score Card
227
+ Produce the formatted score card with pass/fail for each criterion.
228
+
229
+ ### Step 5: Prioritize Fixes
230
+ Rank issues by impact:
231
+ 1. Missing keyword in title/H1 (highest impact)
232
+ 2. Keyword density out of range
233
+ 3. No internal links
234
+ 4. Missing alt text
235
+ 5. Heading hierarchy issues
236
+ 6. External link additions
237
+
238
+ ## Best Practices
239
+
240
+ - Run SEO scoring before publishing (pre-publish checklist)
241
+ - Re-score after content updates to ensure changes did not break optimization
242
+ - Use GSC data to validate keyword targeting against real search behavior
243
+ - Do not sacrifice readability for SEO score — readability comes first
244
+ - Update scoring analysis quarterly as search patterns evolve
245
+ - Track score changes over time to measure optimization impact