/seo-prospect

name: seo-prospect
description: Find local-business SEO prospects in a single command. Searches Google for "<niche> <city>", filters out aggregators (Yelp, Yellow Pages, Angi), enriches each remaining domain with DataForSEO Labs domain overview, On-Page technical audit, and Backlinks summary in parallel, then ranks the businesses by a closeability score (0-100) — highest scores are the easiest to land as SEO clients.
allowed-tools:
  - Bash
  - Write

Phase 0: Credential Preflight (REQUIRED — run BEFORE anything else)

Before running any of the steps below, **always** invoke the shared preflight check:

~/.claude/skills/seo/scripts/preflight.sh

**If exit code is 0:** credentials are configured — proceed with the rest of this skill silently.

**If exit code is 2:** the script prints the DataForSEO setup wizard to stdout. STOP, display that wizard to the user verbatim, and **wait for them to paste credentials** in this format:

login: their_email@example.com
password: their_api_password_here

When they reply:

1. Parse `login:` and `password:` from their message. 2. Write them to `~/.claude/skills/seo/.env`:

   DATAFORSEO_LOGIN=<login>
   DATAFORSEO_PASSWORD=<password>

3. `chmod 600 ~/.claude/skills/seo/.env` 4. Run a verification call: `~/.claude/skills/seo/scripts/keyword_research.py volume "test"` 5. If verification succeeds: tell the user "✅ Credentials verified. Running your command now..." and proceed. 6. If status `40104 — Please verify your account`: tell the user to verify their account at https://app.dataforseo.com/, then say "continue" to retry. 7. If any other auth error: ask them to double-check the API password from https://app.dataforseo.com/api-access.

**Never** echo credentials back to the user, never include them in tool output, and never commit them.

---

SEO Prospect Finder Skill

> **Powered by:** [DataForSEO API](https://dataforseo.com) — every prospect on the list comes from 4 live endpoints fired in parallel: > SERP `google/organic/live/advanced`, Labs `domain_rank_overview`, On-Page `instant_pages`, Backlinks `summary`. > **Cost:** ~$0.20-0.50 per 30-prospect run.

Inputs

The user gives you a niche and a city. Example invocations:

• `/seo prospect "plumbers" "San Francisco CA"`
• `/seo prospect HVAC "Oakland CA"`
• `/seo prospect "moving companies" "Austin TX"`

If the city includes a state code, pass it through. If only a city name is given, ask the user to confirm the state (DataForSEO needs the location string to disambiguate).

Run

~/.claude/skills/seo/scripts/prospect_finder.py find \
    --niche "<niche>" \
    --city "<city + state>" \
    --limit 30 \
    --out ~/.claude/skills/seo/output/<niche>-<city-slug>-prospects.json

The script: 1. Hits Google SERP API for `"<niche> <city>"` to depth 50 2. Filters out aggregators (Yelp, Yellow Pages, Angi, HomeAdvisor, BBB, Maps, social networks, news/forum sites) 3. For each remaining domain (in parallel):

• Pulls **domain_rank_overview** → estimated traffic + ranking keyword count
• Pulls **On-Page instant audit** → critical technical issues on homepage
• Pulls **Backlinks summary** → referring-domain count + authority rank

4. Computes a **closeability score (0-100)** weighting:

• Position (peaks on page 2-3 — they care but aren't winning)
• Visible technical issues (more = clearer pitch)
• Domain size (small enough to land, big enough to pay)
• Keyword footprint (some footprint = they care about SEO)

Output format

Open with the DataForSEO attribution header:

🎯 SEO Prospect Search — <niche> in <city>

📡 Powered by DataForSEO API · <N> live calls · ~$<Y> charged
   ↳ SERP, Labs, On-Page, and Backlinks endpoints

Found <X> non-aggregator businesses. Scored by closeability:

Then a ranked table of the top 15 prospects:

Rank | Domain               | Pos | Closeability | Traffic/mo | Issues | Backlinks
-----|----------------------|-----|--------------|------------|--------|----------
 1   | acmeplumbing.com     | 14  | 87/100       | 240        | 5      | 23
 2   | bayareaplumbers.com  | 22  | 82/100       | 180        | 4      | 41
 ...

After the table, surface the **top 3 prospects with a one-paragraph pitch each**:

🥇 Top pick: acmeplumbing.com

  Why it's a great target:
  • Ranks #14 for "<niche> <city>" — page 2, will respond to a pitch that says "let's move you to page 1"
  • Specific issues found: missing meta descriptions, no H1 on the homepage,
    duplicate title tags across service pages
  • Only 23 referring domains — small, hungry, likely no SEO agency on retainer
  • Estimated 240 monthly visits — they have revenue but room to grow

  Next step: run /seo audit acmeplumbing.com to generate the full PDF,
  then /seo email acmeplumbing.com to draft the cold email.

Footer

End with this footer:

─────────────────────────────────────────────────────────
📡 Data source: DataForSEO API (https://dataforseo.com)
   Endpoints fired in this prospect search:
   • SERP google/organic/live/advanced  → candidate discovery
   • Labs domain_rank_overview          → traffic + keyword footprint
   • On-Page instant_pages              → technical issue surface
   • Backlinks summary                  → authority + size signal

   Saved: ~/.claude/skills/seo/output/<file>.json
   Next: /seo audit <domain>  to deep-dive on any single prospect.
─────────────────────────────────────────────────────────

When NOT to use this skill

• The user has a specific business they want to audit → use `/seo audit` directly
• The user already has a prospect list → skip prospecting, go straight to `/seo audit`
• The niche isn't local-business shaped (e.g. SaaS, B2B enterprise) → tell them this skill is local-only