claude-plugin-wordpress-manager 2.9.1 → 2.12.0

package/skills/wp-structured-data/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: wp-structured-data
+description: This skill should be used when the user asks about "structured data",
+  "Schema.org", "JSON-LD", "rich snippets", "schema markup", "dati strutturati",
+  "rich results", "Google rich cards", "schema validation", "breadcrumb schema",
+  "FAQ schema", "product schema", "article schema", or mentions adding/validating
+  Schema.org markup on WordPress content.
+version: 1.0.0
+---
+
+# WordPress Structured Data Skill
+
+## Overview
+
+Structured data (Schema.org markup in JSON-LD format) helps search engines understand page content and enables rich results (FAQ accordions, product stars, recipe cards, event listings, etc.). This skill manages the full lifecycle: validate existing markup, inject new schemas, and audit site-wide coverage.
+
+## When to Use
+
+- User wants to add structured data to posts or pages
+- User asks about rich snippets or Schema.org
+- User needs to validate existing JSON-LD markup
+- User wants to audit structured data coverage across the site
+- User mentions FAQ schema, product schema, article schema, etc.
+
+## Decision Tree
+
+1. **What operation?**
+   - "validate" / "check" / "test" / "audit" → Validation (Section 1)
+   - "add" / "inject" / "create" / "set up" → Injection (Section 2)
+   - "list" / "audit" / "scan" / "coverage" → Site Audit (Section 3)
+   - "types" / "which schema" / "what schema" → Schema Types Reference (Section 4)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-structured-data/scripts/schema_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This checks for existing schema plugins (Yoast, Rank Math, Schema Pro) and JSON-LD presence.
+
+## Sections
+
+### Section 1: Validation
+See `references/validation-guide.md`
+- Validate live URLs: `sd_validate` with `url` parameter
+- Validate raw markup: `sd_validate` with `markup` parameter
+- Interpret results: check @context, @type, required properties
+- Common issues: missing @context, invalid JSON, wrong @type
+
+### Section 2: Injection
+See `references/injection-patterns.md`
+- Article schema for blog posts
+- Product schema for WooCommerce
+- FAQ schema for Q&A content
+- HowTo schema for tutorials
+- Use `sd_inject` with post_id, schema_type, schema_data
+
+### Section 3: Site Audit
+- List all schema types: `sd_list_schemas`
+- Filter by type: `sd_list_schemas` with `schema_type`
+- Identify posts without structured data
+- Coverage report: total posts vs posts with schema
+
+### Section 4: Schema Types
+See `references/schema-types.md`
+- Supported types and their required/recommended properties
+- Mapping WordPress content types to Schema.org types
+- Rich result eligibility per type
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `sd_validate` | Validate JSON-LD from URL or raw markup |
+| `sd_inject` | Inject/update JSON-LD in post meta |
+| `sd_list_schemas` | List Schema.org types across the site |
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/schema-types.md` | Supported Schema.org types with required properties |
+| `references/validation-guide.md` | Validation workflow, common issues, fixes |
+| `references/injection-patterns.md` | Injection patterns per content type |
+
+## Recommended Agent
+
+**`wp-content-strategist`** — coordinates structured data with content creation and SEO optimization.
+
+## Related Skills
+
+- **`wp-content`** — content lifecycle management (source for schema injection)
+- **`wp-content-optimization`** — SEO scoring and meta optimization
+- **`wp-search-console`** — track rich result impressions in Google Search Console
+- **`wp-woocommerce`** — product structured data for e-commerce
+- **`wp-programmatic-seo`** — bulk schema injection for template pages

package/skills/wp-structured-data/references/injection-patterns.md

@@ -0,0 +1,160 @@
+# Injection Patterns
+
+## Pattern 1: Article Schema for Blog Posts
+
+**When:** Any blog post. Most impactful schema type for content sites.
+
+**Steps:**
+1. Fetch post: `wp_get_post(id: POST_ID)`
+2. Extract: title, date, modified date, author, featured image, excerpt
+3. Build schema data
+4. Inject: `sd_inject(post_id, "Article", schema_data)`
+
+**Schema data template:**
+```json
+{
+  "headline": "{post.title.rendered}",
+  "image": "{featured_image_url}",
+  "datePublished": "{post.date}",
+  "dateModified": "{post.modified}",
+  "author": {
+    "@type": "Person",
+    "name": "{author.name}"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "{site_name}",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "{site_logo_url}"
+    }
+  },
+  "description": "{post.excerpt.rendered (stripped HTML)}"
+}
+```
+
+**Note:** If Yoast or Rank Math is active, they already add Article schema. Check with `sd_validate` first.
+
+## Pattern 2: Product Schema for WooCommerce
+
+**When:** WooCommerce product pages.
+
+**Steps:**
+1. Fetch product: `wc_get_product(id: PRODUCT_ID)`
+2. Extract: name, price, stock status, images, description
+3. Build schema with offers
+4. Inject: `sd_inject(post_id, "Product", schema_data)`
+
+**Schema data template:**
+```json
+{
+  "name": "{product.name}",
+  "image": "{product.images[0].src}",
+  "description": "{product.short_description}",
+  "sku": "{product.sku}",
+  "brand": {
+    "@type": "Brand",
+    "name": "{brand_name}"
+  },
+  "offers": {
+    "@type": "Offer",
+    "price": "{product.price}",
+    "priceCurrency": "EUR",
+    "availability": "https://schema.org/{InStock|OutOfStock}",
+    "url": "{product.permalink}"
+  }
+}
+```
+
+## Pattern 3: FAQ Schema from Content
+
+**When:** Posts containing Q&A sections (H3 questions with paragraph answers).
+
+**Steps:**
+1. Fetch post: `wp_get_post(id: POST_ID)`
+2. Parse content HTML: extract Q&A pairs from H3 + following paragraphs
+3. Build FAQPage schema
+4. Inject: `sd_inject(post_id, "FAQPage", schema_data)`
+
+**Schema data template:**
+```json
+{
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "{question_text}",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "{answer_text}"
+      }
+    }
+  ]
+}
+```
+
+**Extraction heuristic:**
+- H3 ending with `?` → Question
+- Following `<p>` blocks until next H3 → Answer
+- Minimum 3 Q&A pairs for meaningful FAQ schema
+
+## Pattern 4: HowTo Schema from Tutorials
+
+**When:** Tutorial or step-by-step posts.
+
+**Steps:**
+1. Fetch post: `wp_get_post(id: POST_ID)`
+2. Parse content: extract steps from H2 sections or ordered lists
+3. Build HowTo schema
+4. Inject: `sd_inject(post_id, "HowTo", schema_data)`
+
+**Schema data template:**
+```json
+{
+  "name": "{post.title.rendered}",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "{step_heading}",
+      "text": "{step_description}"
+    }
+  ],
+  "totalTime": "PT{minutes}M"
+}
+```
+
+**Extraction heuristic:**
+- H2 headings starting with "Step" or numbered → HowToStep
+- Ordered list items (`<ol><li>`) → HowToStep
+- Time references in content → totalTime
+
+## Pattern 5: Bulk Injection
+
+**When:** Adding schema to multiple existing posts at once.
+
+**Steps:**
+1. List posts: `wp_list_posts(per_page: 50)`
+2. Check existing schemas: `sd_list_schemas()`
+3. Identify posts without schema
+4. For each post without schema:
+   a. Determine best schema type from content
+   b. Extract relevant data
+   c. `sd_inject(post_id, schema_type, schema_data)`
+5. Verify: `sd_list_schemas()` to confirm coverage
+
+**Type determination heuristic:**
+| Content Pattern | Schema Type |
+|----------------|-------------|
+| Contains Q&A pairs (H3 + ?) | FAQPage |
+| Contains step-by-step (H2 "Step N" or `<ol>`) | HowTo |
+| Is WooCommerce product | Product |
+| Has event date/time | Event |
+| Default for blog posts | Article |
+
+## Conflict Resolution
+
+When SEO plugins already add schema:
+
+1. **Check first:** `sd_validate(url: PAGE_URL)` to see existing schemas
+2. **Don't duplicate:** If Article schema already exists from Yoast, don't add another
+3. **Supplement:** Add types the plugin doesn't handle (FAQ, HowTo)
+4. **Override:** To replace plugin schema, disable plugin's schema output for that post type and use `sd_inject` instead

package/skills/wp-structured-data/references/schema-types.md

@@ -0,0 +1,127 @@
+# Supported Schema.org Types
+
+## Type Reference
+
+### Article
+**Use for:** Blog posts, news articles, how-to articles
+**Rich result:** Article rich result with headline, image, date, author
+**Required properties:**
+- `headline` — article title (max 110 chars for rich result)
+- `image` — featured image URL (min 696px wide)
+- `datePublished` — ISO 8601 date
+- `author` — `{ "@type": "Person", "name": "Author Name" }`
+
+**Recommended:** `dateModified`, `publisher`, `description`
+
+**WordPress mapping:**
+```json
+{
+  "headline": "post.title.rendered",
+  "image": "featured_media URL",
+  "datePublished": "post.date",
+  "dateModified": "post.modified",
+  "author": { "@type": "Person", "name": "post.author.name" }
+}
+```
+
+### Product
+**Use for:** WooCommerce products, product pages
+**Rich result:** Product snippet with price, availability, rating
+**Required properties:**
+- `name` — product name
+- `image` — product image URL
+- `offers` — `{ "@type": "Offer", "price": "19.99", "priceCurrency": "EUR", "availability": "https://schema.org/InStock" }`
+
+**Recommended:** `description`, `sku`, `brand`, `aggregateRating`, `review`
+
+### FAQ
+**Use for:** FAQ pages, Q&A sections within posts
+**Rich result:** FAQ accordion in search results
+**Required properties:**
+- `mainEntity` — array of Question objects
+
+**Structure:**
+```json
+{
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is cactus water?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Cactus water is a beverage made from Sicilian prickly pear..."
+      }
+    }
+  ]
+}
+```
+
+### HowTo
+**Use for:** Tutorial posts, step-by-step guides
+**Rich result:** How-to rich result with steps
+**Required properties:**
+- `name` — how-to title
+- `step` — array of HowToStep objects
+
+**Structure:**
+```json
+{
+  "@type": "HowTo",
+  "name": "How to Make Cactus Water Smoothie",
+  "step": [
+    { "@type": "HowToStep", "text": "Blend 200ml cactus water with ice" },
+    { "@type": "HowToStep", "text": "Add fresh fruit of your choice" }
+  ]
+}
+```
+
+**Recommended:** `totalTime` (ISO 8601 duration), `estimatedCost`, `image`
+
+### LocalBusiness
+**Use for:** Business location pages, contact pages
+**Rich result:** Knowledge panel with business info
+**Required properties:**
+- `name` — business name
+- `address` — PostalAddress object
+- `telephone` — phone number
+
+**Recommended:** `openingHoursSpecification`, `geo`, `image`, `priceRange`
+
+### Event
+**Use for:** Event listings, webinar pages, course dates
+**Rich result:** Event rich result with date, location, tickets
+**Required properties:**
+- `name` — event name
+- `startDate` — ISO 8601 date
+- `location` — Place or VirtualLocation object
+
+**Recommended:** `endDate`, `image`, `description`, `offers`, `performer`
+
+### Organization
+**Use for:** About pages, company profiles
+**Rich result:** Knowledge panel
+**Required properties:**
+- `name` — organization name
+- `url` — website URL
+
+**Recommended:** `logo`, `contactPoint`, `sameAs` (social profile URLs)
+
+### BreadcrumbList
+**Use for:** Navigation breadcrumbs on any page
+**Rich result:** Breadcrumb trail in search results
+**Required properties:**
+- `itemListElement` — array of ListItem objects with position, name, item URL
+
+## Content Type → Schema Type Mapping
+
+| WordPress Content | Recommended Schema | Notes |
+|-------------------|-------------------|-------|
+| Blog post | Article | Auto-map title, date, author |
+| Product (WooCommerce) | Product | Map price, stock, reviews |
+| FAQ page | FAQPage | Extract Q&A pairs from content |
+| Tutorial post | HowTo | Extract steps from H2/H3 or ordered lists |
+| About page | Organization | Company info, social links |
+| Contact page | LocalBusiness | Address, phone, hours |
+| Event post | Event | Date, location, ticket info |
+| Any page with breadcrumbs | BreadcrumbList | Navigation hierarchy |

package/skills/wp-structured-data/references/validation-guide.md

@@ -0,0 +1,89 @@
+# Validation Guide
+
+## Validation Workflow
+
+### Step 1: Check Existing Markup
+
+Use `sd_validate` with `url` to scan a live page:
+
+```
+sd_validate(url: "https://example.com/blog-post")
+```
+
+**Result interpretation:**
+- `valid: true` — JSON-LD is well-formed with @context and @type
+- `valid: false` — issues found (listed in `issues` array)
+- `schemas_found: N` — number of JSON-LD blocks on the page
+
+### Step 2: Validate Before Injection
+
+Before using `sd_inject`, validate markup inline:
+
+```
+sd_validate(markup: '{"@context":"https://schema.org","@type":"Article","headline":"Test"}')
+```
+
+### Step 3: Post-Injection Verification
+
+After `sd_inject`, verify by fetching the page and validating:
+
+```
+sd_validate(url: "https://example.com/blog-post")
+```
+
+## Common Issues and Fixes
+
+### Missing @context
+
+**Issue:** `Missing or invalid @context (should include schema.org)`
+**Fix:** `sd_inject` automatically adds `@context: "https://schema.org"` — this issue only appears on existing markup from other sources.
+
+### Missing @type
+
+**Issue:** `Missing @type`
+**Fix:** Every schema must have a @type. When using `sd_inject`, the `schema_type` parameter sets this automatically.
+
+### Invalid JSON
+
+**Issue:** `Invalid JSON-LD on page`
+**Cause:** Malformed JSON in the `<script type="application/ld+json">` block.
+**Fix:** Check for trailing commas, unescaped quotes, or broken HTML in the JSON-LD block.
+
+### Multiple Schemas Conflict
+
+**Issue:** SEO plugin (Yoast/Rank Math) adds its own schema, plus custom schema via `sd_inject`
+**Fix:** Check with `sd_validate` first. If plugin already covers the type, don't duplicate. Use `sd_inject` for types the plugin doesn't handle (e.g., FAQ, HowTo).
+
+### Required Properties Missing
+
+Google requires specific properties per type. See `schema-types.md` for the full list. Common missing properties:
+
+| Type | Often Missing | Impact |
+|------|--------------|--------|
+| Article | `image` | No rich result without image |
+| Product | `offers` | No price shown in search |
+| FAQ | `acceptedAnswer` | Invalid FAQ schema |
+| Event | `startDate` | Invalid event schema |
+
+## Google Rich Results Eligibility
+
+Not all Schema.org types generate rich results. Eligible types:
+
+| Type | Rich Result |
+|------|-------------|
+| Article | Article card with image, date |
+| Product | Price, availability, rating stars |
+| FAQPage | Expandable FAQ accordion |
+| HowTo | Step-by-step instructions |
+| Event | Event card with date, location |
+| LocalBusiness | Knowledge panel |
+| BreadcrumbList | Breadcrumb trail |
+| Recipe | Recipe card with image, time, calories |
+| VideoObject | Video thumbnail in search |
+
+## External Validation
+
+For definitive testing beyond `sd_validate`:
+- **Google Rich Results Test**: https://search.google.com/test/rich-results
+- **Schema.org Validator**: https://validator.schema.org/
+- **Google Search Console**: Rich results report (requires GSC access via `gsc_*` tools)

package/skills/wp-structured-data/scripts/schema_inspect.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * schema_inspect.mjs — Detects structured data plugins and JSON-LD presence.
+ *
+ * Usage:
+ *   node skills/wp-structured-data/scripts/schema_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Checks:
+ *   1. Yoast SEO (adds Article/Organization/BreadcrumbList schemas)
+ *   2. Rank Math SEO (adds Article/Product/FAQ/HowTo schemas)
+ *   3. Schema Pro or WP Schema plugins
+ *   4. WP_SITES_CONFIG environment for REST API access
+ *   5. Theme-level JSON-LD output
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+const args = process.argv.slice(2);
+const cwdFlag = args.find(a => a.startsWith('--cwd='));
+const cwd = cwdFlag ? resolve(cwdFlag.split('=')[1]) : process.cwd();
+
+const result = {
+  structured_data: {
+    detected: false,
+    plugins: [],
+    has_rest_access: false,
+    details: {},
+  },
+};
+
+// Check for SEO/schema plugins in wp-content/plugins
+const pluginsDir = join(cwd, 'wp-content', 'plugins');
+const schemaPlugins = [
+  { dir: 'wordpress-seo', name: 'Yoast SEO', schemas: ['Article', 'Organization', 'BreadcrumbList', 'WebSite', 'WebPage'] },
+  { dir: 'seo-by-rank-math', name: 'Rank Math', schemas: ['Article', 'Product', 'FAQ', 'HowTo', 'LocalBusiness', 'Event'] },
+  { dir: 'schema-pro', name: 'Schema Pro', schemas: ['Article', 'Product', 'FAQ', 'HowTo', 'LocalBusiness', 'Event', 'Recipe'] },
+  { dir: 'wp-schema-pro', name: 'WP Schema Pro', schemas: ['Article', 'Product', 'FAQ'] },
+  { dir: 'schema', name: 'Schema (Starter)', schemas: ['Article', 'Organization'] },
+  { dir: 'schema-and-structured-data-for-wp', name: 'Schema & Structured Data for WP', schemas: ['Article', 'Product', 'FAQ', 'Event', 'Recipe'] },
+];
+
+if (existsSync(pluginsDir)) {
+  for (const plugin of schemaPlugins) {
+    if (existsSync(join(pluginsDir, plugin.dir))) {
+      result.structured_data.detected = true;
+      result.structured_data.plugins.push({
+        name: plugin.name,
+        directory: plugin.dir,
+        auto_schemas: plugin.schemas,
+      });
+    }
+  }
+}
+
+// Check for WP REST API access (needed for sd_inject and sd_list_schemas)
+const sitesConfig = process.env.WP_SITES_CONFIG;
+if (sitesConfig) {
+  try {
+    const config = JSON.parse(sitesConfig);
+    const sites = Array.isArray(config) ? config : [config];
+    result.structured_data.has_rest_access = sites.length > 0;
+    result.structured_data.details.sites_count = sites.length;
+  } catch {
+    result.structured_data.details.config_error = 'Invalid WP_SITES_CONFIG JSON';
+  }
+}
+
+// Check for theme-level JSON-LD in functions.php
+const functionsPhp = join(cwd, 'functions.php');
+const themeDir = join(cwd, 'wp-content', 'themes');
+let hasThemeSchema = false;
+if (existsSync(functionsPhp)) {
+  const content = readFileSync(functionsPhp, 'utf8');
+  if (content.includes('application/ld+json') || content.includes('schema.org')) {
+    hasThemeSchema = true;
+  }
+}
+result.structured_data.details.theme_schema = hasThemeSchema;
+
+// Summary
+if (result.structured_data.plugins.length > 0) {
+  result.structured_data.details.note = 'Schema plugins detected. sd_inject will store in post meta alongside plugin schemas. Verify no conflicts.';
+} else {
+  result.structured_data.details.note = 'No schema plugins detected. sd_inject can manage all structured data via post meta.';
+}
+
+console.log(JSON.stringify(result, null, 2));

package/skills/wp-twitter/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wp-twitter
+description: This skill should be used when the user asks to "publish a tweet",
+  "create a thread", "Twitter analytics", "tweet a post", "pubblica tweet",
+  "Twitter/X publishing", or mentions Twitter/X posting, threads, and analytics
+  for WordPress content.
+version: 1.0.0
+tags: [twitter, x, social-media, tweets, threads, direct-social]
+---
+
+# WordPress Twitter/X Integration Skill
+
+## Overview
+
+Direct Twitter/X publishing connects WordPress content to Twitter via the API v2. This enables quick content distribution: single tweets for announcements, threads for long-form storytelling, and metrics for engagement tracking. The WP REST Bridge provides 5 MCP tools with the `tw_*` namespace.
+
+## When to Use
+
+- User wants to tweet about a WordPress blog post
+- User needs to create a Twitter thread from a blog post
+- User asks about tweet metrics (impressions, likes, retweets)
+- User wants to manage tweets (publish, list, delete)
+- User needs social media distribution via Twitter/X
+
+## Decision Tree
+
+1. **What Twitter action?**
+   - "tweet" / "publish tweet" / "post to Twitter" → Single tweet (Section 1)
+   - "thread" / "tweetstorm" / "multi-tweet" → Thread creation (Section 2)
+   - "analytics" / "metrics" / "impressions" → Metrics (Section 3)
+   - "delete" / "remove tweet" → Delete tweet (Section 4)
+   - "setup" / "configure" / "connect Twitter" → Setup guide (Section 5)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-twitter/scripts/twitter_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured Twitter credentials in WP_SITES_CONFIG.
+
+## Sections
+
+### Section 1: Single Tweet
+See `references/twitter-posting.md`
+- Tweet creation with text, media, and reply-to
+- Character limit enforcement (280 chars)
+- Hashtag and mention strategy
+- Link sharing and Twitter card generation
+
+### Section 2: Thread Creation
+See `references/twitter-posting.md`
+- Blog post → thread conversion
+- Thread splitting logic
+- Sequential reply-chaining
+- Best practices for thread engagement
+
+### Section 3: Metrics
+See `references/twitter-analytics.md`
+- Tweet impressions, likes, retweets, replies, quotes
+- Performance tracking over time
+- Engagement benchmarks
+
+### Section 4: Tweet Deletion
+- Delete a specific tweet by ID
+- Safety hook requires explicit user confirmation
+- Deletion is irreversible
+
+### Section 5: Setup Guide
+See `references/twitter-setup.md`
+- Twitter Developer Portal app creation
+- API v2 Bearer token generation
+- WP_SITES_CONFIG configuration
+- Required access levels and permissions
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/twitter-setup.md` | Developer portal, API keys, WP_SITES_CONFIG, permissions |
+| `references/twitter-posting.md` | Tweets, threads, content adaptation, formatting |
+| `references/twitter-analytics.md` | Metrics, engagement tracking, performance benchmarks |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `tw_create_tweet` | Publish a tweet (text, media, reply-to) |
+| `tw_create_thread` | Publish a connected tweet thread |
+| `tw_get_metrics` | Get tweet metrics (impressions, likes, retweets) |
+| `tw_list_tweets` | List recent user tweets |
+| `tw_delete_tweet` | Delete a tweet (irreversible, safety hook) |
+
+## Recommended Agent
+
+Use the **`wp-distribution-manager`** agent for multi-channel workflows that combine Twitter/X with Mailchimp, Buffer, SendGrid, and LinkedIn.
+
+## Related Skills
+
+- **`wp-linkedin`** — LinkedIn direct publishing (B2B channel)
+- **`wp-social-email`** — Mailchimp, Buffer, SendGrid distribution
+- **`wp-content-repurposing`** — Transform blog content into tweet-optimized formats
+- **`wp-content`** — Create source WordPress content for distribution