claude-plugin-wordpress-manager 2.9.0 → 2.12.0

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

@@ -0,0 +1,60 @@
+# Twitter Analytics Guide
+
+## Available Metrics
+
+Use `tw_get_metrics` to retrieve tweet performance data.
+
+### Public Metrics (Available to All)
+- **impression_count** — Times the tweet was shown in timelines
+- **like_count** — Number of likes
+- **retweet_count** — Number of retweets
+- **reply_count** — Number of replies
+- **quote_count** — Number of quote tweets
+- **bookmark_count** — Number of bookmarks
+
+## Querying Metrics
+
+### Single Tweet
+```
+Tool: tw_get_metrics
+Params: { "tweet_id": "1234567890" }
+```
+
+Returns tweet text, creation date, and all public metrics.
+
+### List Recent Tweets with Metrics
+```
+Tool: tw_list_tweets
+Params: { "count": 20 }
+```
+
+Returns recent tweets with basic metric data.
+
+### Tweets Since Date
+```
+Tool: tw_list_tweets
+Params: { "count": 50, "since": "2026-01-01T00:00:00Z" }
+```
+
+## Performance Benchmarks
+
+| Metric | Average | Good | Excellent |
+|--------|---------|------|-----------|
+| Engagement rate | 0.5-1% | 1-3% | >3% |
+| Like rate | 0.3-0.5% | 0.5-1% | >1% |
+| Retweet rate | 0.1-0.3% | 0.3-0.5% | >0.5% |
+| Reply rate | 0.05-0.1% | 0.1-0.3% | >0.3% |
+
+## Workflow: Tweet-and-Track
+
+1. Create tweet/thread with `tw_create_tweet` or `tw_create_thread`
+2. Note the returned tweet ID(s)
+3. Wait 24-48 hours for meaningful engagement data
+4. Check metrics with `tw_get_metrics`
+5. Compare against benchmarks above
+6. Adjust posting time, content style, and hashtag strategy
+
+## Thread Performance
+- Threads typically get 2-3x more engagement than single tweets
+- The first tweet drives 60-70% of total thread impressions
+- Include a "thread start" indicator to signal more content follows

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

@@ -0,0 +1,66 @@
+# Twitter Posting Guide
+
+## Single Tweets
+
+### Basic Tweet
+```
+Tool: tw_create_tweet
+Params: { "text": "Check out our latest blog post on WordPress optimization!" }
+```
+
+### Tweet with Reply (Thread Start)
+```
+Tool: tw_create_tweet
+Params: { "text": "First tweet text", "reply_to": "1234567890" }
+```
+
+### Character Limits
+- **Text**: 280 characters maximum
+- **URLs**: Count as 23 characters regardless of actual length
+- **Mentions**: Count toward character limit
+- **Media**: Does not count toward character limit
+
+### Best Practices
+- Front-load the value proposition in the first tweet
+- Use 1-3 relevant hashtags (not more)
+- Include a clear CTA when linking to blog content
+- Thread the needle: be concise yet compelling
+
+## Thread Creation
+
+### Automatic Thread from Blog Post
+```
+Tool: tw_create_thread
+Params: {
+  "tweets": [
+    "Thread: 5 ways to optimize your WordPress site for speed",
+    "1/ Enable caching. Use a caching plugin like WP Super Cache or W3 Total Cache.",
+    "2/ Optimize images. Compress and lazy-load all images.",
+    "3/ Minimize HTTP requests. Combine CSS and JS files where possible.",
+    "4/ Use a CDN. Distribute static assets globally for faster loading.",
+    "5/ Upgrade hosting. A good host makes all the difference."
+  ]
+}
+```
+
+### Thread Best Practices
+- Start with a hook that makes people want to read more
+- Each tweet should stand on its own while building the narrative
+- Number your tweets (1/, 2/, etc.) for easy reference
+- End with a summary or CTA tweet
+- Optimal thread length: 3-10 tweets
+
+### Blog-to-Thread Workflow
+1. Fetch WordPress post: `wp_get_post` with post ID
+2. Extract key points from content (H2 headings, key paragraphs)
+3. Craft hook tweet from title/excerpt
+4. Split key points into individual tweets (max 280 chars each)
+5. Add CTA tweet linking back to the full post
+6. Publish with `tw_create_thread`
+
+## Content Adaptation Tips
+- WordPress title → Hook tweet
+- H2 headings → Individual tweet topics
+- Key statistics/quotes → Standalone tweets
+- Featured image → First tweet media (via media upload)
+- Blog URL → CTA tweet link

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

@@ -0,0 +1,62 @@
+# Twitter/X Setup Guide
+
+## Prerequisites
+
+- Twitter Developer account (https://developer.twitter.com/)
+- WordPress site with WP REST Bridge configured
+- Twitter account for posting
+
+## 1. Create Twitter Developer App
+
+1. Go to https://developer.twitter.com/en/portal/dashboard
+2. Create a new Project and App
+3. Select "Free" or "Basic" tier (Free tier allows 1,500 tweets/month)
+4. Note your **API Key**, **API Secret**, and **Bearer Token**
+
+## 2. API Access Levels
+
+| Tier | Read | Write | Cost |
+|------|------|-------|------|
+| Free | Yes | 1,500 tweets/month | $0 |
+| Basic | Yes | 3,000 tweets/month | $100/month |
+| Pro | Yes | 300,000 tweets/month | $5,000/month |
+
+For most WordPress use cases, the Free tier is sufficient.
+
+## 3. Configure WP_SITES_CONFIG
+
+Add to your site configuration:
+
+```json
+{
+  "id": "mysite",
+  "url": "https://mysite.com/wp-json/",
+  "username": "admin",
+  "password": "app-password",
+  "twitter_bearer_token": "AAAA...",
+  "twitter_api_key": "abc123...",
+  "twitter_api_secret": "xyz789...",
+  "twitter_user_id": "1234567890"
+}
+```
+
+### Finding Your User ID
+1. Go to https://tweeterid.com/
+2. Enter your Twitter handle
+3. Copy the numeric user ID
+
+## 4. Verify Configuration
+
+Run the detection script:
+```bash
+node skills/wp-twitter/scripts/twitter_inspect.mjs
+```
+
+Expected output: `twitter_configured: true` with indicators listing configured credentials.
+
+## 5. Important Notes
+
+- Bearer tokens do not expire but can be regenerated
+- The `twitter_user_id` is required for `tw_list_tweets` (listing your tweets)
+- Rate limits apply per 15-minute window (varies by endpoint)
+- Tweet deletion triggers a safety hook requiring explicit confirmation

package/skills/wp-twitter/scripts/twitter_inspect.mjs

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