claude-plugin-wordpress-manager 2.3.1 → 2.4.0

package/skills/wp-social-email/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: wp-social-email
+description: This skill should be used when the user asks to "publish to social media",
+  "schedule social posts", "send email campaign", "Mailchimp integration",
+  "Buffer scheduling", "SendGrid email", "content distribution",
+  "newsletter campaign", "email marketing", "social media management",
+  "distribute content", or mentions publishing WordPress content to social
+  and email channels.
+version: 1.0.0
+---
+
+# WordPress Social & Email Distribution Skill
+
+## Overview
+
+Social and email distribution connects WordPress content to external marketing channels via three services: Mailchimp (email campaigns and audience management), Buffer (social media scheduling and publishing), and SendGrid (transactional email delivery). The WP REST Bridge provides 18 MCP tools across these services, enabling content distribution workflows directly from the WordPress authoring environment.
+
+## When to Use
+
+- User wants to send a newsletter or email campaign from WordPress content
+- User needs to schedule social media posts when a blog post is published
+- User asks about Mailchimp audience management or subscriber lists
+- User wants to connect Buffer for social media scheduling
+- User needs transactional email delivery via SendGrid (welcome emails, confirmations)
+- User asks about content distribution pipelines (blog → social → email)
+- User wants to segment audiences for targeted campaigns
+- User needs analytics on email open rates, click rates, or social engagement
+
+## Decision Tree
+
+1. **What channel or service?**
+   - "Mailchimp" / "audience" / "email campaign" / "newsletter" → Mailchimp integration (Section 1)
+   - "Buffer" / "social post" / "schedule tweet" / "social media" → Buffer social publishing (Section 2)
+   - "SendGrid" / "transactional email" / "email delivery" → SendGrid transactional (Section 3)
+   - "distribute content" / "blog to social" / "content pipeline" → Content-to-distribution workflow (Section 4)
+   - "audience segment" / "targeting" / "list management" → Audience segmentation (Section 5)
+   - "email analytics" / "open rate" / "click rate" / "campaign report" → Distribution analytics (Section 6)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-social-email/scripts/distribution_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured distribution services and API credentials.
+
+## Service Overview
+
+| Service | Tools | Auth Type | Use Case |
+|---------|-------|-----------|----------|
+| Mailchimp | 7 tools (`mc_*`) | API key | Email campaigns, audience management, subscriber lists |
+| Buffer | 5 tools (`buf_*`) | Access token | Social media scheduling, queue management, analytics |
+| SendGrid | 6 tools (`sg_*`) | API key | Transactional email, templates, contact management |
+
+## Distribution Sections
+
+### Section 1: Mailchimp Integration
+See `references/mailchimp-integration.md`
+- API key setup and WP_SITES_CONFIG configuration
+- Audience management (list, get members, add subscribers)
+- Campaign workflow: create → set content → send → report
+- A/B testing and send time optimization
+
+### Section 2: Buffer Social Publishing
+See `references/buffer-social-publishing.md`
+- Access token setup and WP_SITES_CONFIG configuration
+- Profile management and channel connections
+- Post creation with media attachments and scheduling
+- Queue management and posting analytics
+
+### Section 3: SendGrid Transactional Email
+See `references/sendgrid-transactional.md`
+- API key setup and WP_SITES_CONFIG configuration
+- Transactional email for welcome, password reset, order confirmation
+- Dynamic template management
+- Contact management and email deliverability
+
+### Section 4: Content-to-Distribution Workflow
+See `references/content-to-distribution.md`
+- WordPress-to-channel pipeline (fetch post → format → distribute)
+- Content adaptation per channel (blog → social, blog → newsletter)
+- Scheduling strategies (immediate, drip, evergreen rotation)
+- Multi-channel orchestration
+
+### Section 5: Audience Segmentation
+See `references/audience-segmentation.md`
+- Mailchimp list segmentation strategies
+- SendGrid contact lists and custom fields
+- Buffer profile-based targeting
+- Building audience personas from WordPress user data
+
+### Section 6: Distribution Analytics
+See `references/distribution-analytics.md`
+- Mailchimp campaign reports (open rate, click rate, bounces)
+- Buffer analytics (reach, engagement, clicks)
+- SendGrid stats (deliverability, opens, clicks)
+- Cross-channel performance comparison and KPIs
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/mailchimp-integration.md` | API setup, audiences, campaigns, A/B testing |
+| `references/buffer-social-publishing.md` | Access token, profiles, posts, queue management |
+| `references/sendgrid-transactional.md` | API setup, transactional email, templates, contacts |
+| `references/content-to-distribution.md` | Content pipeline, adaptation, scheduling, multi-channel |
+| `references/audience-segmentation.md` | List segmentation, custom fields, personas |
+| `references/distribution-analytics.md` | Campaign reports, social stats, KPIs, benchmarks |
+
+## MCP Tools
+
+### Mailchimp Tools (7)
+
+| Tool | Description |
+|------|-------------|
+| `mc_list_audiences` | List all Mailchimp audiences (lists) with member counts |
+| `mc_get_audience_members` | Get subscribers for a specific audience with pagination |
+| `mc_add_subscriber` | Add or update a subscriber in an audience |
+| `mc_create_campaign` | Create a new email campaign (regular, plaintext, A/B test) |
+| `mc_set_campaign_content` | Set the HTML or template content for a campaign |
+| `mc_send_campaign` | Send or schedule a campaign for delivery |
+| `mc_get_campaign_report` | Get campaign performance metrics (opens, clicks, bounces) |
+
+### Buffer Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `buf_list_profiles` | List connected social media profiles (Twitter, Facebook, LinkedIn, etc.) |
+| `buf_create_update` | Create a social media post with text, media, and optional schedule time |
+| `buf_list_pending` | List posts in the Buffer queue awaiting publication |
+| `buf_list_sent` | List previously published posts with engagement data |
+| `buf_get_analytics` | Get analytics for a profile (reach, engagement, clicks) |
+
+### SendGrid Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `sg_send_email` | Send a transactional email (plain, HTML, or template-based) |
+| `sg_list_templates` | List available dynamic email templates |
+| `sg_get_template` | Get template details including version and HTML content |
+| `sg_list_contacts` | List contacts with optional search and filtering |
+| `sg_add_contacts` | Add or update contacts with custom fields |
+| `sg_get_stats` | Get email statistics (deliveries, opens, clicks, bounces) |
+
+## Recommended Agent
+
+Use the **`wp-distribution-manager`** agent for complex multi-channel distribution workflows that span multiple services or require coordinated content adaptation.
+
+## Related Skills
+
+- **`wp-content-repurposing`** — transform content formats before distribution
+- **`wp-webhooks`** — trigger distribution on WordPress events (publish, update)
+- **`wp-content`** — create and manage WordPress content for distribution
+- **`wp-content-attribution`** — track content sources and attribution across channels

package/skills/wp-social-email/references/audience-segmentation.md

@@ -0,0 +1,173 @@
+# Audience Segmentation
+
+## Overview
+
+Audience segmentation divides your subscriber base into targeted groups for more relevant messaging. Effective segmentation improves open rates, click rates, and reduces unsubscribes. This reference covers segmentation strategies across Mailchimp, SendGrid, and Buffer.
+
+## Mailchimp List Segmentation
+
+### Segment by subscriber data
+
+Mailchimp segments are dynamic filters applied to an audience. Subscribers matching the criteria are automatically included.
+
+```
+Tool: mc_get_audience_members
+Params:
+  audience_id: "abc123def4"
+  status: "subscribed"
+  # Filter by merge fields, tags, or activity in the Mailchimp UI
+```
+
+### Tag-based segmentation
+
+Tags are the most flexible segmentation method via the API:
+
+```
+Tool: mc_add_subscriber
+Params:
+  audience_id: "abc123def4"
+  email: "user@example.com"
+  tags: ["wordpress-user", "product-interest-seo", "signup-2026-q1"]
+```
+
+### Common Mailchimp segments
+
+| Segment | Criteria | Use Case |
+|---------|----------|----------|
+| New subscribers | Signup date < 30 days | Welcome series, onboarding |
+| Engaged readers | Opened last 3 campaigns | Premium content, surveys |
+| Inactive | Not opened in 90 days | Re-engagement campaign |
+| Product interest | Tagged by category | Targeted product launches |
+| High-value | Purchase history > $100 | VIP offers, early access |
+| Location-based | Merge field `COUNTRY` | Localized content, events |
+
+### Merge fields for segmentation
+
+Define custom merge fields to capture WordPress user data:
+
+| Merge Tag | Type | WordPress Source |
+|-----------|------|-----------------|
+| `FNAME` | Text | `user.first_name` |
+| `LNAME` | Text | `user.last_name` |
+| `WP_ROLE` | Text | `user.role` (subscriber, customer, etc.) |
+| `SIGNUP_SRC` | Text | Registration source (blog, checkout, popup) |
+| `LAST_ORDER` | Date | Most recent WooCommerce order date |
+| `ORDER_TOTAL` | Number | Lifetime order value |
+
+## SendGrid Contact Segmentation
+
+### Contact lists
+
+SendGrid uses contact lists for static segmentation:
+
+```
+Tool: sg_add_contacts
+Params:
+  list_ids: ["list_new_users", "list_blog_subscribers"]
+  contacts:
+    - email: "user@example.com"
+      first_name: "Jane"
+      custom_fields:
+        signup_source: "blog_popup"
+        wp_user_id: "42"
+```
+
+### Custom fields
+
+Define custom fields in SendGrid to mirror WordPress user data:
+
+| Field Name | Type | Purpose |
+|------------|------|---------|
+| `wp_user_id` | Number | Link to WordPress user record |
+| `signup_source` | Text | Track acquisition channel |
+| `user_role` | Text | WordPress role for permission-based content |
+| `last_purchase_date` | Date | Trigger post-purchase sequences |
+| `content_preference` | Text | Category interest for targeted notifications |
+
+### SGQL queries for segmentation
+
+```
+Tool: sg_list_contacts
+Params:
+  query: "signup_source = 'blog_popup' AND last_purchase_date IS NULL"
+```
+
+Common SGQL patterns:
+
+| Query | Segment |
+|-------|---------|
+| `signup_source = 'checkout'` | Customers who bought |
+| `last_purchase_date < '2026-01-01'` | Lapsed customers |
+| `user_role = 'subscriber'` | Blog-only subscribers |
+| `content_preference = 'tutorials'` | Tutorial readers |
+
+## Buffer Profile-Based Targeting
+
+Buffer segments audiences by social profile rather than individual users. Each profile reaches a different audience.
+
+### Profile selection strategy
+
+| Profile | Audience Type | Content Style |
+|---------|--------------|---------------|
+| Twitter/X | Tech-savvy, real-time | Short, punchy, hashtags |
+| LinkedIn | Professional, B2B | Thought leadership, data-driven |
+| Facebook | Broad, community | Storytelling, engagement prompts |
+| Instagram | Visual-first, younger | Image-heavy, lifestyle |
+
+### Targeting by profile
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["linkedin_id"]    # Only post to LinkedIn for B2B content
+  text: "Our latest research on WordPress performance..."
+```
+
+Select profiles based on content type:
+- **Product launches**: All profiles
+- **Technical tutorials**: Twitter + LinkedIn
+- **Behind-the-scenes**: Instagram + Facebook
+- **Industry news**: Twitter + LinkedIn
+
+## Building Personas from WordPress Data
+
+### Data sources for persona building
+
+| Source | Data | Tool |
+|--------|------|------|
+| WordPress users | Role, registration date, profile fields | `wp_list_users` |
+| WooCommerce orders | Purchase history, AOV, frequency | `wc_list_orders` |
+| Post analytics | Most-read categories, time on page | Site analytics |
+| Form submissions | Stated interests, preferences | Contact form data |
+
+### Persona-to-segment mapping
+
+| Persona | Characteristics | Mailchimp Tags | SendGrid Lists |
+|---------|----------------|----------------|----------------|
+| New Visitor | First 30 days, no purchase | `new-visitor` | `list_onboarding` |
+| Blog Reader | Regular reader, no purchase | `blog-reader`, category tags | `list_blog` |
+| First Buyer | 1 order, < $50 | `first-buyer` | `list_customers` |
+| Loyal Customer | 3+ orders, > $200 | `loyal-customer`, `vip` | `list_vip` |
+| Churning | No activity 60+ days | `at-risk` | `list_reengagement` |
+
+### Sync WordPress users to segments
+
+Workflow to keep segments current:
+
+```
+1. wp_list_users → fetch all users with roles and metadata
+2. For each user, determine persona based on rules
+3. mc_add_subscriber → set tags matching persona
+4. sg_add_contacts → add to appropriate contact lists
+5. Schedule weekly sync to update segment membership
+```
+
+## Best Practices
+
+- **Start simple**: Begin with 3-4 segments (new, active, inactive, customer); add granularity as data grows
+- **Dynamic over static**: Prefer Mailchimp tag-based segments that update automatically over manually managed lists
+- **Consistent field naming**: Use the same custom field names across Mailchimp and SendGrid for easier cross-channel management
+- **Hygiene**: Remove hard bounces and unsubscribes from all platforms; sync removals across services
+- **Privacy compliance**: Honor opt-out preferences across all channels; never re-add unsubscribed contacts
+- **Test segments**: Before sending a campaign to a new segment, verify member count and sample members for accuracy
+- **Document segments**: Maintain a segment registry with criteria, purpose, and last review date

package/skills/wp-social-email/references/buffer-social-publishing.md

@@ -0,0 +1,124 @@
+# Buffer Social Publishing
+
+## Overview
+
+Buffer is a social media scheduling platform that manages posting across Twitter/X, Facebook, Instagram, LinkedIn, and other channels. The WP REST Bridge provides 5 MCP tools (`buf_*`) for creating posts, managing queues, and retrieving analytics.
+
+## Setup
+
+### Access Token Configuration
+
+Add Buffer credentials to `WP_SITES_CONFIG`:
+
+```json
+{
+  "sites": [{
+    "name": "my-site",
+    "url": "https://example.com",
+    "distribution": {
+      "buffer": {
+        "access_token": "1/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }]
+}
+```
+
+Obtain the access token from Buffer's developer portal (Settings → Apps → Access Token).
+
+## Profile Management
+
+### List connected profiles
+
+```
+Tool: buf_list_profiles
+Returns: Array of profiles with id, service (twitter, facebook, etc.),
+         formatted_username, avatar, schedules, counts
+```
+
+Each profile represents a connected social account. A single Buffer account may have multiple profiles (e.g., @company on Twitter + Company Page on Facebook).
+
+## Post Creation
+
+### Create a social post
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["profile_abc123"]
+  text: "New blog post: 10 Tips for Better SEO — Read more at https://example.com/seo-tips"
+  scheduled_at: "2026-03-15T14:00:00Z"   # Optional: omit for immediate queue
+```
+
+### Create a post with media
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["profile_abc123", "profile_def456"]
+  text: "Check out our latest product launch!"
+  media:
+    photo: "https://example.com/wp-content/uploads/2026/03/product-launch.jpg"
+    thumbnail: "https://example.com/wp-content/uploads/2026/03/product-launch-thumb.jpg"
+```
+
+### Post to multiple profiles
+
+Pass an array of `profile_ids` to publish the same content across channels simultaneously. Buffer adapts character limits per platform.
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["twitter_id", "facebook_id", "linkedin_id"]
+  text: "We just published a comprehensive guide to WordPress performance optimization."
+```
+
+## Queue Management
+
+### List pending posts
+
+```
+Tool: buf_list_pending
+Params:
+  profile_id: "profile_abc123"
+Returns: Array of queued posts with id, text, scheduled_at, media
+```
+
+### List sent posts
+
+```
+Tool: buf_list_sent
+Params:
+  profile_id: "profile_abc123"
+  count: 20
+  page: 1
+Returns: Array of published posts with engagement metrics
+```
+
+## WordPress-to-Buffer Workflow
+
+Typical flow for distributing a WordPress post to social media:
+
+1. **Fetch the post** using `wp_get_post` to get title, excerpt, permalink, featured image
+2. **Format for social**: Compose text from post title + excerpt (truncated to platform limits)
+3. **Attach media**: Use the featured image URL as the `media.photo` parameter
+4. **Schedule**: Set `scheduled_at` for optimal posting time or omit for queue placement
+5. **Post to profiles**: Select target profiles and call `buf_create_update`
+
+```
+# Example: Blog post → Twitter + LinkedIn
+Step 1: wp_get_post id=42 → { title, excerpt, link, featured_media_url }
+Step 2: Compose text = "📝 {title}\n\n{excerpt}\n\nRead more: {link}"
+Step 3: buf_create_update profile_ids=[twitter, linkedin] text=... media.photo={featured_media_url}
+```
+
+## Best Practices
+
+- **Optimal posting times**: Analyze `buf_get_analytics` to identify when your audience is most active; schedule posts during those windows
+- **Platform-specific formatting**: Twitter has 280 chars; LinkedIn allows 3000; tailor text length per profile rather than using identical copy
+- **Hashtag strategy**: Use 1-2 relevant hashtags on Twitter, 3-5 on LinkedIn; avoid hashtags on Facebook
+- **Image dimensions**: Use 1200x628px for link previews, 1080x1080px for square posts; Buffer will resize but starting with correct dimensions avoids cropping
+- **Queue spacing**: Buffer's default schedule spaces posts throughout the day; avoid overriding with manual times unless needed
+- **Evergreen content**: Re-queue high-performing posts using `buf_list_sent` to identify top performers, then `buf_create_update` to re-share
+- **UTM parameters**: Append `?utm_source=buffer&utm_medium=social&utm_campaign={campaign}` to URLs for tracking in Google Analytics
+- **Avoid duplicate content**: Check `buf_list_pending` before creating new posts to prevent queue duplication

package/skills/wp-social-email/references/content-to-distribution.md

@@ -0,0 +1,156 @@
+# Content-to-Distribution Workflow
+
+## Overview
+
+The content-to-distribution pipeline transforms WordPress content into format-appropriate messages for email and social channels. This reference covers the full workflow: fetching content, adapting it per channel, scheduling distribution, and orchestrating multi-channel campaigns.
+
+## WordPress-to-Channel Pipeline
+
+### Core flow
+
+```
+WordPress Post → Fetch Content → Adapt Format → Distribute
+                 (wp_get_post)   (per channel)   (mc_*/buf_*/sg_*)
+```
+
+### Step 1: Fetch the source content
+
+```
+Tool: wp_get_post
+Params:
+  id: 42
+  _embed: true    # Include featured image, author, categories
+Returns:
+  title, excerpt, content (HTML), permalink, featured_media_url,
+  author, categories, tags, date
+```
+
+### Step 2: Adapt for each channel
+
+The same post requires different formatting per distribution target.
+
+### Step 3: Distribute via service tools
+
+Route the adapted content to the appropriate MCP tool.
+
+## Content Adaptation Per Channel
+
+### Blog → Newsletter (Mailchimp)
+
+| Element | Adaptation |
+|---------|------------|
+| Title | Campaign subject line (max 150 chars, add emoji or personalization) |
+| Excerpt | Preview text (max 200 chars) |
+| Content | Full HTML body, reformatted for email (inline CSS, max 600px width) |
+| Featured image | Hero image at top of email (600px wide) |
+| CTA | "Read the full post" button linking to permalink |
+
+```
+1. wp_get_post → extract title, content, featured_image
+2. mc_create_campaign → subject = post title, from_name = site name
+3. mc_set_campaign_content → html = email-formatted post content
+4. mc_send_campaign → deliver or schedule
+```
+
+### Blog → Social Post (Buffer)
+
+| Platform | Adaptation |
+|----------|------------|
+| Twitter/X | Title + shortened excerpt (max 250 chars with URL) |
+| LinkedIn | Title + full excerpt + 3-5 hashtags (max 700 chars) |
+| Facebook | Title + excerpt + URL (no character pressure) |
+| Instagram | Excerpt + 10-15 hashtags (image required) |
+
+```
+1. wp_get_post → extract title, excerpt, permalink, featured_image
+2. Compose platform-specific text variants
+3. buf_create_update → text, media.photo, profile_ids, scheduled_at
+```
+
+### Blog → Transactional Notification (SendGrid)
+
+For notifying specific users about relevant new content:
+
+```
+1. wp_get_post → extract title, excerpt, permalink
+2. sg_list_contacts → find users matching content category
+3. sg_send_email → template with post title, excerpt, read-more link
+```
+
+## Scheduling Strategies
+
+### Immediate distribution
+
+Publish to all channels as soon as the WordPress post goes live. Best for breaking news or time-sensitive content.
+
+```
+1. WordPress publish event triggers distribution
+2. mc_send_campaign (send now)
+3. buf_create_update (no scheduled_at → immediate queue)
+4. sg_send_email (immediate delivery)
+```
+
+### Staggered distribution
+
+Spread distribution across hours or days to maximize reach across time zones and channel algorithms.
+
+```
+Day 0, Hour 0:  Blog post published
+Day 0, Hour 1:  buf_create_update → Twitter (immediate engagement)
+Day 0, Hour 4:  buf_create_update → LinkedIn (business hours)
+Day 1, Hour 10: mc_send_campaign → Newsletter (Tuesday 10am optimal)
+Day 3:          buf_create_update → Facebook (extend reach)
+Day 7:          sg_send_email → Re-engagement for non-openers
+```
+
+### Evergreen rotation
+
+Re-distribute high-performing content on a recurring schedule:
+
+```
+1. buf_list_sent → identify posts with highest engagement
+2. Filter for content older than 30 days (avoid fatigue)
+3. buf_create_update → re-share with updated text
+4. Track performance to retire content below threshold
+```
+
+## Multi-Channel Distribution Workflow
+
+### Full orchestration example
+
+Distribute a new blog post across all three services:
+
+```
+# 1. Fetch source content
+wp_get_post id=42 → { title, excerpt, content, permalink, featured_image }
+
+# 2. Email campaign (Mailchimp)
+mc_create_campaign type="regular" audience_id=... subject="{title}"
+mc_set_campaign_content campaign_id=... html="{formatted_content}"
+mc_send_campaign campaign_id=... schedule_time="2026-03-15T10:00:00Z"
+
+# 3. Social posts (Buffer)
+buf_create_update profile_ids=[twitter] text="{short_text}" media.photo="{featured_image}"
+buf_create_update profile_ids=[linkedin] text="{long_text}" scheduled_at="2026-03-15T14:00:00Z"
+
+# 4. Notification email (SendGrid)
+sg_send_email to="vip-subscribers" template_id="d-newpost" dynamic_template_data={title, excerpt, permalink}
+```
+
+### Coordination checklist
+
+- [ ] Source content finalized and published on WordPress
+- [ ] Email campaign created and content set (Mailchimp)
+- [ ] Social posts queued for each target profile (Buffer)
+- [ ] Transactional notifications sent to relevant user segments (SendGrid)
+- [ ] UTM parameters appended to all outbound URLs
+- [ ] Analytics tracking confirmed for each channel
+
+## Best Practices
+
+- **Single source of truth**: Always fetch content from WordPress (`wp_get_post`) rather than duplicating content manually
+- **URL tracking**: Append UTM parameters per channel (`utm_source=mailchimp`, `utm_source=buffer`, `utm_source=sendgrid`)
+- **Content freshness**: Verify post status is `publish` before distributing; draft content should never reach channels
+- **Error handling**: If one channel fails, proceed with others; log failures and retry individually
+- **Preview before send**: Use Mailchimp preview and Buffer draft features to review formatting before live distribution
+- **Audience overlap**: Be mindful that users may follow multiple channels; vary the messaging slightly to avoid fatigue