lead-search

When to invoke this skill

Builds a lead list from the open web only: companies (or people) matching a described buyer, each row carrying the URL it came from and an honest confidence. No accounts, no logins, no paid data, no outreach — this skill ends at the list. Use when asked to "find leads", "build a lead list", "find prospects", or "who could we sell to".

What you need first

Check for a plan before asking anything. Pick the topic: ls PLAN-*.md 2>/dev/null. If the user named a topic, use PLAN-<topic>.md. If exactly one PLAN exists, use it. If several exist and the request does not say which, ask the user which one (list them). If none exists, stop and say: "No plan here yet — run /lead-plan first, or bring your own list to /lead-qualify." The topic is the part between PLAN- and .md; every other file for it uses the same topic: leads-<topic>.csv. If a plan exists, confirm it in one line ("Found PLAN-acme-austin.md — sell X in Y, target N. Use it?") and take the three facts below, plus the disqualifiers, from it. Anything the user says explicitly in this conversation overrides the plan.

No plan → plan the outreach first. A list is the first step of an outreach the user is about to run, and it is only as good as that plan: who would really reply, why now, what we will say and ask for, the channel and cadence. With no PLAN-<topic>.md, load /lead-plan (the skill tool, or tell the user to type it) and follow it to the end — its questions, the plan, the read-back — before a single search. Then come back here with that plan. Only if /lead-plan is not installed: pick a topic slug from the niche and territory, then:

Three facts. Check the conversation and workspace first; ask for whatever is still missing in a SINGLE message, then wait.

• What they sell — a list built from a guessed offering is confidently aimed at the wrong buyer.
• Where they sell — territory decides which of two identically named companies is the lead. "Anywhere" is a choice the user makes, not a default you assume.
• How many they want — ten leads deserve a fetch each; a hundred are snippet work. The budget scales from this.

If no answer comes, produce what is genuinely useful anyway, state at the top which facts you lacked, and say what would change once you have them.

Ground rules (non-negotiable)

0. Businesses only. Every row is a business with its own website, and the person is reached in their work role. No private individuals as leads — not from public records, not as "owners" of a home or a car — whatever the brief says; offer the business version instead.

These come from watching earlier lead tools fail. Each one bans a specific, observed failure. They apply in every step, whether or not you read a section.

1. Search engines are the only door to gated sites. Never fetch LinkedIn, Crunchbase, ZoomInfo, G2, Clutch or anything behind a login — they block, time out, or poison the session. site:linkedin.com/in "<company>" in a web search is fine: read the name and title off the result title (Jane Doe - CEO - Acme | LinkedIn) and cite the search, not the profile.
2. Never construct a profile URL. A LinkedIn slug you guessed (/in/first-last) is fabrication — real slugs almost always carry a disambiguator. A profile URL enters the file only if a search surfaced it this session. A right name with a wrong URL is worse than a name alone.
3. The Website column holds the company's own domain, never an aggregator. A Yelp, Clutch, Facebook or directory page is evidence, not a website.
4. No invented contact data. No email patterns, no guessed phones. A contact detail appears only if you read it on a page you fetched, cited.
5. No invented firmographics. Founding year, headcount, revenue — only if observed, with the source. A number invented to justify keeping a row poisons the list.
6. UNKNOWN is a value. Every field you could not observe says UNKNOWN. A blank looks like an oversight; UNKNOWN is a finding.

Sections (read on demand)

The step-by-step mechanics live in sections/ next to this file. Read a section right before doing that step — never all of them up front:

If sections/ is missing (partial install), do not stop: the stage goals in this file's frontmatter carry the compressed rules — follow those plus the ground rules above.

Procedure

Scratch for this run lives in .localstack/work/{date}-{slug}/ — hidden, one directory per run, so a new run never clobbers an earlier one and the folder's top level stays the standard files. Scratch is disposable; old run directories may be deleted freely.

Earlier runs: if leads-<topic>.csv already exists, say how many rows it holds before you start ("leads-acme-austin.csv has 18 rows; new finds are added, never duplicated"). This run adds to it; it never starts a second list.

1. Write the buyer down. One sentence, from what the user told you — not from their website's copy. Copy says how they describe themselves, which is often not how their buyers look.

2. Harvest (read sections/harvest.md): 5-8 searches, each a different angle, snippets only. Every candidate lands in .localstack/work/{date}-{slug}/found.md with its query and result URL.

Pick what to resolve, when you have a decide tool. One decide over found.md (one candidate per line) with a yes/no "From this line alone, could it be a business that fits the buyer sentence?" and the buyer sentence as context. Resolve the sure yes first, then the unsure (?); leave the sure no unresolved and say how many you skipped. It only orders the work: a candidate is a lead only after it is resolved.

3. Resolve and save as you go (read sections/resolve.md): per candidate — own website, location, and the decision maker with their title as a page states them (open it; several pages per web_extract call). Trail goes to .localstack/work/{date}-{slug}/resolved.md. The moment a candidate is resolved, append its row to leads-<topic>.csv — at the top of the folder, never under .localstack/, with the exact header below and no other columns (skip a domain already in it). A long run never holds its leads in notes only: if it stops, the list holds everything found so far. localoy checks the file at the end of the turn and sends it back if the path or header is wrong.

4-6. Dedupe, check, report (read sections/report.md): confirm one row per canonical domain and the exact canonical header, update the standard files, then the short gist in chat naming the plan consumed.

7. Hand off. Offer the next stage — "Qualify this list with /lead-qualify?" — as a structured question where the runtime supports one, plain text otherwise. On yes, invoke /lead-qualify if this runtime can invoke skills directly (Claude Code: the Skill tool); otherwise tell the user to type /lead-qualify (Codex: $lead-qualify). The skill still ends at the list; the chain continues only when the user says so.

Quality bar

• Every field traces to something fetched, searched, or told to you this session. What you remember about a company is not evidence.
• A row that fails rule 2 or 3 does not ship with a caveat — it ships fixed or not at all.
• Partial work is reported as partial: "34 found, 20 resolved, budget spent" beats a padded list where the last ten rows are guesses.
• No scores. Confidence is the three-word enum, argued from observations, never a number.