claude-plugin-wordpress-manager 2.3.1 → 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 (65) hide show
  1. package/.claude-plugin/plugin.json +15 -3
  2. package/CHANGELOG.md +62 -0
  3. package/agents/wp-content-strategist.md +104 -0
  4. package/agents/wp-distribution-manager.md +98 -0
  5. package/docs/GUIDE.md +183 -23
  6. package/docs/plans/2026-03-01-tier3-wcop-design.md +373 -0
  7. package/docs/plans/2026-03-01-tier3-wcop-implementation.md +915 -0
  8. package/hooks/hooks.json +18 -0
  9. package/package.json +18 -3
  10. package/servers/wp-rest-bridge/build/tools/buffer.d.ts +3 -0
  11. package/servers/wp-rest-bridge/build/tools/buffer.js +205 -0
  12. package/servers/wp-rest-bridge/build/tools/comments.d.ts +6 -6
  13. package/servers/wp-rest-bridge/build/tools/gsc.d.ts +3 -0
  14. package/servers/wp-rest-bridge/build/tools/gsc.js +354 -0
  15. package/servers/wp-rest-bridge/build/tools/index.d.ts +38 -38
  16. package/servers/wp-rest-bridge/build/tools/index.js +12 -0
  17. package/servers/wp-rest-bridge/build/tools/mailchimp.d.ts +3 -0
  18. package/servers/wp-rest-bridge/build/tools/mailchimp.js +265 -0
  19. package/servers/wp-rest-bridge/build/tools/media.d.ts +2 -2
  20. package/servers/wp-rest-bridge/build/tools/multisite-sites.d.ts +2 -2
  21. package/servers/wp-rest-bridge/build/tools/plugin-repository.d.ts +1 -1
  22. package/servers/wp-rest-bridge/build/tools/search.d.ts +2 -2
  23. package/servers/wp-rest-bridge/build/tools/sendgrid.d.ts +3 -0
  24. package/servers/wp-rest-bridge/build/tools/sendgrid.js +255 -0
  25. package/servers/wp-rest-bridge/build/tools/unified-content.d.ts +8 -8
  26. package/servers/wp-rest-bridge/build/tools/unified-taxonomies.d.ts +4 -4
  27. package/servers/wp-rest-bridge/build/tools/users.d.ts +6 -6
  28. package/servers/wp-rest-bridge/build/tools/wc-coupons.d.ts +1 -1
  29. package/servers/wp-rest-bridge/build/tools/wc-customers.d.ts +3 -3
  30. package/servers/wp-rest-bridge/build/tools/wc-orders.d.ts +4 -4
  31. package/servers/wp-rest-bridge/build/tools/wc-products.d.ts +8 -8
  32. package/servers/wp-rest-bridge/build/tools/wc-webhooks.d.ts +4 -4
  33. package/servers/wp-rest-bridge/build/types.d.ts +122 -0
  34. package/servers/wp-rest-bridge/build/wordpress.d.ts +14 -0
  35. package/servers/wp-rest-bridge/build/wordpress.js +151 -0
  36. package/servers/wp-rest-bridge/package.json +1 -0
  37. package/skills/wordpress-router/references/decision-tree.md +8 -2
  38. package/skills/wp-content/SKILL.md +2 -0
  39. package/skills/wp-content-attribution/SKILL.md +2 -0
  40. package/skills/wp-content-optimization/SKILL.md +172 -0
  41. package/skills/wp-content-optimization/references/content-freshness.md +234 -0
  42. package/skills/wp-content-optimization/references/headline-optimization.md +171 -0
  43. package/skills/wp-content-optimization/references/meta-optimization.md +243 -0
  44. package/skills/wp-content-optimization/references/readability-analysis.md +201 -0
  45. package/skills/wp-content-optimization/references/seo-content-scoring.md +245 -0
  46. package/skills/wp-content-optimization/scripts/content_optimization_inspect.mjs +237 -0
  47. package/skills/wp-content-repurposing/SKILL.md +1 -0
  48. package/skills/wp-monitoring/SKILL.md +1 -0
  49. package/skills/wp-programmatic-seo/SKILL.md +2 -0
  50. package/skills/wp-search-console/SKILL.md +121 -0
  51. package/skills/wp-search-console/references/competitor-gap-analysis.md +226 -0
  52. package/skills/wp-search-console/references/content-seo-feedback.md +181 -0
  53. package/skills/wp-search-console/references/gsc-setup.md +110 -0
  54. package/skills/wp-search-console/references/indexing-management.md +182 -0
  55. package/skills/wp-search-console/references/keyword-tracking.md +181 -0
  56. package/skills/wp-search-console/scripts/search_console_inspect.mjs +178 -0
  57. package/skills/wp-social-email/SKILL.md +152 -0
  58. package/skills/wp-social-email/references/audience-segmentation.md +173 -0
  59. package/skills/wp-social-email/references/buffer-social-publishing.md +124 -0
  60. package/skills/wp-social-email/references/content-to-distribution.md +156 -0
  61. package/skills/wp-social-email/references/distribution-analytics.md +208 -0
  62. package/skills/wp-social-email/references/mailchimp-integration.md +145 -0
  63. package/skills/wp-social-email/references/sendgrid-transactional.md +165 -0
  64. package/skills/wp-social-email/scripts/distribution_inspect.mjs +165 -0
  65. package/skills/wp-webhooks/SKILL.md +1 -0
@@ -258,4 +258,126 @@ export interface WPNetworkSite {
258
258
  spam: boolean;
259
259
  deleted: boolean;
260
260
  }
261
+ export interface MCMailchimpAudience {
262
+ id: string;
263
+ name: string;
264
+ member_count: number;
265
+ campaign_defaults: {
266
+ from_name: string;
267
+ from_email: string;
268
+ subject: string;
269
+ };
270
+ stats: {
271
+ member_count: number;
272
+ unsubscribe_count: number;
273
+ open_rate: number;
274
+ click_rate: number;
275
+ };
276
+ date_created: string;
277
+ }
278
+ export interface MCCampaign {
279
+ id: string;
280
+ type: string;
281
+ status: string;
282
+ emails_sent: number;
283
+ send_time: string;
284
+ settings: {
285
+ subject_line: string;
286
+ from_name: string;
287
+ reply_to: string;
288
+ };
289
+ report_summary?: {
290
+ opens: number;
291
+ unique_opens: number;
292
+ clicks: number;
293
+ subscriber_clicks: number;
294
+ };
295
+ }
296
+ export interface MCCampaignReport {
297
+ id: string;
298
+ campaign_title: string;
299
+ emails_sent: number;
300
+ opens: {
301
+ opens_total: number;
302
+ unique_opens: number;
303
+ open_rate: number;
304
+ };
305
+ clicks: {
306
+ clicks_total: number;
307
+ unique_clicks: number;
308
+ click_rate: number;
309
+ };
310
+ unsubscribed: number;
311
+ bounces: {
312
+ hard_bounces: number;
313
+ soft_bounces: number;
314
+ };
315
+ }
316
+ export interface BufProfile {
317
+ id: string;
318
+ service: string;
319
+ formatted_username: string;
320
+ avatar: string;
321
+ counts: {
322
+ sent: number;
323
+ pending: number;
324
+ };
325
+ }
326
+ export interface BufUpdate {
327
+ id: string;
328
+ text: string;
329
+ profile_id: string;
330
+ status: string;
331
+ sent_at?: number;
332
+ due_at?: number;
333
+ statistics?: {
334
+ clicks: number;
335
+ reach: number;
336
+ impressions: number;
337
+ };
338
+ }
339
+ export interface SGEmailRequest {
340
+ personalizations: {
341
+ to: {
342
+ email: string;
343
+ name?: string;
344
+ }[];
345
+ subject?: string;
346
+ }[];
347
+ from: {
348
+ email: string;
349
+ name?: string;
350
+ };
351
+ subject: string;
352
+ content: {
353
+ type: string;
354
+ value: string;
355
+ }[];
356
+ template_id?: string;
357
+ }
358
+ export interface SGTemplate {
359
+ id: string;
360
+ name: string;
361
+ generation: string;
362
+ updated_at: string;
363
+ versions: {
364
+ id: string;
365
+ name: string;
366
+ active: number;
367
+ subject: string;
368
+ }[];
369
+ }
370
+ export interface SGStats {
371
+ date: string;
372
+ stats: {
373
+ metrics: {
374
+ requests: number;
375
+ delivered: number;
376
+ opens: number;
377
+ clicks: number;
378
+ bounces: number;
379
+ spam_reports: number;
380
+ };
381
+ }[];
382
+ }
261
383
  export {};
@@ -11,6 +11,11 @@ interface SiteConfig {
11
11
  ssh_key?: string;
12
12
  ssh_port?: number;
13
13
  is_multisite?: boolean;
14
+ mailchimp_api_key?: string;
15
+ buffer_access_token?: string;
16
+ sendgrid_api_key?: string;
17
+ gsc_service_account_key?: string;
18
+ gsc_site_url?: string;
14
19
  }
15
20
  /**
16
21
  * Parse WP_SITES_CONFIG JSON and initialize all site clients
@@ -69,6 +74,15 @@ export declare function hasWooCommerce(siteId?: string): boolean;
69
74
  * Uses Consumer Key/Secret auth and wc/v3 namespace by default.
70
75
  */
71
76
  export declare function makeWooCommerceRequest(method: string, endpoint: string, data?: any, options?: WordPressRequestOptions): Promise<any>;
77
+ export declare function hasMailchimp(siteId?: string): boolean;
78
+ export declare function makeMailchimpRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
79
+ export declare function hasBuffer(siteId?: string): boolean;
80
+ export declare function makeBufferRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
81
+ export declare function hasSendGrid(siteId?: string): boolean;
82
+ export declare function makeSendGridRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
83
+ export declare function hasGSC(siteId?: string): boolean;
84
+ export declare function getGSCSiteUrl(siteId?: string): string;
85
+ export declare function getGSCAuth(siteId?: string): Promise<any>;
72
86
  /**
73
87
  * Search the WordPress.org Plugin Repository
74
88
  */
@@ -1,5 +1,7 @@
1
1
  // src/wordpress.ts - Multi-site WordPress REST API client
2
2
  import axios from 'axios';
3
+ import { google } from 'googleapis';
4
+ import { readFileSync } from 'fs';
3
5
  // ── Concurrency Limiter ──────────────────────────────────────────────
4
6
  // Simple FIFO semaphore to cap concurrent requests per site
5
7
  class ConcurrencyLimiter {
@@ -32,6 +34,9 @@ class ConcurrencyLimiter {
32
34
  const siteClients = new Map();
33
35
  const siteLimiters = new Map();
34
36
  const wcSiteClients = new Map();
37
+ const mcSiteClients = new Map();
38
+ const bufSiteClients = new Map();
39
+ const sgSiteClients = new Map();
35
40
  let activeSiteId = '';
36
41
  const parsedSiteConfigs = new Map();
37
42
  const MAX_CONCURRENT_PER_SITE = 5;
@@ -84,6 +89,18 @@ export async function initWordPress() {
84
89
  await initWcClient(site.id, site.url, site.wc_consumer_key, site.wc_consumer_secret);
85
90
  logToStderr(`Initialized WooCommerce for site: ${site.id}`);
86
91
  }
92
+ if (site.mailchimp_api_key) {
93
+ await initMailchimpClient(site.id, site.mailchimp_api_key);
94
+ logToStderr(`Initialized Mailchimp for site: ${site.id}`);
95
+ }
96
+ if (site.buffer_access_token) {
97
+ await initBufferClient(site.id, site.buffer_access_token);
98
+ logToStderr(`Initialized Buffer for site: ${site.id}`);
99
+ }
100
+ if (site.sendgrid_api_key) {
101
+ await initSendGridClient(site.id, site.sendgrid_api_key);
102
+ logToStderr(`Initialized SendGrid for site: ${site.id}`);
103
+ }
87
104
  }
88
105
  activeSiteId = defaultSite || sites[0].id;
89
106
  logToStderr(`Active site: ${activeSiteId}`);
@@ -152,6 +169,40 @@ async function initWcClient(id, url, consumerKey, consumerSecret) {
152
169
  }
153
170
  wcSiteClients.set(id, client);
154
171
  }
172
+ async function initMailchimpClient(id, apiKey) {
173
+ const dc = apiKey.split('-').pop() || 'us21';
174
+ const client = axios.create({
175
+ baseURL: `https://${dc}.api.mailchimp.com/3.0/`,
176
+ headers: {
177
+ 'Content-Type': 'application/json',
178
+ 'Authorization': `Basic ${Buffer.from(`anystring:${apiKey}`).toString('base64')}`,
179
+ },
180
+ timeout: DEFAULT_TIMEOUT_MS,
181
+ });
182
+ mcSiteClients.set(id, client);
183
+ }
184
+ async function initBufferClient(id, accessToken) {
185
+ const client = axios.create({
186
+ baseURL: 'https://api.bufferapp.com/1/',
187
+ headers: {
188
+ 'Content-Type': 'application/json',
189
+ },
190
+ params: { access_token: accessToken },
191
+ timeout: DEFAULT_TIMEOUT_MS,
192
+ });
193
+ bufSiteClients.set(id, client);
194
+ }
195
+ async function initSendGridClient(id, apiKey) {
196
+ const client = axios.create({
197
+ baseURL: 'https://api.sendgrid.com/v3/',
198
+ headers: {
199
+ 'Content-Type': 'application/json',
200
+ 'Authorization': `Bearer ${apiKey}`,
201
+ },
202
+ timeout: DEFAULT_TIMEOUT_MS,
203
+ });
204
+ sgSiteClients.set(id, client);
205
+ }
155
206
  // ── Site Management ──────────────────────────────────────────────────
156
207
  /**
157
208
  * Get the active site's client, or a specific site's client
@@ -357,6 +408,106 @@ export async function makeWooCommerceRequest(method, endpoint, data, options) {
357
408
  limiter.release();
358
409
  }
359
410
  }
411
+ // ── Mailchimp Request Interface ──────────────────────────────────
412
+ export function hasMailchimp(siteId) {
413
+ const id = siteId || activeSiteId;
414
+ return mcSiteClients.has(id);
415
+ }
416
+ export async function makeMailchimpRequest(method, endpoint, data, siteId) {
417
+ const id = siteId || activeSiteId;
418
+ const client = mcSiteClients.get(id);
419
+ if (!client) {
420
+ throw new Error(`Mailchimp not configured for site "${id}". Add mailchimp_api_key to WP_SITES_CONFIG.`);
421
+ }
422
+ const limiter = getLimiter(id);
423
+ await limiter.acquire();
424
+ try {
425
+ const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
426
+ return response.data;
427
+ }
428
+ finally {
429
+ limiter.release();
430
+ }
431
+ }
432
+ // ── Buffer Request Interface ─────────────────────────────────────
433
+ export function hasBuffer(siteId) {
434
+ const id = siteId || activeSiteId;
435
+ return bufSiteClients.has(id);
436
+ }
437
+ export async function makeBufferRequest(method, endpoint, data, siteId) {
438
+ const id = siteId || activeSiteId;
439
+ const client = bufSiteClients.get(id);
440
+ if (!client) {
441
+ throw new Error(`Buffer not configured for site "${id}". Add buffer_access_token to WP_SITES_CONFIG.`);
442
+ }
443
+ const limiter = getLimiter(id);
444
+ await limiter.acquire();
445
+ try {
446
+ const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
447
+ return response.data;
448
+ }
449
+ finally {
450
+ limiter.release();
451
+ }
452
+ }
453
+ // ── SendGrid Request Interface ───────────────────────────────────
454
+ export function hasSendGrid(siteId) {
455
+ const id = siteId || activeSiteId;
456
+ return sgSiteClients.has(id);
457
+ }
458
+ export async function makeSendGridRequest(method, endpoint, data, siteId) {
459
+ const id = siteId || activeSiteId;
460
+ const client = sgSiteClients.get(id);
461
+ if (!client) {
462
+ throw new Error(`SendGrid not configured for site "${id}". Add sendgrid_api_key to WP_SITES_CONFIG.`);
463
+ }
464
+ const limiter = getLimiter(id);
465
+ await limiter.acquire();
466
+ try {
467
+ const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
468
+ return response.data;
469
+ }
470
+ finally {
471
+ limiter.release();
472
+ }
473
+ }
474
+ // ── Google Search Console Interface ─────────────────────────────
475
+ const gscAuthClients = new Map();
476
+ export function hasGSC(siteId) {
477
+ const id = siteId || activeSiteId;
478
+ const sites = JSON.parse(process.env.WP_SITES_CONFIG || '[]');
479
+ const site = sites.find((s) => s.id === id);
480
+ return !!(site?.gsc_service_account_key && site?.gsc_site_url);
481
+ }
482
+ export function getGSCSiteUrl(siteId) {
483
+ const id = siteId || activeSiteId;
484
+ const sites = JSON.parse(process.env.WP_SITES_CONFIG || '[]');
485
+ const site = sites.find((s) => s.id === id);
486
+ if (!site?.gsc_site_url) {
487
+ throw new Error(`GSC site URL not configured for site "${id}". Add gsc_site_url to WP_SITES_CONFIG.`);
488
+ }
489
+ return site.gsc_site_url;
490
+ }
491
+ export async function getGSCAuth(siteId) {
492
+ const id = siteId || activeSiteId;
493
+ // Return cached client if available
494
+ if (gscAuthClients.has(id)) {
495
+ return gscAuthClients.get(id);
496
+ }
497
+ const sites = JSON.parse(process.env.WP_SITES_CONFIG || '[]');
498
+ const site = sites.find((s) => s.id === id);
499
+ if (!site?.gsc_service_account_key) {
500
+ throw new Error(`GSC not configured for site "${id}". Add gsc_service_account_key (path to JSON key file) to WP_SITES_CONFIG.`);
501
+ }
502
+ const keyContent = JSON.parse(readFileSync(site.gsc_service_account_key, 'utf-8'));
503
+ const auth = new google.auth.GoogleAuth({
504
+ credentials: keyContent,
505
+ scopes: ['https://www.googleapis.com/auth/webmasters'],
506
+ });
507
+ const authClient = await auth.getClient();
508
+ gscAuthClients.set(id, authClient);
509
+ return authClient;
510
+ }
360
511
  // ── Plugin Repository (External API) ────────────────────────────────
361
512
  /**
362
513
  * Search the WordPress.org Plugin Repository
@@ -17,6 +17,7 @@
17
17
  "@modelcontextprotocol/sdk": "^1.27.1",
18
18
  "axios": "^1.7.9",
19
19
  "form-data": "^4.0.1",
20
+ "googleapis": "^171.4.0",
20
21
  "zod": "^3.24.2"
21
22
  },
22
23
  "devDependencies": {
@@ -1,4 +1,4 @@
1
- # Router decision tree (v10 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network)
1
+ # Router decision tree (v13 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network + social/email distribution + search console + content optimization)
2
2
 
3
3
  This routing guide covers WordPress **development**, **local environment**, and **operations** workflows.
4
4
 
@@ -14,7 +14,7 @@ Keywords that indicate **local environment**:
14
14
  local site, Studio, LocalWP, Local by Flywheel, wp-env, local WordPress, start site, stop site, create local site, local development, symlink plugin, local database, switch PHP version, localhost, local preview, detect environment, WASM, SQLite local
15
15
 
16
16
  Keywords that indicate **operations**:
17
- deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content
17
+ deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content, social publish, schedule post, Buffer, email campaign, Mailchimp, SendGrid, transactional email, content distribution, newsletter send, Google Search Console, GSC, keyword tracking, keyword rankings, search analytics, indexing status, URL inspection, sitemap submit, search performance, SERP data, optimize content, headline scoring, readability analysis, SEO score, content scoring, meta optimization, content freshness, content triage, bulk optimize, Flesch-Kincaid, keyword density
18
18
 
19
19
  Keywords that indicate **development**:
20
20
  create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold, i18n, translation, accessibility, a11y, headless, decoupled, WPGraphQL, CI, CD, pipeline, GitHub Actions, GitLab CI, deploy automatico, workflow, quality gate
@@ -104,6 +104,12 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
104
104
  → `wp-content-attribution` skill + `wp-ecommerce-manager` agent
105
105
  - **Multi-language / multilingual / hreflang / international SEO / language sites / translate network**
106
106
  → `wp-multilang-network` skill + `wp-site-manager` agent
107
+ - **Social/email distribution / publish to social / schedule post / email campaign / Mailchimp / Buffer / SendGrid / newsletter / transactional email / content distribution**
108
+ → `wp-social-email` skill + `wp-distribution-manager` agent
109
+ - **Google Search Console / keyword tracking / indexing status / sitemap submit / search performance / GSC / SERP data**
110
+ → `wp-search-console` skill + `wp-content-strategist` agent
111
+ - **Content optimization / headline scoring / readability / SEO score / meta optimization / content freshness / content triage / optimize posts / Flesch-Kincaid / keyword density**
112
+ → `wp-content-optimization` skill + `wp-content-strategist` agent
107
113
 
108
114
  ## Step 2c: route by local environment intent (keywords)
109
115
 
@@ -105,3 +105,5 @@ Tool: assign_terms_to_content — assign terms to content
105
105
  ### Related Skills
106
106
  - **`wp-content-repurposing`** — transform existing content for social media, email, and multi-channel distribution
107
107
  - **`wp-content-attribution`** — measure which content drives WooCommerce sales (UTM tracking, attribution models, ROI)
108
+ - **wp-social-email** — distribute content to social media and email after creation
109
+ - **wp-content-optimization** — optimize existing content: headlines, readability, SEO scoring, meta descriptions, freshness audit
@@ -95,3 +95,5 @@ The script checks WooCommerce presence, analytics plugins, UTM tracking setup, c
95
95
  - `wp-content` — content management and editorial workflows
96
96
  - `wp-monitoring` — ongoing site performance and health tracking
97
97
  - `wp-content-repurposing` — transform high-ROI content into multi-channel formats
98
+ - `wp-search-console` — correlate GSC keyword data with WooCommerce conversions for content-commerce attribution
99
+ - `wp-content-optimization` — prioritize optimization of high-revenue content using attribution data
@@ -0,0 +1,172 @@
1
+ ---
2
+ name: wp-content-optimization
3
+ description: This skill should be used when the user asks to "optimize content",
4
+ "improve headlines", "readability analysis", "SEO score", "content scoring",
5
+ "meta description optimization", "content freshness", "content audit",
6
+ "content triage", "bulk content optimization", "headline score",
7
+ "Flesch-Kincaid", "keyword density", or mentions improving existing
8
+ WordPress content quality and performance.
9
+ version: 1.0.0
10
+ ---
11
+
12
+ # WordPress Content Optimization Skill
13
+
14
+ ## Overview
15
+
16
+ AI-driven content optimization using Claude's linguistic analysis combined with GSC data (v2.5.0) and WooCommerce attribution data. No external optimization APIs are needed — this skill uses existing WP REST Bridge tools plus Claude's built-in analysis capabilities to perform headline scoring, readability analysis, SEO density checks, meta optimization, content freshness audits, and bulk content triage.
17
+
18
+ ## Philosophy
19
+
20
+ This is Claude-native. No external optimization APIs like Clearscope, SurferSEO, or MarketMuse are required. Claude itself performs headline analysis, readability scoring, SEO density checks, and content classification by leveraging its linguistic capabilities directly on content fetched through the WP REST Bridge.
21
+
22
+ ## When to Use
23
+
24
+ - User wants to improve existing content quality
25
+ - User needs headline/title optimization with scoring
26
+ - User asks about readability (Flesch-Kincaid, sentence length)
27
+ - User wants SEO content scoring (keyword density, H-tag coverage)
28
+ - User needs meta description optimization based on CTR data
29
+ - User wants content freshness audit (find stale content)
30
+ - User needs bulk content triage (quick wins vs rewrite vs archive)
31
+
32
+ ## Decision Tree
33
+
34
+ 1. **What type of optimization?**
35
+ - "optimize headline" / "title score" / "headline analysis" → Headline Analysis (Section 1)
36
+ - "readability" / "Flesch-Kincaid" / "sentence length" → Readability Analysis (Section 2)
37
+ - "SEO score" / "keyword density" / "content scoring" → SEO Content Scoring (Section 3)
38
+ - "meta description" / "title tag" / "CTR optimization" → Meta Description Optimization (Section 4)
39
+ - "content freshness" / "stale content" / "outdated posts" → Content Freshness Audit (Section 5)
40
+ - "content triage" / "bulk optimize" / "content audit" → Bulk Content Triage (Section 6 — combines all above)
41
+
42
+ 2. **Run detection first:**
43
+ ```bash
44
+ node skills/wp-content-optimization/scripts/content_optimization_inspect.mjs [--cwd=/path/to/project]
45
+ ```
46
+ This identifies available content, GSC integration status, and WooCommerce data availability.
47
+
48
+ ## Procedures Overview
49
+
50
+ | # | Procedure | Input | Output |
51
+ |---|-----------|-------|--------|
52
+ | 1 | Headline Analysis | Title + target keyword | Score 1-10, 3 optimized alternatives |
53
+ | 2 | Readability Analysis | Body content | Flesch-Kincaid score, long sentences, suggestions |
54
+ | 3 | SEO Content Scoring | Body + keyword + GSC data | Keyword density, H2/H3 coverage, internal linking gaps |
55
+ | 4 | Meta Description Optimization | Current meta + GSC CTR data | Optimized meta for CTR, A/B variant |
56
+ | 5 | Content Freshness Audit | Content list + publish date | Stale content identified, update priorities |
57
+ | 6 | Bulk Content Triage | N contents + GSC data | Classified: quick wins, needs rewrite, archive |
58
+
59
+ ## Bulk Content Triage Classification
60
+
61
+ | Category | Criteria | Action |
62
+ |----------|----------|--------|
63
+ | Quick Wins | High traffic + low CTR, weak headline | Optimize title/meta |
64
+ | Needs Rewrite | >12 months, low readability, keyword off-target | Rewrite content |
65
+ | Performing | High traffic + high CTR | Maintain, refresh date |
66
+ | Archive | Zero traffic >6 months, no keywords | 301 redirect or noindex |
67
+
68
+ ## Sections
69
+
70
+ ### Section 1: Headline Analysis
71
+ See `references/headline-optimization.md`
72
+ - Headline scoring criteria (1-10 scale based on keyword placement, power words, length, clarity)
73
+ - Power word categories (emotional, urgency, curiosity, value)
74
+ - Headline formulas (How-to, List, Question, Comparison)
75
+ - Target keyword placement in headlines
76
+ - A/B title generation workflow
77
+ - Example: fetch via `list_content` → Claude analyzes → generate alternatives → `update_content`
78
+
79
+ ### Section 2: Readability Analysis
80
+ See `references/readability-analysis.md`
81
+ - Flesch-Kincaid scoring (target: 60-70 for general audience)
82
+ - Sentence length analysis (target: <20 words average)
83
+ - Passive voice detection and reduction
84
+ - Paragraph length guidelines
85
+ - Jargon and complexity detection
86
+ - Workflow: fetch content → analyze text → suggest improvements → update
87
+
88
+ ### Section 3: SEO Content Scoring
89
+ See `references/seo-content-scoring.md`
90
+ - Keyword density check (target: 1-2% primary keyword)
91
+ - H2/H3 hierarchy coverage (are subheadings using secondary keywords?)
92
+ - Internal linking analysis (minimum 2-3 internal links per post)
93
+ - External linking (1-2 authoritative sources)
94
+ - Image alt text coverage
95
+ - Combining with `gsc_search_analytics` for keyword data
96
+
97
+ ### Section 4: Meta Description Optimization
98
+ See `references/meta-optimization.md`
99
+ - Title tag best practices (under 60 chars, keyword first)
100
+ - Meta description guidelines (under 160 chars, compelling CTA, keyword inclusion)
101
+ - Using GSC CTR data to identify low-CTR pages for optimization
102
+ - A/B variant generation for testing
103
+ - Rich snippet optimization hints
104
+
105
+ ### Section 5: Content Freshness Audit
106
+ See `references/content-freshness.md`
107
+ - Content decay patterns (traffic drop over time)
108
+ - Freshness signals (published date, modified date, data accuracy)
109
+ - Refresh strategies: date update, data refresh, section expansion, republish
110
+ - Evergreen vs temporal content classification
111
+ - Workflow: `list_content` by date → analyze age → check GSC traffic trends → prioritize
112
+
113
+ ### Section 6: Bulk Content Triage
114
+ Combines all sections above into a single audit workflow:
115
+ 1. Fetch all published content via `list_content`
116
+ 2. Pull GSC performance data via `gsc_page_performance` and `gsc_top_queries`
117
+ 3. Run headline analysis (Section 1) on each title
118
+ 4. Run readability analysis (Section 2) on each body
119
+ 5. Run SEO content scoring (Section 3) on each post
120
+ 6. Cross-reference with GSC CTR data for meta optimization (Section 4)
121
+ 7. Check publish dates for freshness audit (Section 5)
122
+ 8. Classify each content piece into the triage categories above
123
+ 9. Generate prioritized action list
124
+
125
+ ## Reference Files
126
+
127
+ | File | Content |
128
+ |------|---------|
129
+ | `references/headline-optimization.md` | Headline formulas, power words, scoring criteria |
130
+ | `references/readability-analysis.md` | Flesch-Kincaid, sentence length, passive voice, jargon |
131
+ | `references/seo-content-scoring.md` | Keyword density, H-tag hierarchy, internal link analysis |
132
+ | `references/meta-optimization.md` | Title tag + meta description best practices, CTR optimization |
133
+ | `references/content-freshness.md` | Content decay, refresh strategies, evergreen vs temporal |
134
+
135
+ ## MCP Tools Used
136
+
137
+ These are existing tools used by the optimization procedures (no new tools introduced):
138
+
139
+ ### WP REST Bridge
140
+
141
+ | Tool | Usage |
142
+ |------|-------|
143
+ | `list_content` | Fetch published content for analysis |
144
+ | `get_content` | Get full content body for individual post analysis |
145
+ | `update_content` | Apply optimized titles, meta descriptions, content updates |
146
+
147
+ ### Google Search Console (if available)
148
+
149
+ | Tool | Usage |
150
+ |------|-------|
151
+ | `gsc_page_performance` | Page-level traffic data for triage classification |
152
+ | `gsc_top_queries` | Top queries for keyword density validation |
153
+ | `gsc_search_analytics` | Detailed search metrics for CTR-based meta optimization |
154
+
155
+ ### WooCommerce (if available)
156
+
157
+ | Tool | Usage |
158
+ |------|-------|
159
+ | `wc_get_orders` | Attribution data linking content to conversions |
160
+ | `wc_list_products` | Product pages for content-commerce optimization |
161
+
162
+ ## Recommended Agent
163
+
164
+ Use the **`wp-content-strategist`** agent for content optimization workflows that combine Claude's linguistic analysis with search performance data and WordPress content management.
165
+
166
+ ## Related Skills
167
+
168
+ - **`wp-content`** — create and manage WordPress content
169
+ - **`wp-search-console`** — search performance data for optimization decisions
170
+ - **`wp-content-attribution`** — track content sources and attribute traffic
171
+ - **`wp-programmatic-seo`** — generate SEO-optimized content at scale
172
+ - **`wp-social-email`** — distribute optimized content across channels