claude-plugin-wordpress-manager 2.9.0 → 2.12.0

package/skills/wp-content-repurposing/references/transform-templates.md

@@ -0,0 +1,304 @@
+# Transform Templates
+
+Ready-to-use templates for converting WordPress content into platform-specific formats.
+
+## Template 1: Blog → Tweet (Single)
+
+**Format rules:**
+- Max 280 characters (link counts as ~23 chars)
+- Structure: Hook + key takeaway + link + hashtags
+- Tone: Casual, punchy, curiosity-driven
+
+**Template:**
+```
+{hook_sentence} {key_takeaway}
+
+{post_url}
+
+{hashtags}
+```
+
+**Character budget:**
+| Element | Max Chars |
+|---------|-----------|
+| Hook + takeaway | ~220 |
+| URL | ~23 |
+| Hashtags (2-3) | ~35 |
+
+**Example input:**
+```
+Title: "5 Benefits of Cactus Water for Summer Hydration"
+Excerpt: "Cactus water from Sicilian prickly pear is packed with electrolytes,
+antioxidants, and has zero calories. Here's why it's the perfect summer drink."
+Tags: ["cactus water", "hydration", "zero calorie"]
+```
+
+**Example output:**
+```
+Zero calories, packed with electrolytes — cactus water is the summer drink
+you didn't know you needed 🌵
+
+https://dolcezero.com/cactus-water-benefits
+
+#cactuswater #hydration #zerocalorie
+```
+
+**Hashtag generation logic:**
+1. Take post tags, lowercase, remove spaces → `#cactuswater`
+2. Add 1-2 category-based hashtags → `#healthydrinks`
+3. Cap at 3 hashtags for Twitter (engagement drops with more)
+
+---
+
+## Template 2: Blog → Twitter Thread
+
+**Format rules:**
+- Tweet 1: Hook with promise ("Here's what we learned about X" or "N things about X")
+- Middle tweets: One key point per tweet, numbered
+- Last tweet: CTA with link
+- Each tweet max 280 chars
+- Split by H2 sections or key points
+
+**Template:**
+```
+Tweet 1 (hook):
+{numbered_promise_or_question}
+
+A thread 🧵👇
+
+Tweet 2-N (key points):
+{number}/ {section_heading}
+
+{key_point_summary}
+
+Tweet N+1 (CTA):
+If you found this useful, check out the full article:
+
+{post_url}
+
+{hashtags}
+```
+
+**Splitting rules:**
+- If post has H2 headings: 1 tweet per H2 (summarize section in 250 chars)
+- If no H2s: Extract sentences with numbers/stats/claims, 1 per tweet
+- Max thread length: 10 tweets (5-7 optimal for engagement)
+- Each middle tweet should stand alone (valuable without reading the thread)
+
+**Example input:**
+```
+Title: "5 Benefits of Cactus Water for Summer Hydration"
+H2s: ["Rich in Electrolytes", "Zero Calories", "Antioxidant Power",
+      "Sustainable Sourcing", "Naturally Refreshing"]
+```
+
+**Example output:**
+```
+Tweet 1:
+5 reasons cactus water is the smartest hydration choice this summer
+
+A thread 🧵👇
+
+Tweet 2:
+1/ Rich in Electrolytes
+
+Prickly pear cactus naturally contains potassium, magnesium, and calcium —
+the same electrolytes you'd find in sports drinks, without the sugar.
+
+Tweet 3:
+2/ Zero Calories
+
+Unlike coconut water (45 cal) or fruit juice (110+ cal), cactus water
+delivers hydration at exactly 0 calories per serving.
+
+...
+
+Tweet 6:
+Found this useful? Read the full breakdown:
+
+https://dolcezero.com/cactus-water-benefits
+
+#cactuswater #hydration #zerocalorie
+```
+
+---
+
+## Template 3: Blog → LinkedIn Post
+
+**Format rules:**
+- Max 3,000 characters (optimal: 1,300-1,700)
+- Structure: Hook line → story/insight → key takeaway → CTA → hashtags
+- Tone: Professional, thought-leadership, data-driven
+- Line breaks between paragraphs for readability
+- Link in post body (not first comment for simplicity)
+
+**Template:**
+```
+{hook_line}
+
+{context_or_story}
+
+{key_insight_with_data}
+
+{takeaway_or_opinion}
+
+{cta_with_link}
+
+{hashtags}
+```
+
+**Example input:**
+```
+Title: "How We Reduced Sugar Content to Zero Without Losing Taste"
+Excerpt: "Our R&D team spent 18 months developing a proprietary process
+that uses Sicilian prickly pear as a natural sweetness base..."
+Tags: ["food technology", "zero sugar", "innovation"]
+```
+
+**Example output:**
+```
+We spent 18 months on a single question: can a drink taste sweet with
+literally zero sugar?
+
+The answer surprised even our food scientists.
+
+Sicilian prickly pear cactus has a naturally sweet flavor profile.
+By extracting and concentrating its essence, we created a beverage base
+that delivers sweetness perception without any added sugars or
+artificial sweeteners.
+
+The result: a drink that scored 8.2/10 in blind taste tests against
+traditional sweetened beverages.
+
+Key insight: consumers don't want "less sugar." They want full flavor
+with zero compromise. That's what drove our entire product philosophy.
+
+Full story on our process → https://dolcezero.com/zero-sugar-innovation
+
+#FoodTechnology #ZeroSugar #BeverageInnovation #ProductDevelopment
+```
+
+**Hashtag generation logic:**
+1. Take post tags → professional case: `#FoodTechnology`
+2. Add industry hashtags: `#Innovation`, `#ProductDevelopment`
+3. Cap at 3-5 hashtags (LinkedIn penalizes excessive hashtags)
+4. Use PascalCase for multi-word hashtags
+
+---
+
+## Template 4: Blog → LinkedIn Article
+
+**Format rules:**
+- Full long-form content adaptation (up to 125,000 chars)
+- Preserve HTML structure: H2 → article sections, lists → bullet points
+- Add professional introduction paragraph (not in original post)
+- Add author bio and CTA at the end
+- Strip WordPress-specific shortcodes and embeds
+- Requires user confirmation (safety hook active on `li_create_article`)
+
+**Template:**
+```
+Title: {post_title}
+
+{professional_intro_paragraph}
+
+{adapted_content_with_html}
+
+---
+
+{author_bio_cta}
+```
+
+**HTML adaptation rules:**
+- Keep: `<h2>`, `<h3>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<strong>`, `<em>`, `<blockquote>`
+- Strip: `<script>`, `<style>`, `<iframe>`, WordPress shortcodes `[shortcode]`
+- Convert: `<img>` with featured image only (LinkedIn renders inline images in articles)
+- Remove: WordPress block comments `<!-- wp:paragraph -->`
+
+**When to use article vs feed post:**
+| Criteria | Feed Post | Article |
+|----------|-----------|---------|
+| Word count | < 500 words | > 500 words |
+| Content type | Quick insight, update | Tutorial, case study, analysis |
+| Engagement goal | Likes, comments | Thought leadership, saves |
+| Link included | Yes (drive traffic) | Optional (content is self-contained) |
+
+---
+
+## Template 5: Blog → Email Snippet
+
+**Format rules:**
+- Structure: Subject line + preview text + snippet body + CTA button
+- Snippet length: 150-200 words (enough to entice, not enough to satisfy)
+- CTA: "Read the full article" or "Continue reading"
+- For use with Mailchimp (`mc_set_campaign_content`) or SendGrid (`sg_send_email`)
+
+**Template:**
+```
+Subject: {compelling_subject_line}
+Preview: {first_line_preview_text}
+
+---
+
+{post_title}
+
+{excerpt_or_first_paragraph}
+
+{one_key_statistic_or_insight}
+
+[Read the full article →]({post_url})
+```
+
+**Subject line formulas:**
+1. **Number + benefit**: "5 ways cactus water improves your hydration"
+2. **Question**: "Is cactus water the next coconut water?"
+3. **How-to**: "How we made zero-calorie taste amazing"
+4. **Curiosity gap**: "The Sicilian secret behind our water"
+
+**Example input:**
+```
+Title: "5 Benefits of Cactus Water for Summer Hydration"
+Excerpt: "Cactus water from Sicilian prickly pear is packed with electrolytes..."
+URL: "https://dolcezero.com/cactus-water-benefits"
+```
+
+**Example output:**
+```
+Subject: 5 reasons cactus water beats coconut water this summer
+Preview: Zero calories, natural electrolytes, and a taste you won't believe
+
+---
+
+5 Benefits of Cactus Water for Summer Hydration
+
+Cactus water from Sicilian prickly pear is packed with electrolytes,
+antioxidants, and has zero calories. It's everything you want from a
+hydration drink — without the sugar.
+
+Key finding: In our tests, cactus water delivered 40% more potassium
+per serving than leading coconut water brands.
+
+[Read the full article →](https://dolcezero.com/cactus-water-benefits)
+```
+
+---
+
+## Template Selection Guide
+
+| Source Content | Short (< 500 words) | Long (≥ 500 words) |
+|---------------|---------------------|--------------------|
+| Blog post | Tweet + LinkedIn post + email snippet | Thread + LinkedIn article + email snippet |
+| Product page | Tweet + LinkedIn post | Tweet + LinkedIn post + email snippet |
+| Case study | LinkedIn post + email snippet | Thread + LinkedIn article + email snippet |
+| News/update | Tweet | Tweet + LinkedIn post |
+
+## Multi-Channel Workflow
+
+For full pipeline execution (1 post → all channels):
+
+1. Fetch post with `wp_get_post`
+2. Extract elements (title, excerpt, headings, key points, tags, image)
+3. Apply templates in order: Tweet → Thread (if applicable) → LinkedIn → Email
+4. Preview all outputs for user review
+5. Dispatch via: `tw_create_tweet` → `tw_create_thread` → `li_create_post` → `mc_set_campaign_content`
+6. Report: channels published, content IDs, analytics check schedule

package/skills/wp-linkedin/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: wp-linkedin
+description: This skill should be used when the user asks to "publish to LinkedIn",
+  "LinkedIn post", "LinkedIn article", "B2B social", "pubblica su LinkedIn",
+  "LinkedIn analytics", "LinkedIn engagement", or mentions LinkedIn publishing
+  and analytics for WordPress content.
+version: 1.0.0
+tags: [linkedin, social-media, b2b, direct-social]
+---
+
+# WordPress LinkedIn Integration Skill
+
+## Overview
+
+Direct LinkedIn publishing connects WordPress content to LinkedIn via the Community Management API v2. This enables B2B-focused content distribution: feed posts for quick updates, long-form articles for blog-to-LinkedIn workflows, and analytics for engagement tracking. The WP REST Bridge provides 5 MCP tools with the `li_*` namespace.
+
+## When to Use
+
+- User wants to publish a WordPress blog post to LinkedIn
+- User needs to create LinkedIn feed posts from WordPress content
+- User wants to publish a long-form LinkedIn article from a blog post
+- User asks about LinkedIn post analytics (impressions, clicks, engagement)
+- User needs B2B social media distribution from WordPress
+
+## Decision Tree
+
+1. **What LinkedIn action?**
+   - "publish post" / "LinkedIn update" / "feed post" → Posting workflow (Section 1)
+   - "article" / "long-form" / "blog to LinkedIn" → Article publishing (Section 2)
+   - "analytics" / "engagement" / "impressions" → Analytics (Section 3)
+   - "setup" / "configure" / "connect LinkedIn" → Setup guide (Section 4)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-linkedin/scripts/linkedin_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured LinkedIn credentials in WP_SITES_CONFIG.
+
+## Sections
+
+### Section 1: LinkedIn Posting
+See `references/linkedin-posting.md`
+- Feed post creation with text, links, and images
+- Visibility settings (PUBLIC vs CONNECTIONS)
+- Content adaptation from WordPress excerpt/title
+- Hashtag strategy and mention formatting
+
+### Section 2: Article Publishing
+See `references/linkedin-posting.md`
+- Blog post → LinkedIn article conversion
+- HTML content formatting for LinkedIn
+- Thumbnail and media handling
+- Article vs post decision criteria
+
+### Section 3: Analytics
+See `references/linkedin-analytics.md`
+- Post impressions and engagement metrics
+- Click-through rates and share counts
+- Performance comparison across posts
+- B2B content performance benchmarks
+
+### Section 4: Setup Guide
+See `references/linkedin-setup.md`
+- LinkedIn Developer App creation
+- OAuth 2.0 access token generation
+- WP_SITES_CONFIG configuration
+- Required scopes: w_member_social, r_liteprofile
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/linkedin-setup.md` | Developer app, OAuth setup, WP_SITES_CONFIG, scopes |
+| `references/linkedin-posting.md` | Post creation, articles, content adaptation, formatting |
+| `references/linkedin-analytics.md` | Metrics, engagement tracking, performance benchmarks |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `li_get_profile` | Get authenticated LinkedIn user profile |
+| `li_create_post` | Create a LinkedIn feed post (text, link, image) |
+| `li_create_article` | Publish a long-form LinkedIn article |
+| `li_get_analytics` | Get post analytics (impressions, clicks, engagement) |
+| `li_list_posts` | List recent posts by the authenticated user |
+
+## Recommended Agent
+
+Use the **`wp-distribution-manager`** agent for multi-channel workflows that combine LinkedIn with Mailchimp, Buffer, SendGrid, and Twitter/X.
+
+## Related Skills
+
+- **`wp-twitter`** — Twitter/X direct publishing (awareness channel)
+- **`wp-social-email`** — Mailchimp, Buffer, SendGrid distribution
+- **`wp-content-repurposing`** — Transform blog content into LinkedIn-optimized formats
+- **`wp-content`** — Create source WordPress content for distribution

package/skills/wp-linkedin/references/linkedin-analytics.md

@@ -0,0 +1,58 @@
+# LinkedIn Analytics Guide
+
+## Available Metrics
+
+Use `li_get_analytics` to retrieve post performance data.
+
+### Post-Level Metrics
+- **impressions** — Number of times the post was shown in feeds
+- **clicks** — Total clicks on the post (content, company name, logo)
+- **likes** — Number of likes/reactions
+- **comments** — Number of comments
+- **shares** — Number of reposts
+- **engagement rate** — (clicks + likes + comments + shares) / impressions
+
+### Time Periods
+- `day` — Daily breakdown
+- `month` — Monthly aggregation (default)
+
+## Querying Analytics
+
+### All Posts Summary
+```
+Tool: li_get_analytics
+Params: {}
+```
+Returns aggregated statistics across all recent posts.
+
+### Specific Post
+```
+Tool: li_get_analytics
+Params: { "post_id": "urn:li:share:1234567890" }
+```
+
+## Performance Benchmarks (B2B)
+
+| Metric | Good | Excellent |
+|--------|------|-----------|
+| Engagement rate | 2-4% | >5% |
+| Click-through rate | 0.5-1% | >2% |
+| Impressions per post | 500-2000 | >5000 |
+| Comments per post | 3-10 | >20 |
+
+## Workflow: Post-and-Track
+
+1. Create post with `li_create_post`
+2. Wait 24-48 hours for meaningful data
+3. Check metrics with `li_get_analytics`
+4. Compare against benchmarks above
+5. Adjust content strategy based on engagement patterns
+
+## Listing Recent Posts
+
+```
+Tool: li_list_posts
+Params: { "count": 20 }
+```
+
+Returns posts with basic metrics for quick overview.

package/skills/wp-linkedin/references/linkedin-posting.md

@@ -0,0 +1,53 @@
+# LinkedIn Posting Guide
+
+## Feed Posts vs Articles
+
+| Feature | Feed Post (`li_create_post`) | Article (`li_create_article`) |
+|---------|-----|---------|
+| Length | Up to 3,000 chars | Unlimited (long-form) |
+| Format | Plain text + link/image | HTML body |
+| Use case | Quick updates, links, images | Blog-to-LinkedIn, thought leadership |
+| Engagement | Higher reach, lower depth | Lower reach, higher depth |
+| SEO | No | Yes (indexed by search engines) |
+
+## Creating Feed Posts
+
+### Basic Text Post
+```
+Tool: li_create_post
+Params: { "text": "Excited to share our latest blog post about...", "visibility": "PUBLIC" }
+```
+
+### Post with Link Share
+```
+Tool: li_create_post
+Params: { "text": "New article on our blog!", "link_url": "https://mysite.com/blog/post-slug", "visibility": "PUBLIC" }
+```
+
+LinkedIn automatically generates a link preview card with the page's Open Graph metadata.
+
+### Best Practices for Feed Posts
+- **First 2 lines matter** — LinkedIn truncates after ~210 characters with "...see more"
+- **Hashtags**: 3-5 relevant hashtags at the end
+- **Mentions**: Use LinkedIn mention syntax for company pages
+- **Emojis**: Use sparingly for visual breaks
+- **CTA**: Include a clear call-to-action
+
+## Publishing Articles
+
+### Blog-to-LinkedIn Workflow
+1. Fetch WordPress post: `wp_get_post` with `id`
+2. Extract: title, content (HTML), featured image URL
+3. Create article: `li_create_article` with title, body_html, thumbnail_url
+
+### Content Adaptation Tips
+- Remove WordPress-specific shortcodes from HTML
+- Ensure images use absolute URLs
+- Keep title under 100 characters
+- First paragraph should hook the reader
+- Add "Originally published on [site]" at the end
+
+## Visibility Settings
+
+- **PUBLIC** — Visible to all LinkedIn users (default)
+- **CONNECTIONS** — Visible only to your connections

package/skills/wp-linkedin/references/linkedin-setup.md

@@ -0,0 +1,59 @@
+# LinkedIn Setup Guide
+
+## Prerequisites
+
+- LinkedIn Developer account (https://www.linkedin.com/developers/)
+- WordPress site with WP REST Bridge configured
+- LinkedIn personal or company page
+
+## 1. Create LinkedIn Developer App
+
+1. Go to https://www.linkedin.com/developers/apps
+2. Click "Create app"
+3. Fill in: App name, LinkedIn Page, Privacy policy URL, App logo
+4. Under "Products", request access to **Community Management API**
+5. Wait for approval (usually instant for personal posting)
+
+## 2. Generate OAuth 2.0 Token
+
+### Required Scopes
+- `w_member_social` — Write access to post content
+- `r_liteprofile` — Read basic profile info
+- `openid` — OpenID Connect (for userinfo endpoint)
+
+### Token Generation
+1. In your LinkedIn app → Auth tab → OAuth 2.0 settings
+2. Add redirect URL: `https://localhost:8080/callback`
+3. Use the OAuth 2.0 authorization flow:
+   ```
+   https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope=w_member_social%20r_liteprofile%20openid
+   ```
+4. Exchange the authorization code for an access token
+5. Token expires in 60 days — set a reminder to refresh
+
+## 3. Configure WP_SITES_CONFIG
+
+Add to your site configuration:
+
+```json
+{
+  "id": "mysite",
+  "url": "https://mysite.com/wp-json/",
+  "username": "admin",
+  "password": "app-password",
+  "linkedin_access_token": "AQV...",
+  "linkedin_person_urn": "urn:li:person:ABC123"
+}
+```
+
+### Finding Your Person URN
+Use `li_get_profile` tool after configuring the access token. The `sub` field in the response contains your person URN.
+
+## 4. Verify Configuration
+
+Run the detection script:
+```bash
+node skills/wp-linkedin/scripts/linkedin_inspect.mjs
+```
+
+Expected output: `linkedin_configured: true` with indicators listing configured credentials.

package/skills/wp-linkedin/scripts/linkedin_inspect.mjs

@@ -0,0 +1,55 @@
+/**
+ * linkedin_inspect.mjs — Detect LinkedIn configuration readiness.
+ *
+ * Checks WP_SITES_CONFIG for LinkedIn credentials.
+ *
+ * Usage:
+ *   node linkedin_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — LinkedIn configuration found
+ *   1 — no LinkedIn configuration found
+ */
+
+import { stdout, exit, argv } from 'node:process';
+import { resolve } from 'node:path';
+
+function detectLinkedInConfig() {
+  const li = { configured: false, indicators: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return li;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return li; }
+  if (!Array.isArray(sites)) return li;
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    if (site.linkedin_access_token) {
+      li.configured = true;
+      li.indicators.push(`linkedin_access_token configured for ${label}`);
+    }
+    if (site.linkedin_person_urn) {
+      li.indicators.push(`linkedin_person_urn: ${site.linkedin_person_urn} for ${label}`);
+    }
+  }
+  return li;
+}
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const linkedin = detectLinkedInConfig();
+
+  const report = {
+    linkedin_configured: linkedin.configured,
+    linkedin,
+    cwd,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(linkedin.configured ? 0 : 1);
+}
+
+main();