Prospector

# Prospector

Find leads matching your ICP via Exa company search + Apollo contact enrichment.

## Prerequisites

Run `/prospector:setup` first to configure your API keys: - **Exa** (required): https://exa.ai - company discovery - **Apollo** (required): https://apollo.io - contact enrichment - **Attio** (optional): https://attio.com - CRM sync

You can also set keys via environment variables: - `PROSPECTOR_EXA_API_KEY` - `PROSPECTOR_APOLLO_API_KEY` - `PROSPECTOR_ATTIO_API_KEY` (optional)

## Usage

### Setup (one-time)

``` /prospector:setup ```

Collects and validates API keys, stores securely in `~/.config/prospector/config.json`.

### Find Leads

``` /prospector ```

Asks ICP questions, searches Exa, enriches via Apollo, outputs CSV to Desktop.

## Main Command: /prospector

When the user invokes `/prospector`, follow this workflow:

### Step 1: Check Config or Env Vars

First, verify env vars or config exist:

```bash python3 -c " import json import os from pathlib import Path config_path = Path.home() / '.config' / 'prospector' / 'config.json' env_exa = bool(os.getenv('PROSPECTOR_EXA_API_KEY')) env_apollo = bool(os.getenv('PROSPECTOR_APOLLO_API_KEY')) env_attio = bool(os.getenv('PROSPECTOR_ATTIO_API_KEY')) if not config_path.exists(): print('NOT_FOUND') else: with open(config_path) as f: config = json.load(f) print('FOUND') print(f'exa: {bool(config.get(\"exa_api_key\"))}') print(f'apollo: {bool(config.get(\"apollo_api_key\"))}') print(f'attio: {bool(config.get(\"attio_api_key\"))}') print(f'env_exa: {env_exa}') print(f'env_apollo: {env_apollo}') print(f'env_attio: {env_attio}') " ```

If NOT_FOUND and env vars are not set, tell user to run `/prospector:setup` first.

### Step 2: Ask ICP Questions

Use AskUserQuestion to collect ICP criteria in order:

**Question 1: Industry** ``` header: "Industry" question: "What industry are you targeting?" options: - label: "SaaS" description: "Software as a Service companies" - label: "Fintech" description: "Financial technology companies" - label: "Healthcare" description: "Healthcare and health tech" - label: "E-commerce" description: "Online retail and marketplaces" - label: "AI/ML" description: "Artificial intelligence and machine learning" - label: "Any" description: "No industry filter" multiSelect: false ```

**Question 2: Company Size** ``` header: "Size" question: "What company size are you targeting?" options: - label: "1-10" description: "Early stage startups" - label: "11-50" description: "Seed to Series A" - label: "51-200" description: "Series A to B" - label: "201-500" description: "Growth stage" - label: "500+" description: "Enterprise" - label: "Any" description: "No size filter" multiSelect: false ```

**Question 3: Funding Stage** ``` header: "Funding" question: "What funding stage are you targeting?" options: - label: "Pre-seed" description: "Pre-product market fit" - label: "Seed" description: "Building initial product" - label: "Series A" description: "Scaling product" - label: "Series B+" description: "Growth and expansion" - label: "Any" description: "No funding filter" multiSelect: false ```

**Question 4: Geography** ``` header: "Geography" question: "What geography are you targeting?" options: - label: "United States" description: "US-based companies" - label: "Europe" description: "European companies" - label: "Global" description: "Worldwide" - label: "Any" description: "No geography filter" multiSelect: false ```

**Question 5: Keywords (optional)** ``` header: "Keywords" question: "Any specific keywords that should appear in company descriptions? (optional)" options: - label: "Skip" description: "No keyword filter" - label: "Enter keywords" description: "I'll type specific keywords" multiSelect: false ```

If "Enter keywords", ask for the text input.

**Question 6: Contact Count** ``` header: "Count" question: "How many contacts do you want to find?" options: - label: "25" description: "Quick search, lower API usage" - label: "50" description: "Balanced (recommended)" - label: "100" description: "Larger batch, more API usage" multiSelect: false ```

### Step 3: Run Search

Execute the Python script with the collected ICP:

```bash cd [skill_directory]/scripts python3 -c " from prospector import run_search, export_csv, Config

icp = { 'industry': '[INDUSTRY]', 'company_size': '[SIZE]', 'funding_stage': '[FUNDING]', 'geography': '[GEOGRAPHY]', 'keywords': '[KEYWORDS or empty string]' }

leads = run_search(icp, num_contacts=[COUNT]) if leads: path = export_csv(leads) print(f'SUCCESS: {len(leads)} leads saved to {path}') else: print('NO_RESULTS: No leads found matching criteria') " ```

Replace placeholders with actual values from questions.

### Step 4: Attio Sync (if configured)

If Attio is configured and leads were found, ask:

``` header: "Attio" question: "Sync leads to Attio CRM?" options: - label: "Yes" description: "Sync companies and contacts to Attio" - label: "No" description: "Just keep the CSV" multiSelect: false ```

If yes:

```bash cd [skill_directory]/scripts python3 -c " from prospector import sync_to_attio, Config, Lead import json

# Load leads from the CSV we just created (or pass them directly) # For simplicity, re-run with sync leads = [...] # Pass leads from previous step

companies, people = sync_to_attio(leads) print(f'SYNCED: {companies} companies, {people} contacts') " ```

### Step 5: Report Results

Tell the user: - How many leads were found - Where the CSV was saved - If Attio sync was done, how many records were synced

## Error Handling

- **Config not found**: Tell user to run `/prospector:setup` - **Invalid API key**: Tell user which key failed, suggest re-running setup - **No results**: Suggest broadening ICP criteria - **Partial failures**: Report what succeeded, warn about failures