# List Expander > Expand a hard-to-build niche list from ~10 known-good seed companies into a full qualified TAM. Seed fingerprinting (how do good-fit companies ACTUALLY show up in the company database's filters) → lookalike generation (Prospeo company_lookalike, Exa findSimilar, Parallel.ai entity search) → filter mining with a precision/volume scorecard → wide pull with auto-sharding → cheap-AI qualification → live-website verification → client transparency report. Use when a vertical list feels "too small" (medical groups, hedge funds, Medicare brokerages), when known good-fit companies don't show up in keyword searches, or when someone says "expand this list", "the TAM should be bigger", "find more companies like these". - Skill: `moussaoui-ghiles/list-expander` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add moussaoui-ghiles/list-expander` - Raw SKILL.md: https://api.skillmd.com/api/skills/moussaoui-ghiles/list-expander/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Moussaoui-Ghiles (https://skillmd.com/u/moussaoui-ghiles) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/moussaoui-ghiles/list-expander --- # List Expander — seed companies → lookalikes → mined filters → qualified TAM ## The problem this solves Niche lists come out tiny because we search databases with narrow explicit keywords, but real good-fit companies (e.g. Atlantic Medical Group, Hackensack Meridian) often don't carry that keyword in their database record. Instead of guessing keywords top-down, this skill works bottom-up: take companies you KNOW fit, discover how the database actually tags them, expand via lookalike engines, and only then derive the wide-net filters — with measured precision per filter — before pulling and AI-qualifying at scale. ## Pipeline (5 phases) All scripts live in `scripts/`, run with `npx tsx`, and are dependency-free (node ≥ 18 native fetch). Every script takes `--help`. Keys load from the repo-root `.env` (see `.env.example`), falling back to `~/.env`. Artifacts land in `~/output/list-expander/{run}/`. ``` Phase 1 fingerprint.ts seeds → how each shows up in Prospeo + its live homepage Phase 2 lookalikes.ts seeds → candidates via Prospeo lookalike + Exa + Parallel (qualify candidates → lookalikes-confirmed.csv) Phase 3 mine-filters.ts confirmed fits → candidate filters → scorecard (volume × precision) Phase 4 pull.ts winning filters → wide pull, auto-shard, dedup, exclusions score-batch.ts scale AI qualification (gpt-5-nano by default) verify-website.ts second pass on QUALIFIED rows: live homepage fetch → dead / suspended-parked / live; live sites re-judged on their CURRENT content (catches stale-DB ghosts). Always run — DB descriptions happily qualify dead companies otherwise. Phase 5 contact-count.ts verified-email TAM ceiling (free Prospeo count trick) report.ts single-file HTML transparency report for the client ``` ### Phase 0 — inputs - ~10 seed companies known for sure to fit (domains). - 1–2 sentence ICP description ("multi-site medical/specialty groups in the US, ≥$3M revenue"). - Optional: exclusion CSV (companies already in campaigns). ### Phase 1 — fingerprint the seeds ```bash npx tsx scripts/fingerprint.ts --domains="a.com,b.com,..." --run= ``` Prints coverage (which seeds Prospeo is missing — **that gap IS the under-count story for the client**), plus industry and keyword-tag frequency tables. Writes `fingerprint.json/csv`. ### Phase 2 — generate lookalikes ```bash npx tsx scripts/lookalikes.ts --domains="" --run= \ --objective="" \ --country="United States #US" --pages=3 ``` - **Prospeo `company_lookalike`** (required lane): `{"domain": ""}` — one call per seed, single domain only (arrays 400). Composable with location/headcount/keyword filters. One large health system seed returned 5,727 lookalikes. - **Exa findSimilar** (optional lane): content similarity, and it returns homepage text in the same call — free evidence for qualification. - **Parallel.ai entity-search** (optional lane): ~$0.005/req, pads to `match_limit` with junk — always qualify before trusting; returns LinkedIn URLs, not domains. Optional lanes whose key is unset are **skipped with a log line**, so the run still completes on Prospeo alone. Then qualify candidates (Claude sub-agents for a small set, or `score-batch.ts` with a draft prompt) → write `lookalikes-confirmed.csv`. Target 50–150 confirmed. ### ⚠️ EXHAUSTIVE-SWEEP DEFAULT Phase 3's scorecard is for TRANSPARENCY, not selection. The pull in Phase 4 must include: (a) EVERY industry carried by ≥1 confirmed fit — whole industry, headcount band + geo only, no keyword narrowing; (b) EVERY discriminative keyword from confirmed fits across ALL industries. Score everything with the cheap model. Only band + geography are legal pre-filters. Snowball until net-new drops under 2–3%. Never trim the sweep to save AI cost — recall is the product. Pull keywords unless they are stopword-grade. ### Phase 3 — mine + score filters ```bash npx tsx scripts/mine-filters.ts --csv= --run= --propose --country="United States #US" # Claude reviews/edits {run}/candidates.json: prune generic n-grams, add synonym keywords # (the "every medical group contains 'group'" trap — kill terms that are frequent but not discriminative) npx tsx scripts/mine-filters.ts --run= --scorecard # score the 25-company samples: for f in ~/output/list-expander//samples/*.csv; do npx tsx scripts/score-batch.ts --csv=$f --prompt-file= --out=${f%.csv}-scored.csv; done mkdir -p ~/output/list-expander//samples-scored && mv ~/output/list-expander//samples/*-scored.csv $_ npx tsx scripts/mine-filters.ts --run= --scorecard --precision-from=~/output/list-expander//samples-scored ``` `--propose` fingerprints each confirmed company against Prospeo **and fetches its live homepage**, then mines 2–3-grams across that combined text. The homepage is the evidence source that matters: it says what a company calls itself *today*, which is exactly what a keyword filter has to match. Pass `--no-scrape` to mine from Prospeo descriptions only (faster, thinner). Output: `filter-scorecard.csv` — per filter: Prospeo count, sampled precision, estimated qualified yield. **Review with the user before Phase 4.** ### Phase 4 — wide pull + scale qualification Tune the qualification prompt FIRST via `/icp-prompt-builder` (interactive, 10-company batches, 2 clean rounds to converge). ```bash # Write {run}/winners.json (filter_sets + base_filters — format documented in pull.ts header) npx tsx scripts/pull.ts --run= --test # 2 pages/set sanity check FIRST npx tsx scripts/pull.ts --run= --exclude= npx tsx scripts/score-batch.ts --csv=/pull-all.csv --prompt-file= --scrape --concurrency=8 npx tsx scripts/verify-website.ts --run= --prompt-file= --concurrency=40 ``` Verify the first test output shows real successes before the full run. Any filter set whose `total_count` exceeds 24k is auto-sharded (country → 51 states → headcount-band bisection) so the tail is never truncated. ### Phase 5 — TAM ceiling + report ```bash npx tsx scripts/contact-count.ts --csv= --run= \ --titles="COO,VP Operations,..." --seniorities="C-Suite,Vice President,Head,Director" npx tsx scripts/report.ts --run= --title=" — TAM Expansion" open ~/output/list-expander//report.html ``` ## Requirements / env Put these in the repo-root `.env` (copy `.env.example`), or `~/.env`. **REQUIRED** | Var | What for | Sign up | |---|---|---| | `PROSPEO_API_KEY` | Every phase: company search, lookalikes, counts | https://prospeo.io/ → dashboard → API (copy the X-KEY) | | `OPENAI_API_KEY` | AI qualification in `score-batch.ts` + `verify-website.ts` | https://platform.openai.com/api-keys | **OPTIONAL** (each is one lane; unset = that lane logs `skipped: not set` and the run continues) | Var | What for | Sign up | |---|---|---| | `EXA_API_KEY` | Exa `findSimilar` lookalike lane in `lookalikes.ts` | https://exa.ai/ | | `PARALLEL_AI_API_KEY` | Parallel.ai entity-search lookalike lane in `lookalikes.ts` | https://parallel.ai/ | | `OPENAI_API_KEY_NANO` | A separate cheap-model key; used in preference to `OPENAI_API_KEY` when set | https://platform.openai.com/api-keys | | `OPENAI_ICP_MODEL` | Override the qualification model (default `gpt-5-nano`) | — | | `PROSPEO_MIN_INTERVAL_MS` | Slow Prospeo pacing below the built-in 450ms floor. Can only make it **slower** — values under 450 are clamped | — | No database is required. Every artifact is a file under `~/output/list-expander/{run}/`. ## Verified API facts | Filter | Syntax | Notes | |---|---|---| | `company_lookalike` | `{"domain": "x.com"}` or `{"icp_text": "..."}` | single domain only; `icp_text` describing the *product* surfaces vendors — describe the *company* | | `company_keywords` | `{"include": [...], "exclude": [...]}` | multi-word phrases OK; combine with `company_industry` for precision | | `company_key_customers` | `{"include": [...]}` | matches by who their customers are | | `company_headcount_custom` | `{"min": N, "max": N}` | use this, not `headcount_range` (enum format unverified) | | `company_products_services`, `company_icp` | ❌ broken/unusable via API | use `company_keywords` / `company_lookalike.icp_text` instead | **Prospeo pacing (measured):** `PROSPEO_MIN_INTERVAL_MS=200` (5 req/s) trips "Rate limit exceeded" after ~1,000 requests; **450 ms (~2.2 req/s) ran 1,550+ requests clean**. The account limit is GLOBAL, so `lib.ts` paces every process through a shared slot file (`~/.cache/prospeo-lock/`) with a 450 ms floor, backs off 45 s on a rate-limit, and makes that penalty visible to every other running process. Identical request+page re-runs within 30 days are FREE (`free:true`) — re-pulling after a partial failure costs nothing. **Prospeo count trick:** a page-1 call's `pagination.total_count` sizes any filter cheaply; add `person_contact_details:{email:["VERIFIED"]}` on `/search-person` for the verified-email ceiling. Seniority enum: `Founder/Owner, C-Suite, Partner, Vice President, Head, Director, Manager, Senior, Entry, Intern` — never "VP", never "President". ## Related skills - `/icp-prompt-builder` — tune the qualification prompt before Phase 4 (the score-batch script it refers to lives HERE: `scripts/score-batch.ts`) - `/prospeo-search-api` — full Prospeo filter reference - `/prospeo-full-export` — title-first paginated lead export once you have the company list - `/blitz-list-builder` — domain-first contact discovery on the qualified companies - `/disco-like` — a 4th lookalike source (seed domains or NL ICP text) - `/list-quality-scorecard` — grade the final CSV before it goes anywhere near a campaign