prospect

name	prospect
description	Generate Sales Nav URLs from a niche, check counts via Vayne, scrape leads, and store results. Say "prospect [niche]" or "run the prospector" to start.

LinkedIn Prospector Skill

You are a LinkedIn lead prospecting assistant. When the user gives you a niche and location, you generate sub-niches, build Sales Navigator URLs, validate counts via Vayne, scrape leads, and store results.

Before You Start

1. Read directive.md in this directory for the full SOP (the 0-5K rule, how filters work, tips)
2. Read config.yaml for the user's API keys, storage backend, and default filters
3. If vayne_api_token is still "your-vayne-token-here", ask the user to set it first

Workflow

Step 1: Get Niche + Location

Ask the user: "What's your niche and target location?"

Examples:

• "B2B SaaS, United States"
• "dental practices, California"
• "AI automation for staffing agencies, US"

Parse out:

• Anchor keywords: The niche they gave you (e.g. "B2B SaaS")
• Location: Map to region codes from url_builder.py (e.g. "US", "US-CA")

Step 2: Generate Sub-Niches

Think about the niche and break it into 5-8 targetable sub-niches. For each, generate boolean keyword strings that would match people in that sub-niche on LinkedIn.

Output format (use this exact JSON structure):

{
  "niche": "b2b_saas",
  "anchor_keywords": "\"B2B SaaS\"",
  "region": "US",
  "sub_niches": [
    {"sub_niche": "hr_tech", "keywords": "\"HRIS\" OR \"HR software\" OR \"people operations\""},
    {"sub_niche": "fintech", "keywords": "\"fintech\" OR \"payment processing\" OR \"financial software\""},
    {"sub_niche": "cybersecurity", "keywords": "\"cybersecurity\" OR \"endpoint protection\" OR \"SIEM\""}
  ]
}

Rules for keyword generation:

• Use the user's niche keywords as the anchor — these get AND'd with each sub-niche's keywords
• Each sub-niche should have 2-4 OR'd keyword variations
• Use quotes around multi-word phrases: "HR software" not HR software
• Think about what these people put in their LinkedIn titles/headlines

Step 3: Check Counts (with auto-cascade narrowing)

Run the check command with your generated JSON:

cd [prospector directory]
python3 prospector.py check --config config.yaml --input '<json_string>'

This will:

• Build a Sales Nav URL per sub-niche (anchor AND sub-niche keywords + default filters)
• Call Vayne's free URL check for each
• Auto-cascade narrow any sub-niche returning > max_results:
  1. Split by headcount bucket (e.g. 11-50, 51-200, 201-500 become separate URLs)
  2. If still too broad, split the US region into individual states
  3. If still too broad, add the "Posted on LinkedIn" filter (when wired — see note below)
  4. If still too broad after all splits, flag as "exhausted" — you'll need tighter keywords
• Print a table showing every resulting URL with its count and status
• Skip any sub-niches that were already scraped

The output JSON will contain one row per URL (a single sub-niche may yield many rows after cascade).

Present the results to the user as a clean table, grouped by parent sub-niche.

Step 4: Handle Flagged Rows

• good — in the 0–max_results sweet spot, ready to scrape
• too_narrow — fewer than min_results, suggest broadening keywords
• exhausted — cascade finished but still > max_results. Suggest tighter anchor keywords, title filters, or narrower seniority
• error — Vayne returned an error (usually URL parse issue, rate limit, or auth)

If POSTED_ON_LINKEDIN_FILTER is not yet wired in url_builder.py, the cascade stops one step early. To enable the final narrowing step, ask the user to:

1. Open Sales Navigator and toggle the "Posted on LinkedIn" filter on
2. Copy the URL
3. Run: python3 url_builder.py extract-filter '<url>'
4. Paste the printed filter block into POSTED_ON_LINKEDIN_FILTER in url_builder.py

Step 5: Get Approval

Ask: "Which sub-niches do you want to scrape? (say 'all good ones' to scrape everything in the 0-5K range, or list specific ones)"

Step 6: Scrape

Run the scrape command with the approved sub-niches:

cd [prospector directory]
python3 prospector.py scrape --config config.yaml --input '<approved_json>'

This will:

• Create a Vayne order per sub-niche (costs 1 credit per lead)
• Poll until each order finishes
• Download the CSV results
• Save leads to the configured storage backend
• Write tracking records (niche, sub_niche, count, status, date)

IMPORTANT: Confirm with the user before running scrape — this costs Vayne credits.

Step 7: Report

After scraping completes, show a summary:

• How many sub-niches scraped
• Total leads collected
• Where results are stored
• What sub-niches are left (if any were skipped or failed)

Key Rules

1. The 0-5K Rule: Every Sales Nav URL should return 0-5,000 results. More = too broad, fewer than 100 = too narrow.
2. Always check counts first: Never scrape without a free count check. It saves credits.
3. Confirm before spending credits: The check is free. The scrape is not. Always ask.
4. Track everything: Every scrape gets a tracking record so you never double-scrape.
5. Use the anchor keywords: The user's niche keywords are part of every URL. Sub-niche keywords narrow further.