linkedin_skills/README.md

# LinkedIn Outreach Skills for Claude Code

**AI-powered LinkedIn lead filtering, first-touch drafting, and reply handling — runs entirely inside Claude Code.**

Built for B2B founders, sales teams, and growth operators who do outbound on LinkedIn and want a repeatable, signal-driven system — without paying for a bloated sales tool.

---

## What this does

You give it a CSV of LinkedIn leads. It filters, scores, drafts first-touch messages in your voice, handles replies, and tells you what to fix after each campaign.

Everything runs as [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code) — your AI handles the filtering, drafting, and reply logic. Bring your own leads, or use [linkednav.com](https://www.linkednav.com) to source warm leads from your LinkedIn activity.

```
/onboard           → analyze your product, set your ICP
/calibrate-voice   → build your writing style guide
/linkedin-lead-filter → score and bucket your leads
/draft-outreach    → write first-touch messages, signal-first
/reply-handler     → classify and draft replies
/campaign-retro    → diagnose what to fix after a campaign
```

---

## Who this is for

- **B2B founders** doing outbound themselves
- **Sales reps and SDRs** who want better personalization without more tools
- **Growth operators** running LinkedIn campaigns at small-to-medium scale
- Anyone who has tried LinkedIn outreach and found their reply rates too low

---

## Requirements

- **[Claude Code](https://claude.ai/code)** — the only hard requirement
- **Node.js 18+** — optional. If installed, file processing is faster. If not, Claude handles everything directly.

---

## Quickstart

```bash
git clone https://github.com/xx254/linkedin_skills
cd linkedin_skills
bash setup
```

Then open the folder in Claude Code and run:
```
/onboard
```

That's it. `/onboard` analyzes your product, suggests your ICP, and saves your settings. All other skills are ready to use after that.

---

## Skills — recommended order

```
/onboard → /calibrate-voice → /linkedin-lead-filter → /draft-outreach → /reply-handler → /campaign-retro
```

Every skill can be run independently. The only hard dependency: `/linkedin-lead-filter` requires `/onboard` to have been completed first. Everything else just works better with more context — it's not a blocker.

| Skill | What it does | Input | Output | Run alone? |
|-------|-------------|-------|--------|-----------|
| `/onboard` | Analyzes your landing page, suggests your ICP, asks you to confirm or adjust, then saves your settings. Run once. | Your landing page URL | `state/linkedin-settings.json`, `context/about-me.md` | ✅ Start here |
| `/calibrate-voice` | Builds a writing style guide from your real messages (or a preset). Every draft skill follows this guide. Re-run when reply rates drop or your style shifts. | Paste real messages you've written, or pick a style archetype | `context/brand-voice.md` | ✅ Only needs your messages or a style choice |
| `/linkedin-lead-filter` | Scores and buckets a CSV of LinkedIn leads against your ICP. Produces qualified/disqualified files and a canonical lead registry for downstream use. | CSV file path or pasted CSV content | `output/leads_<date>/` — categorized CSVs + `lead_registry_<date>.json` | ✅ Requires `/onboard` first |
| `/draft-outreach` | Drafts a first-touch LinkedIn connection request for a lead. Signal-first, no pitch. Can take a lead from the filter registry or a name/company/title you type directly. | Registry path + lead key, **or** name / company / title / LinkedIn URL directly | `output/outreach_<date>/draft_<lead>_<date>.json` — draft + variant | ✅ No prior filter run needed |
| `/reply-handler` | Classifies a prospect's reply (interested, hesitant, not interested, etc.) and drafts a contextual response. One question per message, no repositioning as a pitch. | Paste the prospect's message | Reply draft + classification + next-step strategy | ✅ Most standalone skill |
| `/campaign-retro` | Diagnoses which lever is broken (targeting, voice, or reply handling) and outputs a precise fix list. Updates `brand-voice.md` with approved changes. | Your send/reply/acceptance metrics, or examples of messages that did/didn't work | Diagnosis report + edits to `context/brand-voice.md` | ✅ Just paste your numbers |

---

### What you provide · What you get (overview)

| What you provide | What you get |
|------------------|--------------|
| ICP / filter rules (saved to `linkedin-settings.json` via `/onboard`) + **real lead CSV** | Daily output: `qualified` / various disqualify CSVs + **`lead_registry_*.json`** (the canonical key source for all downstream steps) |
| Voice calibration (saved to `brand-voice.md` via `/calibrate-voice`); optional: real messages you've written | **First-touch LinkedIn drafts** (written to `output/outreach_*` by script, generated by Agent per skill flow) |
| `lead_key` + prospect's message | **Reply draft** (`output/replies_*`) |
| `lead_key` + conversation outcome | **Status and metrics update** (recorded in `linkedin-system-state.json` for tracking) |
| Real data and examples during retro (shared in conversation with Agent) + optional weekly report script | **Campaign retro conclusions** + **`reports/weekly-summary_*.md`** |

---


## Getting your leads

This pipeline works with any CSV of LinkedIn leads. You have two paths:

### Option A — Bring your own CSV

Export from LinkedIn Sales Navigator, Apollo, or any other tool. The script accepts any CSV that can be mapped to name, title, company, and LinkedIn URL. See [CSV column names](#csv-column-names) below.

### Option B — Use linkednav.com warm leads (recommended)

[linkednav.com](https://www.linkednav.com) surfaces people who have already shown interest in you or your content — these are warmer than cold lists and respond at higher rates. Export your leads directly from the dashboard into this pipeline.

**Signals LinkedNav tracks:**

| Category | Signal | What it means |
|----------|--------|--------------|
| **Your content** | `post_like` | Liked one of your posts |
| | `post_comment` | Commented on one of your posts |
| | `post_share` | Shared your content |
| | `poll_vote` | Voted on your poll |
| | `article_reaction` | Reacted to your article |
| | `article_read` | Read your long-form article |
| | `newsletter_subscriber` | Subscribed to your newsletter |
| | `mention` | Mentioned you in a post |
| | `content_download` | Downloaded your lead magnet |
| **Profile & network** | `profile_view` | Viewed your profile |
| | `connection_request` | Sent you a connection request |
| | `event_attendee` | Attended your LinkedIn event |
| | `company_follower` | Follows your company page |
| **Competitor signals** | `competitor_post_like` | Liked a competitor's post |
| | `competitor_post_comment` | Commented on a competitor's post |
| | `competitor_event_attendee` | Attended a competitor's event |
| **Intent signals** | `tool_recommendation_ask` | Posted asking for tool recommendations |
| | `pain_point_post` | Posted about a problem your service solves |
| | `influencer_post_like` | Engaging with niche influencers in your category |
| | `industry_event_attendee` | Attended a relevant industry event |
| | `conference_speaker` | Speaking at an industry conference |
| **Company growth** | `funding_news` | Company announced funding |
| | `press_mention` | Company featured in the press |
| | `hiring_surge` | Company posted many roles recently |
| | `hiring_adjacent_role` | Hiring for a role that typically buys your service |
| | `hiring_pain_point_jd` | Job description describes the problem you solve |
| | `hiring_competitor_tool_mention` | JD requires experience with a competing tool |
| | `hiring_volume_surge` | Function expanding fast |
| | `hiring_new_senior_leader` | New C-suite hire — tool stack reassessment likely |
| **Life events** | `job_change` | Recently changed roles |
| | `work_anniversary` | Work anniversary — often reassessing tools |

All signals map directly to the scoring logic in `/linkedin-lead-filter`. High-warmth signals score 3 and are prioritized for outreach. Reaching out within 24 hours of a signal → significantly higher reply rates.

**LinkedNav also handles sending.** After you've drafted and approved your messages here, LinkedNav can run the outreach campaign and follow-ups autonomously.

---

## What you need to provide (user input / configuration)

Each item below is a real data entry point. **Do not use fabricated placeholder data in place of real leads.** If you don't have data yet, complete configuration first, then import a real CSV.

### CSV column names

Your CSV needs to be mappable to name, title, company, and LinkedIn URL at minimum. The skill accepts common export formats from LinkedIn Sales Navigator, Apollo, linkednav.com, and others.

Supported column aliases:
- Name: `First Name` + `Last Name`, or `Name`
- Title: `Job Title` / `Position` / `Title`
- Company: `Company`
- Industry: `Industry`
- Location: `Location` / `Geography`
- LinkedIn: `LinkedIn URL` / `Linkedin URL` / `LinkedIn`
- Signal: `Source Post`, `Imported At`

See `sample_contacts.example.csv` for a working example.

For full technical details see `PRODUCT_SYSTEM.md` and `contracts/lead-artifact-contract.md`.

---

## Distribution notes

- `output/` and `reports/` contain run artifacts and are excluded via `.gitignore`; directories are created by `bootstrap-system.js`.
- `state/*.json` is excluded from the repo — only `state/*.example.json` templates are committed. Copy them or run `bootstrap` after cloning.
- `*.csv` files are excluded from the repo — never commit real lead data. Use `sample_contacts.example.csv` as a structural reference.
- After cloning, run `bootstrap` first, then fill in your own CSV and context files.

---

## What a warm lead CSV looks like

This is the kind of data you get from linkednav.com. Each row is a real person who already showed a signal — not a cold name from a list.

| Name | Title | Company | Signal | What happened |
|------|-------|---------|--------|--------------|
| Jane Doe | VP of Marketing | Acme Corp | `post_like` | Liked your post on outbound sequencing |
| John Smith | Head of Growth | Beta Inc | `post_comment` | Commented: "this is exactly the problem we're dealing with" |
| Maria Garcia | Director of Demand Gen | Gamma Ltd | `profile_view` | Viewed your profile 3 times in 7 days |
| David Lee | Founder | Delta Ventures | `post_share` | Shared your post on LinkedIn automation to their network |
| Sarah Kim | CMO | Epsilon Co | `newsletter_subscriber` | Subscribed to your LinkedIn newsletter on GTM strategy |
| Alex Johnson | VP Sales | Zeta Corp | `job_change` | Started new role as VP Sales — likely evaluating new tools |
| Priya Patel | Growth Lead | Eta Startup | `event_attendee` | Attended your LinkedIn event on warm outbound |
| Tom Chen | Marketing Director | Theta Inc | `company_follower` | Follows your company page |
| Lisa Wang | Revenue Operations Lead | Iota Corp | `poll_vote` | Voted on your poll about outreach personalization |
| Marcus Brown | Head of Partnerships | Kappa Inc | `article_reaction` | Reacted to your article on LinkedIn signal tracking |
| Nina Roberts | Sales Director | Lambda Co | `connection_request` | Sent you a connection request without a note |
| James Park | CEO | Mu Ventures | `mention` | Mentioned you in a post about outreach tools |
| Rachel Chen | VP of Sales | Nu Corp | `competitor_post_like` | Liked a competitor post within the last 24 hours |
| Kevin Morris | Head of Revenue | Xi Inc | `competitor_post_comment` | Commented on a competitor post: "we've been looking for exactly this" |
| Aisha Okafor | Growth Marketing Manager | Omicron Ltd | `influencer_post_like` | Liked 4 posts from a niche influencer in your category this week |
| Wei Zhang | CFO | Pi Ventures | `funding_news` | Company announced $12M Series A — now scaling GTM team |
| Elena Sousa | Director of Operations | Rho Software | `hiring_surge` | Company posted 14 new roles in the last 30 days |
| Daniel Osei | Co-Founder | Sigma Labs | `tool_recommendation_ask` | Posted asking for tool recommendations for LinkedIn outreach |
| Yuki Tanaka | Marketing Ops Manager | Tau Corp | `pain_point_post` | Posted about struggling with low reply rates on outbound |
| Sofia Rossi | Chief of Staff | Upsilon Co | `article_read` | Read your long-form article on signal-based outreach |
| Ethan Brooks | VP Marketing | Phi Group | `content_download` | Downloaded your lead magnet on outreach templates |
| Amara Diallo | Head of Sales Enablement | Chi Inc | `work_anniversary` | 5-year work anniversary — likely reassessing tools and processes |
| Lucas Andrade | Founder | Psi Startup | `press_mention` | Company featured in TechCrunch for new product launch |
| Hannah Müller | CRO | Omega GmbH | `conference_speaker` | Announced as keynote speaker at SaaStr 2024 |
| Ryan Thompson | VP of Operations | Alpha SaaS | `hiring_adjacent_role` | Hiring for a role that typically owns the problem your service solves |
| Fatima Al-Rashid | Head of Marketing | Beta Cloud | `hiring_pain_point_jd` | Job description explicitly describes the pain your service solves |
| Liam O'Brien | Director of Operations | Gamma Tech | `hiring_volume_surge` | Same function posted 4 roles in 30 days — expanding fast |
| Mei Suzuki | CEO | Delta Co | `hiring_new_senior_leader` | Just hired a new C-suite leader in your buyer persona |
| Carlos Mendez | VP of Product | Epsilon Media | `hiring_competitor_tool_mention` | JD requires experience with a competing tool — actively evaluating |
| Ingrid Larsson | Head of Growth | Zeta Nordic | `competitor_event_attendee` | Attended a competitor's product launch event last week |
| Omar Hassan | VP of Partnerships | Eta Corp | `industry_event_attendee` | Attended industry conference on B2B sales automation |