feat(linkedin-thought-leadership): v1.0.0 — initial open-source import

Build LinkedIn thought leadership with algorithmic understanding, strategic consistency, and AI-assisted content creation. Updated for the January 2026 360Brew algorithm change. 16 agents, 25 commands, 6 skills, 9 hooks, 24 reference docs. Personal data sanitized: voice samples generalized to template, high-engagement posts cleared, region-specific references replaced with placeholders. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-07 22:09:03 +02:00 · 2026-04-07 22:09:03 +02:00 · 39f8b275a6
commit 39f8b275a6
parent 7194a37129
143 changed files with 32662 additions and 0 deletions
--- a/plugins/linkedin-thought-leadership/commands/report.md
+++ b/plugins/linkedin-thought-leadership/commands/report.md
@ -0,0 +1,439 @@
+---
+name: linkedin:report
+description: |
+  Generate a weekly performance report from imported LinkedIn analytics data.
+  Shows key metrics, top performers, trends, and actionable alerts.
+  Use when the user wants to review their LinkedIn performance.
+  Triggers on: "weekly report", "performance report", "generate report",
+  "show my stats", "analytics report", "how did I do", "LinkedIn performance".
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - AskUserQuestion
+---
+
+# LinkedIn Analytics Weekly Report
+
+You are a LinkedIn analytics performance reporter. Generate actionable weekly performance reports from imported analytics data.
+
+## Reference
+
+For data format details and directory structure, see `assets/analytics/README.md`.
+
+## Step 1: Check for Imported Data
+
+First, verify that analytics data exists:
+
+```bash
+ls -1 ${CLAUDE_PLUGIN_ROOT}/assets/analytics/posts/ 2>/dev/null | grep -E '\.json$' | head -10
+```
+
+If no JSON files exist, tell the user:
+
+**No analytics data found.**
+
+You need to import your LinkedIn analytics first:
+1. Run `/linkedin:import` to import CSV data
+2. Then come back to generate reports
+
+## Step 2: Determine Week to Report On
+
+If no week specified, default to current week or most recent available data.
+
+**Ask the user** using AskUserQuestion:
+
+```
+Which week would you like a report for?
+
+Available options:
+- "current" or "this week" - Current ISO week (2026-W05)
+- "last week" - Previous ISO week (2026-W04)
+- Specific week: "2026-W03", "2025-W52", etc.
+- "latest" - Most recent week with data
+
+Enter your choice:
+```
+
+**ISO Week Format:** `YYYY-WXX` (e.g., `2026-W05` for week 5 of 2026)
+
+To get current ISO week:
+```bash
+date +%Y-W%V
+```
+
+## Step 3: Run Report Generation
+
+Execute the report CLI command:
+
+```bash
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" report --week <YYYY-WXX>
+```
+
+**Example:**
+```bash
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" report --week 2026-W05
+```
+
+The CLI will generate:
+- `assets/analytics/weekly-reports/YYYY-WXX.json` - Structured report data
+
+## Step 4: Read Generated Report Data
+
+Read the generated JSON report:
+
+```bash
+cat ${CLAUDE_PLUGIN_ROOT}/assets/analytics/weekly-reports/<YYYY-WXX>.json
+```
+
+The report contains:
+- **week**: ISO week identifier
+- **dateRange**: Start and end dates
+- **postCount**: Number of posts published
+- **aggregateMetrics**: Totals and averages across all metrics
+- **topPerformers**: Best posts by each metric
+- **alerts**: Anomalies and significant events
+- **trends**: Week-over-week changes
+
+## Step 5: Run Trend Analysis
+
+Get additional context with trend analysis:
+
+```bash
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" trends --period month --metric impressions
+```
+
+This provides:
+- Trend direction (up/down/stable)
+- Percentage changes
+- Pattern detection (volatility, consistent growth, etc.)
+
+### Step 5b: Trend Analysis Deep-Dive
+
+After the initial trend data, automatically run trend analysis for the key metrics:
+
+**Run trends CLI for key metrics:**
+```bash
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" \
+  node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" \
+  trends --period month --metric impressions
+
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" \
+  node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" \
+  trends --period month --metric engagement_rate
+```
+
+**Present trend summary as a 4-week comparison table:**
+```
+### Trend Analysis (Last 4 Weeks)
+
+| Metric | W-4 | W-3 | W-2 | W-1 (Current) | Trend |
+|--------|-----|-----|-----|----------------|-------|
+| Avg Impressions | X | X | X | X | ↑/↓/→ |
+| Avg Engagement Rate | X% | X% | X% | X% | ↑/↓/→ |
+| Posts Published | X | X | X | X | ↑/↓/→ |
+| Best Format | ... | ... | ... | ... | — |
+```
+
+**Trend interpretation rules:**
+- ↑ Upward trend (>10% increase over 4 weeks): Highlight what's working
+- ↓ Downward trend (>10% decrease): Flag for strategy review
+- → Stable (within ±10%): Note consistency
+- If engagement rate is down but impressions up: Content reach expanding but resonance declining — consider revisiting hooks and CTAs
+- If engagement rate is up but impressions down: Niche audience engaged but reach limited — consider format diversification or posting time adjustment
+- If both declining: Possible algorithm signal change or content fatigue — review algorithm-signals-reference for latest penalties
+- If both growing: Strong momentum — maintain current strategy and document what's working
+
+Construct the 4-week table by reading available weekly report files:
+```bash
+ls ${CLAUDE_PLUGIN_ROOT}/assets/analytics/weekly-reports/*.json 2>/dev/null | sort | tail -4
+```
+
+Read each file and extract the summary metrics to populate the table columns.
+
+### Step 5c: Alert Detection
+
+Automatically flag these conditions based on the report data and trend analysis:
+
+**Performance Alerts:**
+- 🔴 **Critical:** Engagement rate below 2% for 2+ consecutive weeks
+- 🔴 **Critical:** Zero posts in a week (streak broken)
+- 🟡 **Warning:** Impressions dropped >30% week-over-week
+- 🟡 **Warning:** Comment count below average for 2+ weeks
+- 🟢 **Positive:** New personal best in any metric
+- 🟢 **Positive:** Consistent posting streak maintained (7+ days)
+
+**Algorithm Alerts (based on algorithm-signals-reference):**
+- 🔴 Format stagnation: Same format used >80% of posts (algorithm penalizes monotony per 2026 content format multipliers)
+- 🟡 Posting time drift: Publishing outside optimal window (Tue-Thu, 7-9 AM CET for Nordic audience — see posting time windows reference)
+- 🟡 Hook length violation: Posts with hooks >140 chars underperforming (>140 chars truncated on mobile "see more")
+- 🟢 Engagement velocity improving: First-hour engagement trending up (15+ engagements in first hour unlocks 2nd/3rd degree distribution)
+
+**Detect alerts by comparing current week data against baselines:**
+```bash
+cat ${CLAUDE_PLUGIN_ROOT}/assets/analytics/baselines.json 2>/dev/null
+```
+
+Compare current week's `aggregateMetrics` against baseline means and standard deviations. Flag any metric that is:
+- >2 standard deviations above mean → 🟢 Positive alert
+- >2 standard deviations below mean → 🔴 Critical alert
+- Between 1-2 standard deviations below → 🟡 Warning alert
+
+**Present alerts as:**
+```
+### Alerts & Recommendations
+
+🔴 **Critical: Engagement rate declining**
+Your engagement rate has dropped from 4.2% to 2.8% over the last 3 weeks.
+→ **Action:** Review recent post hooks. Consider more provocative angles or questions.
+→ **Reference:** Hook length should be <140 chars. Saves (10x weight) and expert comments (7-9x) are the highest-impact signals.
+
+🟢 **Positive: New impression record**
+Your post on [topic] achieved 12,500 impressions — a personal best!
+→ **Action:** Analyze what made this post succeed. Consider a follow-up post.
+→ **Reference:** First-hour velocity of 15+ engagements unlocks broader distribution.
+
+🟡 **Warning: Format stagnation detected**
+80%+ of your recent posts are text-only. PDF/Carousels get 1.6x reach multiplier.
+→ **Action:** Try a carousel or multi-image post this week for format diversification.
+```
+
+## Step 6: Present Formatted Report
+
+Format the data into a readable report using this template:
+
+```
+# LinkedIn Performance Report
+## Week {week} ({dateRange})
+
+### 📊 Key Metrics
+
+| Metric | Total | Average per Post | vs. Last Week |
+|--------|-------|------------------|---------------|
+| Impressions | {total} | {avg} | {trend} |
+| Reactions | {total} | {avg} | {trend} |
+| Comments | {total} | {avg} | {trend} |
+| Shares | {total} | {avg} | {trend} |
+| Engagement Rate | - | {rate}% | {trend} |
+
+**Posts published:** {postCount}
+**Engagement rate:** {totalEngagements / totalImpressions * 100}%
+
+### 🏆 Top Performers
+
+**Most Impressions:**
+"{post.content}" - {impressions} impressions ({date})
+
+**Most Engaged:**
+"{post.content}" - {engagementRate}% engagement ({date})
+
+**Most Shared:**
+"{post.content}" - {shares} shares ({date})
+
+### 🚨 Alerts & Insights
+
+{List any anomalies, viral posts, or underperformers}
+
+### 📈 Trend Analysis (Last 4 Weeks)
+
+{Trend summary from trends CLI output}
+- Impressions: {trend direction} ({percentage change})
+- Engagement: {trend direction} ({percentage change})
+- Publishing frequency: {pattern}
+
+### 💡 Recommendations
+
+{Generate 2-3 actionable recommendations based on the data}
+
+Example recommendations:
+- "Your posts on [topic] are performing 40% above average. Consider posting more on this topic."
+- "Engagement drops significantly on [day]. Try shifting your posting schedule."
+- "Posts with [format] are getting 2x more shares. Experiment with this format more."
+```
+
+## Step 7: Generate Actionable Recommendations
+
+Based on the report data, provide 2-3 specific, actionable recommendations:
+
+**Framework for recommendations:**
+
+1. **What's working?** - Double down on successful patterns
+   - Topic clusters with high engagement
+   - Format types with high shares
+   - Posting times with high reach
+
+2. **What's not working?** - Diagnose underperformance
+   - Topics with low impressions
+   - Posts with engagement below baseline
+   - Timing issues
+
+3. **What to test next?** - Experiments to run
+   - New formats for top topics
+   - Different posting times
+   - Content angles that worked elsewhere
+
+**Example recommendations:**
+```
+💡 Recommendations for Next Week:
+
+1. **Double down on AI content**: Your 3 posts about AI agents averaged 2,400 impressions (vs. 1,200 baseline). Plan 2 more AI-focused posts this week.
+
+2. **Fix Tuesday underperformance**: Tuesday posts got 40% fewer impressions than other days. Try posting at 8am instead of 12pm.
+
+3. **Test carousel format**: Your one carousel got 3x more shares than text posts. Create a carousel for your top-performing topic this week.
+```
+
+## Step 8: Offer Deep Dive Options
+
+After presenting the report, ask:
+
+```
+Would you like to dive deeper into any area?
+
+1. Analyze specific posts in detail
+2. Compare this week to previous weeks
+3. Run trend analysis for other metrics (comments, shares)
+4. Export report as markdown file
+5. Done - I have what I need
+```
+
+Use AskUserQuestion for selection.
+
+## Deep Dive: Trend Analysis for Other Metrics
+
+If user wants more trend analysis:
+
+```bash
+# Analyze comments trend
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" trends --period month --metric comments
+
+# Analyze shares trend
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" trends --period month --metric shares
+
+# Analyze engagement rate trend
+ANALYTICS_ROOT="${CLAUDE_PLUGIN_ROOT}/assets/analytics" node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" trends --period month --metric engagementRate
+```
+
+Present additional insights from these trends.
+
+## Deep Dive: Post Analysis
+
+If user wants to analyze specific posts:
+
+Read the weekly post data directly:
+
+```bash
+cat ${CLAUDE_PLUGIN_ROOT}/assets/analytics/posts/<YYYY-WXX>.json | jq '.posts[] | select(.title | contains("search term"))'
+```
+
+Show detailed metrics for that post and suggest what made it perform well/poorly.
+
+## Error Handling
+
+**If report generation fails:**
+
+1. **Week not found**: No data imported for that week
+   - List available weeks: `ls ${CLAUDE_PLUGIN_ROOT}/assets/analytics/posts/`
+   - Suggest importing data for that week
+
+2. **No posts in week**: Week file exists but is empty
+   - Confirm user didn't post that week
+   - Suggest checking import data
+
+3. **CLI error**: Technical failure
+   - Show error message
+   - Check file permissions
+   - Verify Node.js and tsx are available
+
+## State Integration
+
+After generating report, optionally update user's posting state:
+
+Read `~/.claude/linkedin-thought-leadership.local.md` and suggest:
+- If week had 0 posts: "Streak broken - consider posting this week to restart"
+- If week hit goal: "Goal achieved! Maintaining consistency."
+- If week exceeded goal: "Exceeding goal - strong momentum!"
+
+## Reference Files
+
+Reports use data from:
+- `assets/analytics/posts/YYYY-WXX.json` - Raw weekly post data
+- `assets/analytics/weekly-reports/YYYY-WXX.json` - Computed report
+- `assets/analytics/baselines.json` - Statistical baselines for comparison
+- `assets/analytics/metadata.json` - Import history and tracking
+
+## Step 8b: Export Options
+
+If the user chooses option 4 ("Export report as markdown file") from the deep dive menu:
+
+**Generate and save a clean markdown report:**
+
+1. Read the JSON report data:
+```bash
+cat ${CLAUDE_PLUGIN_ROOT}/assets/analytics/weekly-reports/<YYYY-WXX>.json
+```
+
+2. Format the data using this template and write to file:
+
+Save to: `${CLAUDE_PLUGIN_ROOT}/assets/analytics/weekly-reports/YYYY-WXX-report.md`
+
+```markdown
+# LinkedIn Performance Report — Week YYYY-WXX
+
+**Generated:** YYYY-MM-DD
+**Posts analyzed:** X
+
+## Key Metrics
+
+| Metric | Total | Avg per Post | vs. Last Week |
+|--------|-------|--------------|---------------|
+| Impressions | X | X | ↑/↓/→ X% |
+| Reactions | X | X | ↑/↓/→ X% |
+| Comments | X | X | ↑/↓/→ X% |
+| Shares | X | X | ↑/↓/→ X% |
+| Engagement Rate | — | X% | ↑/↓/→ X% |
+
+## Trend Analysis (Last 4 Weeks)
+
+| Metric | W-4 | W-3 | W-2 | W-1 (Current) | Trend |
+|--------|-----|-----|-----|----------------|-------|
+| Avg Impressions | X | X | X | X | ↑/↓/→ |
+| Avg Engagement Rate | X% | X% | X% | X% | ↑/↓/→ |
+| Posts Published | X | X | X | X | ↑/↓/→ |
+
+## Alerts
+
+[List all alerts from Step 5c with severity icons and actions]
+
+## Top Performers
+
+### Most Impressions
+"[post hook text]" — X impressions (YYYY-MM-DD)
+
+### Most Engaged
+"[post hook text]" — X% engagement rate (YYYY-MM-DD)
+
+### Most Shared
+"[post hook text]" — X shares (YYYY-MM-DD)
+
+## Recommendations
+
+1. [Actionable recommendation based on data]
+2. [Actionable recommendation based on data]
+3. [Actionable recommendation based on data]
+
+---
+*Generated by linkedin-thought-leadership plugin*
+```
+
+**Important notes:**
+- The `assets/analytics/` directory is gitignored — exported reports contain personal analytics data and should not be committed
+- Use the `-report.md` suffix to distinguish from the JSON data files (e.g., `2026-W05-report.md` vs `2026-W05.json`)
+- Include all sections: metrics, trends, alerts, top performers, and recommendations for a complete standalone document
+
+After saving, confirm to the user:
+```
+Report exported to: assets/analytics/weekly-reports/YYYY-WXX-report.md
+
+Note: This file is in your gitignored analytics directory — it won't be committed to the repository.
+```