linkedin-performance-agent
LinkedIn-specialised performance agent. Extends performance-marketing-agent with LinkedIn algorithm behaviour, feed mechanics, content format signals, and CSV export parsing. Called by linkedin-growth
SKILL.md.claude/skills/linkedin-performance-agent/SKILL.md
GitHub/linkedin-performance-agent
Extends performance-marketing-agent with LinkedIn-specific platform knowledge. Everything in the base agent applies here. This file adds the LinkedIn layer on top.
Reach is not capture (read this before any verdict)
Impressions and engagement rate cannot tell a breakout from rented reach. Period 3 (2026-08) produced the account's largest post ever — 6,387 impressions, 4,113 members reached — and zero followers. The aggregate export reported it as a +123% period. It was a −62% period once the outlier was removed.
Two metrics carry this. Compute both on every post that has single-post data:
| Metric | Formula |
|---|---|
| Capture rate | Followers gained / Members reached × 100 |
| Profile view rate | Profile viewers from post / Impressions × 100 |
| Capture rate | Verdict |
|---|---|
| > 0.5% | Strong — reach is building the account |
| 0.1–0.5% | Average |
| < 0.1% | Rented reach — the post performed for LinkedIn, not for the creator |
Rule: a post is a win only if it clears BOTH the engagement-rate tier AND the capture-rate tier. Never report high impressions as success without stating capture. When capture data is unavailable, say so explicitly rather than implying the reach was valuable.
Corollary for period totals: if one post is more than ~40% of a period's impressions, always report the period twice — with and without it. The ex-outlier figure is the account's real trajectory.
LinkedIn algorithm signals (what the base agent doesn't know)
Early engagement velocity
LinkedIn's algorithm weights engagement in the first 60–90 minutes heavily. A post that gets 5 comments in the first hour will outreach a post that gets 20 comments after 6 hours. When analysing performance, note if the post was shared at a high-traffic time (Tue–Thu, 8–10am or 12–1pm in the creator's timezone).
Dwell time
LinkedIn measures how long people pause on a post (dwell time). Long-form posts that people read fully signal quality to the algorithm. This is why line-break formatting and short paragraphs matter — they increase scroll depth and dwell time. Short posts that get scrolled past quickly suppress reach even with high reaction counts.
Comment-to-impression ratio
This is the most powerful organic reach signal on LinkedIn. A post with a 0.5% comment rate will be distributed far more broadly than one with a 5% reaction rate but 0.1% comment rate. Always surface this ratio in verdicts.
Comment rate = Comments / Impressions × 100
| Comment rate | LinkedIn signal |
|---|---|
| >0.5% | Strong — algorithm amplifies |
| 0.2–0.5% | Average |
| <0.2% | Weak — limited distribution |
Connection depth
LinkedIn distributes to 1st connections first, then 2nd-degree. Posts that trigger engagement from diverse industries (not just your immediate network) signal broad relevance and get pushed further. Can't measure this from CSV — note it qualitatively when visible.
Hashtag reach
3–5 hashtags is optimal. More suppresses reach. Niche hashtags (#ClaudeCode) surface the post to followers of that tag. Generic hashtags (#AI) add noise, not reach. Track hashtag patterns across top-performing posts.
LinkedIn-specific content formats
| Format | Algorithm treatment | Best for |
|---|---|---|
| Text-only | Highest organic reach — no external link suppression | Opinion, insight, personal story |
| Single image | Good reach — pauses scroll | Data visualisation, quote cards, infographics |
| Meme / humour image | Very high reach, very low capture | Top-of-funnel only — see below |
| Carousel (PDF) | High dwell time — strong reach signal | Step-by-step, listicles, frameworks |
| Video (native) | Boosted by algorithm | Demos, walkthroughs, talking head |
| External link in post | Suppressed reach (~30–50%) | Avoid in main post — put links in first comment |
| Newsletter | Separate distribution — not feed reach | Long-form evergreen |
Key rule: If the post links to an external URL, move the link to the first comment. Post body should be link-free to avoid suppression. Track whether posts with external links underperform in the data.
Meme / humour posts — measured behaviour on this account
One data point (2026-08-09), but a decisive one. Treat it as the working model until contradicted:
- Delivered ~23× the impressions of a same-period text post at ~1/6th the engagement rate and 0.00% capture
- Distribution went to non-followers, skewed younger and student-heavy than the follower base (Entry 32% vs Senior 24%, inverted), and into locations absent from the audience profile
- 97% of engagement was reactions. 0 reposts, 0 saves, 1 comment
Never grade a meme on engagement rate. It will always look weak. Grade it on capture rate and reposts.
Diagnostic when a meme reaches wide but captures nothing: the post carried no bridge back to the author — nothing signalling what the creator does, so laughter gave the stranger no reason to follow. Check for: a fixed visual signature, one converting caption line, and a shared enemy rather than observational humour.
Demographics warning: when a single humour post dominates a period, the aggregate CONTENT DEMOGRAPHICS sheet becomes ~100% that post. It describes who a meme reaches, not who the account reaches. Never write it into the Audience Profile as an audience shift — always reconcile against the AUDIENCE DEMOGRAPHICS sheet, which is follower-based.
LinkedIn engagement types (beyond base agent)
| LinkedIn reaction | What it signals |
|---|---|
| Like | Neutral agreement |
| Celebrate | Achievement / milestone content |
| Support | Vulnerability / struggle content |
| Funny | Humour / relatable content |
| Love | Strong emotional resonance |
| Insightful | Educational / data-driven content |
| Curious | Question-posing / thought-provoking content |
Reaction type breakdown is visible in LinkedIn analytics but not in the CSV export. When recording manually, note the dominant reaction type — it signals content tone alignment.
LinkedIn CSV export — parsing spec
How to export: linkedin.com/analytics/creator/ → select date range → Export button (Creator Mode required). See performance/HOWTO.md for full steps.
LinkedIn exports .xlsx (Aggregate Analytics), not a flat CSV. The file is named AggregateAnalytics_<Name>_<start>_<end>.xlsx. Read it with python3 + openpyxl via a venv (pandas may not be available). When openpyxl is not installed: python3 -m venv /tmp/xlvenv && /tmp/xlvenv/bin/pip install openpyxl -q.
XLSX structure — 5 sheets
| Sheet | What it contains | What to extract |
|---|---|---|
DISCOVERY |
Overall impressions + members reached for the period | Account-level totals for tracker benchmarks |
ENGAGEMENT |
Daily totals: Date · Impressions · Engagements | Trend data — not per post |
TOP POSTS |
Per-post rows: URL · Publish Date · Engagements · Impressions (two side-by-side tables — one sorted by engagements, one by impressions) | Primary source for per-post matching |
FOLLOWERS |
Total followers + daily new follower counts | Audience growth signal |
DEMOGRAPHICS |
Company · Location · Seniority · Job title · Industry breakdowns | Audience profile for Strategist context |
Per-post matching (from TOP POSTS sheet)
The TOP POSTS sheet has two side-by-side tables. Read both — they contain the same posts sorted differently. Extract unique rows by URL.
Available per-post fields:
Post URL— use to confirm match and record inperformance.mdPost Publish Date— match toposts/<slug>-YYYYMMDD/folder dateEngagements— total (reactions + comments + reposts + clicks combined — no breakdown)Impressions— total feed appearances
Engagement rate = Engagements / Impressions × 100 (calculate it — not provided in export)
Matching logic:
- Extract publish date from TOP POSTS row
- Find
posts/<slug>-YYYYMMDD/where YYYYMMDD matches the publish date - If multiple folders share a date: read
final-post.mdopening lines and compare to URL hashtags for confirmation - If no folder matches the date: log as unmatched in tracker.md — the post exists on LinkedIn but was not generated by this factory
What's NOT available in this export: reactions vs. comments vs. reposts breakdown, saves, followers gained, profile views, comment content, dwell time. For any of that, use the single-post export below.
Attribution safety — do not match on date alone. The 2026-08 import misattributed a 6,387-impression post to a carousel that was never published, purely because both carried the same date. The URL slug is the tiebreaker, and its shape is informative:
| URL slug shape | Means |
|---|---|
_<hashtag>-<hashtag>-share-<id> |
Post had hashtags — match them against the post's ## Hashtags |
_share-<id> with no words |
No hashtags detected. Could be a bare image, a document, or an off-pipeline post. Do NOT assume it is a factory post. |
_ugcPost-<id> |
Older post type |
When the slug carries no hashtags and more than one candidate exists for the date, stop and ask the user which post it is. Log it as unresolved rather than guessing. A wrong attribution poisons every downstream pattern.
Publish verification (run on every import). For each posts/<slug>-<date>/ folder containing a final-post.md, check whether it appears anywhere in the TOP POSTS impressions table. The table lists posts down to a single impression, so absence is strong evidence the post was never published, not evidence it underperformed.
Write anything absent into a ## Unshipped register section in tracker.md with its finish date. The 2026-08 import found four finished posts with zero LinkedIn record. Surface this prominently — unshipped inventory is a higher-priority finding than any pattern insight, because generation is not the bottleneck when finished posts are sitting idle.
Cadence check (run on every import). From the ENGAGEMENT sheet, find the longest run of days with no new post in TOP POSTS, and report the daily impression floor during it. On this account the floor is ~5/day within a week of silence, meaning there is no residual distribution to coast on. Report publishing frequency as a first-class finding alongside content patterns.
Single-post export — parsing spec
How to export: open the post on LinkedIn → View analytics → Export. File is named SinglePostAnalytics_<Name>_<postId>.xlsx, one sheet, Post analytics.
Pull this for every post above ~1,000 impressions. The aggregate export cannot distinguish a breakout from rented reach.
Structure — one sheet, key/value rows then a demographics block
| Row group | Fields |
|---|---|
| Header | Post URL, Post Date, Post Publish Time |
| Discovery | Impressions, Members reached |
| Profile activity | Profile viewers from this post, Followers gained from this post |
| Engagement | Social engagements, Reactions, Comments, Reposts, Saves, Sends on LinkedIn, Link engagements, Premium custom button engagements |
| Post viewer demographics | Category · Value · % rows — Job title, Location, Seniority, Company, Industry, Company size |
Parse as key/value until the row reading Post viewer demographics, then switch to three-column table mode.
What to compute
- Engagement rate = aggregate
Engagements/Impressions× 100 (prefer the aggregate figure for continuity with older rows) - Comment rate =
Comments/Impressions× 100 - Capture rate =
Followers gained/Members reached× 100 - Profile view rate =
Profile viewers/Impressions× 100 - Impressions per member =
Impressions/Members reached— near 1.0 means broad cold distribution, one look each; higher means repeat exposure inside a warm network - Reaction share =
Reactions/Social engagements— above ~90% means passive consumption, no conversation - Aggregate vs post-level gap = aggregate
Engagements−Social engagements. Most likely image/document clicks, which the aggregate folds in and the post-level sheet does not itemise. Report as inference, never as a reported field.
Reconciling the two exports
The post-level Social engagements will usually be lower than the aggregate Engagements for the same post. This is expected, not an error. Log both, use the aggregate for the tracker's Eng. Rate column so periods stay comparable, and note the delta.
Follower attribution
Followers gained from this post is authoritative and often contradicts the FOLLOWERS sheet. In the 2026-08 import the aggregate showed +3 followers across the two days a 6,387-impression post ran, while the post itself reported 0. The followers came from elsewhere. Never attribute daily follower movement to a post without this field.
Demographics extraction
Read the DEMOGRAPHICS sheet and write or update the ## Audience Profile section in tracker.md. Update this section on every import — audience composition shifts as the account grows.
Column name variations
LinkedIn occasionally renames headers between export versions. If an expected column is missing, scan the first row for the closest match. Never fail silently — log unresolvable columns in tracker.md under ## Import Notes.
Matching logic (post folder ↔ CSV row):
- Match
Date publishedto the date inposts/<slug>-YYYYMMDD/ - If multiple posts share a date: match first 80 chars of
Contentagainstfinal-post.mdopening lines - If still ambiguous: log as unmatched, ask the user to confirm
LinkedIn-specific Pattern Summary additions
Extend the base Pattern Summary with these LinkedIn-specific sections:
### Format performance
| Format | Posts | Avg impressions | Avg eng. rate | Capture | What it buys |
|---|---|---|---|---|---|
| Text + image | | | | | |
| Text-only | | | | | |
| Meme / humour | | | | | |
| Carousel | | | | | |
State the trade explicitly in one line: what the reach format costs in conversion, quantified.
### Cadence
- Posts published this period: <N> in <days> days
- Longest silence: <N> days (<start> to <end>)
- Daily impression floor during silence: <N>/day
- Verdict: <is cadence or content the binding constraint this period?>
### Unshipped register
| Post folder | Finished | Status |
|---|---|---|
<any final-post.md with zero LinkedIn record>
### LinkedIn algorithm signals
- **Best comment rate:** <slug> at <X>% (Comments / Impressions) — this post got the most algorithmic boost
- **Best capture rate:** <slug> at <X>% (Followers gained / Members reached) — this post actually grew the account
- **Link-in-post tax:** posts with external links averaged <X>% vs. link-free posts at <Y>% (evidence of suppression)
- **Hashtag pattern on top posts:** <list the hashtags used on the 2 strongest posts>
- **Posting time pattern:** <if visible — day/time of top-performing posts>
### Reaction quality signal
- Dominant reaction on top posts: <Insightful / Like / Celebrate / etc.> — signals audience is reading as <educational / professional milestone / etc.> content
- Reaction share: <Reactions / Social engagements> — above ~90% means passive consumption, no conversation
- Comment-to-reaction ratio on top posts: <ratio> — <high = comments dominate = strong algorithm signal / low = passive engagement>
Account-level facts established 2026-08 — carry these forward until contradicted:
- LinkedIn Premium is NOT an amplifier on this account. Pre-Premium posts ranged 384–848 impressions; post-Premium text posts landed at 291–320. Do not attribute reach swings to Premium. This supersedes the earlier "expect a distribution lift" note.
- Format beats Premium beats angle for raw reach. Angle still governs conversion.
- Publishing gaps have no floor cushion — reach decays to ~5 impressions/day within a week of silence.
LinkedIn-specific verdict additions
Add to the base agent verdict block:
**Engagement rate:** <X>% — <weak / average / strong>
**Comment rate:** <Comments / Impressions × 100>% — <above/below the 0.2% threshold>
**Capture rate:** <Followers gained / Members reached × 100>% — <strong / average / RENTED REACH>
**Format used:** text-only / single image / meme / carousel / video
**Link in post body?:** yes (reach suppressed) / no
**Dominant engagement:** <reactions X% of all actions>
**Algorithm assessment:** <likely amplified / average distribution / likely suppressed — with reason>
**What worked:** <the mechanism, not the metric>
**What failed:** <the mechanism, not the metric>
**Fix for next time:** <numbered, specific, actionable>
Verdict discipline. Name the mechanism, not the number. "0 followers from 4,113 strangers because the post carried no signal of what the author builds" is a finding. "Low capture rate" is a restatement. If a post reached wide and captured nothing, the verdict must answer: what would have given a stranger a reason to stay?
LinkedIn-specific recommendations
Add to the base agent recommendations:
- If comment rate is consistently below 0.2%: the CTA is not generating discussion — test open questions instead of directional CTAs
- If image posts underperform text-only: the image may be interrupting the hook — test leading with text, image as supporting element
- If engagement rate is high but comments are low: the post is getting reactions but not conversation — reframe the topic as a question or debate
- If posts with external links underperform: enforce first-comment link discipline — never put URLs in the post body
- If early posts (first 3) show no pattern yet: note "insufficient data — 3 more posts needed before patterns are reliable"
- If the unshipped register is non-empty: lead the recommendations with it. Shipping finished inventory outranks every content pattern. Generation is not the bottleneck when completed posts have zero impressions.
- If a post has high impressions and capture below 0.1%: do not recommend "do more of this." Recommend the bridge — visual signature, converting caption line, shared enemy over observational humour — plus sequencing a conversion post within 24–48h while the cold audience is still in distribution
- If a reach format is working: recommend budgeting it (roughly 1 in 4–5 posts), never displacing the formats that convert
- If a period's impressions are dominated by one post: report the period with and without it, and state which is the real trajectory
Output files
Same as base agent:
posts/<slug>-<date>/performance.md— per-post verdictperformance/tracker.md— rolling ledger + Pattern Summary
LinkedIn Performance Agent writes the LinkedIn-specific additions on top of what the base agent would write. The output is one performance.md and one tracker.md — not separate files.