---
name: linkedin-analytics
description: |
  Analyze LinkedIn content performance, import analytics data, generate reports, audit content
  strategy, and troubleshoot engagement issues. Covers the full analytics lifecycle from CSV
  import to actionable insights and recovery protocols.

  This skill should be used when the user wants to analyze post performance, import LinkedIn data exports,
  generate weekly reports, audit their content strategy, troubleshoot reach drops,
  or understand what's working and what isn't.

  Triggers on: "analyze my posts", "LinkedIn analytics", "weekly report", "import CSV",
  "what's working", "content audit", "why is my reach down", "LinkedIn troubleshooting",
  "performance report", "quarterly review", "engagement trends", "audit my linkedin",
  "low reach", "content not working", "reach dropped", "A/B test", "test different hooks",
  "compare post versions", "experiment with content".
---

## Analytics Domain

This skill covers everything related to LinkedIn analytics, performance measurement, reporting, troubleshooting, and content strategy auditing.

---

## Commands

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/linkedin:analyze` | Content/performance analysis | When content isn't performing |
| `/linkedin:audit` | Periodic content strategy audit | Quarterly reviews |
| `/linkedin:import` | Import CSV with auto-detect, quick-import, feedback loop | After downloading LinkedIn data or to start fresh import |
| `/linkedin:report` | Generate weekly performance report | Weekly check-ins |
| `/linkedin:ab-test` | Design and manage content A/B tests | Testing content variations |

## Agents

| Agent | Model | Responsibility |
|-------|-------|----------------|
| `analytics-interpreter` | Sonnet | Audience pattern analysis + weekly/monthly performance reports (interpret/report modes) |
| `trend-spotter` | (inherits session) | Trending topics + opportunity scores |
| `post-feedback-monitor` | Opus | Post-publish 48h monitoring, anomaly detection |

---

## Analytics System

### Architecture

Node.js CLI tool for parsing LinkedIn CSV exports into structured JSON.

**Location:** `scripts/analytics/`
**Data:** `${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/analytics/` (gitignored -- personal performance data)

**CLI usage:**
```bash
node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" import <file>
node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" report --week <W>
node --import tsx "${CLAUDE_PLUGIN_ROOT}/scripts/analytics/src/cli.ts" trends --period <P> --metric <M>
```

**Storage structure:**
```
${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/analytics/
+-- exports/           # Raw CSV from LinkedIn (drop files here)
+-- posts/             # Imported post data as JSON
+-- weekly-reports/    # Generated weekly reports
+-- README.md          # Import instructions
```

### Import Workflow Enhancements

The `/linkedin:import` command reduces friction with:

1. **Auto-detect from ~/Downloads** — Scans for recent LinkedIn CSV files in ~/Downloads before asking users to manually move files
2. **Quick-import helper** — `hooks/scripts/quick-import.mjs` opens LinkedIn Analytics in the browser and watches ~/Downloads for new CSV files (auto-copies on detection)
3. **Analytics-to-strategy feedback loop** — After import, automatically runs content pillar performance, format analysis, posting time analysis, and generates 3 data-driven recommendations
4. **State tracking** — Updates `last_import_date` and `last_import_week` in state file. Session-start and idle-prompt hooks show import staleness warnings.

### Data Freshness

The plugin tracks import freshness via `last_import_date` in the state file:

| Staleness | Status line | Reminders |
|-----------|-------------|-----------|
| Never imported | `Import: never` | "No analytics data imported yet" |
| <7 days | `Import: Xd ago` | None |
| 7-13 days | `Import: Xd ago` | "Consider /linkedin:import for fresh data" |
| 14+ days | `Import: Xd ago` | "Analytics data is stale. Strategy recommendations may be inaccurate" |

The `strategy-advisor` agent adds data confidence caveats based on import freshness.

---

## Troubleshooting: Performance Issues

### Quick Decision Tree

```
Is your reach down?
|
+-- Down <25%? --> Normal fluctuation, continue posting
+-- Down 25-50%? --> Review last week's posts, increase engagement
+-- Down 50-75%? --> Start 14-day recovery protocol
+-- Down 75%+? --> Full profile audit, check for violations
```

### Common Causes

1. **topic-relevance profile mismatch** -- Topic doesn't align with profile (see `references/algorithm-signals-reference.md`)
2. **External link reach effect** -- Links in the post body correlate with lower reach (see `references/algorithm-signals-reference.md`)
3. **Engagement drop** -- Not doing pre-post engagement (5x5x5 method)
4. **Topic inconsistency** -- Posting outside your established expertise areas
5. **Format fatigue** -- Same format every post, audience stops engaging

6. **Stale analytics data** — Strategy advice based on old data; run `/linkedin:import` for fresh data

For complete troubleshooting and recovery protocols, see `references/troubleshooting-guide.md`.

---

## Analytics Tools for Finding YOUR Edge

The mechanics in the main skill represent baseline knowledge. Your edge comes from discovering what works specifically for YOUR audience.

**Essential free tools:**
1. **LinkedIn Native Analytics** - Track weekly (15 min)
2. **Google Trends + Exploding Topics** - Catch emerging topics
3. **Reddit + Niche Communities** - Find real problems
4. **Personal Knowledge System** - Connect non-obvious dots
5. **Structured Experimentation** - Test hypotheses

For detailed tool guidance, see `references/analytics-tools-guide.md`.

---

## Content Audit Framework

### What to Review (Quarterly)

1. **Top performers** -- What topics, formats, hooks worked best?
2. **Bottom performers** -- What fell flat? Why?
3. **Topic distribution** -- Are you too narrow or too broad?
4. **Format mix** -- Matching 70/20/10 rule?
5. **Engagement quality** -- Comments vs. reactions ratio?
6. **Profile optimization** -- Still aligned with content themes?

### Key Metrics

| Metric | Good | Great | Exceptional |
|--------|------|-------|-------------|
| Impression rate (% of followers) | 10-20% | 20-40% | 40%+ |
| Engagement rate | 2-4% | 4-8% | 8%+ |
| Comment-to-reaction ratio | 1:10 | 1:5 | 1:3 |
| Profile views per post | 5-15 | 15-30 | 30+ |

---

## Common Patterns

**User: "Why isn't my content getting engagement?"**
1. Review recent posts for patterns
2. Check for algorithm penalty triggers
3. Assess first-hour engagement strategy
4. Evaluate topic consistency
5. Provide specific fixes from troubleshooting guide

**User: "What's working for me?"**
1. Import or review analytics data
2. Identify top-performing posts and patterns
3. Map patterns to content matrix
4. Recommend doubling down on winning formulas

---

## Reference Files

| File | When to Read |
|------|--------------|
| `references/algorithm-signals-reference.md` | Understanding algorithm behavior |
| `references/troubleshooting-guide.md` | When reach drops |
| `references/analytics-tools-guide.md` | Tool recommendations |
| `references/ab-testing-framework.md` | A/B testing methodology and tracking |
| `references/linkedin-growth-playbook-2025-2026.md` | Engagement benchmarks |
| `assets/checklists/quality-scorecard.md` | Quality standards reference |
