Files
Corey Haines f86637eace feat: add prospecting skill + truelist integration (#308)
* feat: add prospecting skill + truelist integration

New skill: skills/prospecting/
- SKILL.md (251 lines, well under 500 limit): branch picker for SaaS / B2B /
  Local SMB, shared 5-phase framework (ICP -> discovery -> qualify -> score ->
  output), compliance guardrails, tool selection quick-picks, output formats
- references/saas-prospecting.md: tech stack signals, funding/hiring triggers,
  SaaS-specific sources and qualification
- references/b2b-prospecting.md: industry/firmographic signals, trigger events,
  decision-maker mapping, B2B-specific sources
- references/local-prospecting.md: 4-tier website status classification,
  browser-assisted research workflow (generalized from the local-client-
  prospector pattern), proximity scoring
- references/data-sources.md: deep dives on Apollo, Clay, ZoomInfo, Clearbit,
  Hunter, Snov, Truelist, LinkedIn Sales Nav, BuiltWith, Crunchbase, RB2B,
  with sequencing recommendations across the three branches
- references/compliance.md: CAN-SPAM, GDPR, CASL, platform ToS (LinkedIn,
  Google Maps, Apollo/ZI/Clearbit), anti-patterns, audit checklist
- evals/evals.json: 6 evals (2 SaaS, 2 B2B, 1 Local SMB, 1 deliverability)

New integration:
- tools/integrations/truelist.md: email deliverability validation
  (Deliverable / Risky / Undeliverable / Unknown classification)

Registry + marketplace wiring:
- tools/REGISTRY.md: truelist row + new Email Verification category section
- .claude-plugin/marketplace.json: bumped to 2.1.0, prospecting added to
  plugin description
- VERSIONS.md: prospecting 1.0.0 + 2.1.0 changelog entry
- README.md: skill table re-synced, prospecting added to ASCII flow under
  Sales & GTM column

All 41 skills pass validation. sync-skills.js is idempotent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(prospecting): add GitHub stargazers/forks/watchers as discovery channel

Net-new in this commit:
- tools/clis/github-prospects.js: zero-dep Node CLI with commands
  stargazers / forks / watchers / user / rate-limit. Pagination via Link header,
  optional --enrich for full profile data, --with-email / --with-company /
  --with-blog filters, --format csv|json output, --dry-run preview. Uses
  GITHUB_TOKEN for 5000/hr rate limit (vs 60/hr unauthenticated).
- tools/integrations/github.md: integration guide covering auth, rate limits,
  endpoints, workflows for SaaS prospecting, compliance notes (public API, not
  scraping), CLI reference.

Skill updates:
- skills/prospecting/SKILL.md: added GitHub to the tool selection quick picks
  and to the tool integrations table.
- skills/prospecting/references/saas-prospecting.md: added GitHub to Tier 3
  buying signals plus a dedicated "GitHub prospecting pattern (when audience
  is developers)" subsection with end-to-end workflow.
- skills/prospecting/references/data-sources.md: added GitHub deep-dive
  section between RB2B and Free fallbacks.

Registry:
- tools/REGISTRY.md: github row in Tool Index, new Developer Intent / GitHub
  category section.

All 41 skills still pass validation. sync-skills.js still no-op.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(prospecting): apply review suggestions

CLI hardening + optimization:
- github-prospects.js: encodeURIComponent on username path interpolation
  (defense in depth; GitHub usernames are restricted enough that this is safe
  in practice, but good hygiene).
- github-prospects.js: refactored enrichUsers to filter inline and support
  --target N early termination. Previously, --with-email on a 1000-star repo
  would enrich all 1000 users before filtering down to the ~50 that match.
  Now you can pass --target 25 to stop as soon as 25 matches are found,
  saving API quota on restrictive filters.
- github.md: documented the new --target flag.

Reverse cross-references (so prospecting is discoverable from sibling skills):
- cold-email: added prospecting as the natural upstream skill
- customer-research: added "Translating customer research into an ICP for
  outbound" hand-off to prospecting
- competitor-profiling: distinguished from prospecting ("this skill does deep
  research on specific accounts; prospecting builds the initial list")

All 41 skills still pass validation. sync-skills.js still no-op.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(truelist): align integration doc with actual OpenAPI spec

Source of truth: Truelist-Labs/truelist-openapi (OpenAPI 3.1).

The earlier integration doc had inferred (and wrong) endpoint paths, request
shapes, and status enum values. Corrected against the published spec:

Base URL: https://api.truelist.io
Endpoints (real):
- POST /api/v1/verify_inline?email=... (sync single, email is query param)
- POST /api/v1/verify (async bulk, body: {emails: [...]})
- GET /me (account info)

Real email_state enum:
- ok, email_invalid, risky, unknown, accept_all
(not the inferred "Deliverable / Risky / Undeliverable / Unknown")

Real email_sub_state enum:
- email_ok, is_disposable, is_role, unknown_error, failed_smtp_check

Also corrected:
- Truelist has an official MCP server (Truelist-Labs/truelist-mcp) — was
  marked as MCP unavailable
- Truelist has 7 official SDKs (Node, Python, Ruby, PHP, Go, Java, .NET) +
  framework integrations (Django, Laravel, Next.js, Rails, React, Svelte,
  Vue, WordPress) — was marked as SDK unavailable
- Native integrations with Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n,
  Clay, Salesforce, ActiveCampaign, Brevo, ConvertKit, Drip, BigCommerce,
  Go High Level — was unlisted
- Rate limits: 10 req/s per endpoint (was unspecified)

Files updated:
- tools/integrations/truelist.md: full rewrite against spec
- tools/REGISTRY.md: MCP and SDK columns now show ✓ for truelist; classifier
  note in the Email Verification section reflects real enum values
- skills/prospecting/evals/evals.json: eval #6 expected_output and assertions
  use real email_state values and mention the MCP server
- skills/prospecting/references/data-sources.md: Truelist deep-dive uses real
  endpoint paths, real enum values, and lists the MCP/SDK ecosystem

All 41 skills still pass validation. sync-skills.js still no-op.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(prospecting): add Firecrawl + Browserbase for single-target site research

Both tools are programmatic scrapers, but their use in prospecting is
strictly bounded: extract content from individual public business sites
(the prospect's own website URL), never from the platforms hosting them
(Google Maps, LinkedIn, Yelp, Apollo, etc.). This matches the line drawn
by the original local-client-prospector reference skill and our own
compliance section.

New integration docs:
- tools/integrations/firecrawl.md: REST + MCP + SDKs (Node/Python/Go/Rust);
  scrape / map / crawl / extract / search endpoints; explicit "when NOT to
  use" section listing the prohibited platforms.
- tools/integrations/browserbase.md: real Chromium via Playwright/Puppeteer
  or Stagehand (AI-friendly natural-language extraction); session
  recordings; useful when rendering or interaction is required.

Prospecting skill updates:
- SKILL.md: added Firecrawl + Browserbase to tool selection quick picks
  and tool integrations table.
- references/data-sources.md: new "Firecrawl / Browserbase (single-target
  site research)" section between RB2B and Free fallbacks. Includes the
  compliance line inline so the framing isn't lost.
- references/local-prospecting.md: optional "programmatic verification"
  paragraph in the browser research workflow — once you have a candidate's
  URL from manual Maps discovery, you can hit it programmatically.
- references/compliance.md: anti-pattern #1 now explicitly clarifies that
  Firecrawl/Browserbase are fine for the prospect's own website but not
  for the platforms hosting prospects.

Registry:
- tools/REGISTRY.md: firecrawl + browserbase rows in Tool Index, new "Site
  Scraping (single-target only)" category section with the compliance
  framing in the agent recommendation.

All 41 skills still pass validation. sync-skills.js still no-op.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 11:20:26 -07:00

6.1 KiB

Prospecting Compliance Reference

The legal and platform-ToS constraints that apply to prospect list building. Read first, every engagement.

Operational guidance, not legal advice. For high-volume programs or programs touching EU/UK residents, run your setup past a privacy attorney.


United States — CAN-SPAM (downstream)

CAN-SPAM regulates the cold email send, not the list build. But the list build matters because:

  • You must be able to identify the source of every email address you contact (required if challenged)
  • The "from" line and email content rules apply at send time — but you can't lie about how you got the contact
  • Opt-out requests must be honored within 10 business days and tracked

For prospecting specifically: capture and retain the source URL + date for every contact you add to a list. CAN-SPAM doesn't require it explicitly, but defending your sender practices does.


EU / UK — GDPR

The strictest applicable framework. Triggers when:

  • Your prospect resides in EU/UK
  • You're processing personal data (any identifiable info, including business emails tied to a named person)

Lawful bases for cold B2B outreach

You have three credible options:

  1. Legitimate interest (most common for B2B). Requires:

    • The contact is in a business role likely to be interested in your offer
    • The data was collected from a public, business-context source
    • You provide a clear opt-out
    • You can articulate the legitimate interest test in writing
  2. Consent — typically not feasible for cold outreach (you don't have consent before first contact)

  3. Existing customer relationship — only applies to current customers, not prospects

What you must do

  • Capture source + date + lawful basis for every contact
  • Honor data subject access requests (DSARs) — you must be able to disclose, correct, or delete on request
  • Include a privacy notice / opt-out in the first outreach
  • Don't store personal data longer than necessary for the legitimate interest

What disqualifies a list

  • Bulk-scraped LinkedIn data — explicit ToS violation + GDPR risk
  • Email addresses purchased from a list broker without source provenance
  • "Anyone @ this domain" guessed emails sent without verification (multiplies risk + bounces)

Canada — CASL

Stricter than CAN-SPAM. Cold B2B outreach requires:

  • Express consent (explicit opt-in) — typically not present for cold prospecting
  • OR implied consent — existing business relationship within 24 months, OR business address publicly published on the company's own site for the purpose of receiving such communications

Practical implication for Canadian prospects: relying on the publicly-published-address exception is the most defensible cold prospecting basis in Canada. You must include sender identification, mailing address, and an unsubscribe mechanism in every message.


Platform Terms of Service

LinkedIn

  • Sales Navigator as a research tool: fine
  • Scraping LinkedIn at any scale: explicit ToS violation. Banned accounts are permanent. Don't.
  • Apollo, Clay, and ZoomInfo claim LinkedIn-overlap data through various legitimate channels — verify their data sources before assuming compliance
  • InMail and Connection Requests: governed by LinkedIn's own messaging rules, not by CAN-SPAM/GDPR (because LinkedIn-internal)

Google Maps

  • ToS prohibits bulk extraction or productizing Maps data
  • Browser-assisted research as a discovery aid: acceptable
  • Storing Place IDs or large structured Maps data in your CRM: explicit ToS prohibition
  • Use Maps to find local businesses, then cross-source from the business's own site for the data you retain

Apollo / ZoomInfo / Clearbit

  • All have their own ToS limiting reselling, downstream sharing, and use cases
  • Read your contract — typically you can use the data for your own outreach but not productize it
  • Don't share extracts publicly (e.g., on a leaderboard, in a public report)

Crunchbase

  • Free tier is read-only for personal use
  • Paid tier permits broader use within contractual scope
  • API access requires paid Pro+ tier

Anti-Patterns (Don't Do These)

  1. Bulk-scraping LinkedIn / Google Maps / Yelp. Browser-assisted research is OK; automated scrapers pointed at these platforms are not. Firecrawl and Browserbase are fine for an individual prospect's own website (the URL you found through manual discovery) — not for the platforms hosting prospects.
  2. Buying lists from random vendors without source provenance. You inherit their legal exposure.
  3. Guessing emails and sending unverified. Bounce rates over 2% destroy sender reputation; legally, you can't claim a "legitimate interest" basis for an email you fabricated.
  4. Harvesting personal email addresses (Gmail, personal Outlook, etc.) from public profiles. Personal addresses raise GDPR risk significantly.
  5. Storing data you don't need. Minimize retention. Don't keep prospect lists forever — GDPR right to deletion applies.
  6. Skipping the lawful basis documentation. If challenged, you need to show your work. Capture source URL + collection date for every contact.
  7. Reselling prospect lists. You may not have the right to share them downstream. Read your data provider contracts.
  8. CAPTCHA bypass / login wall bypass. Even if technically possible, this signals bot behavior and violates virtually every ToS.

Quick Audit Checklist

Before shipping a list to the user (or downstream to cold-email):

  • Every contact has a source URL + collection date
  • No contacts sourced from scraped LinkedIn data
  • No Google Maps Place IDs or large Maps-structured data retained
  • Lawful basis documented (legitimate interest test for B2B, or relevant alternative)
  • Email addresses validated (deliverability check before outreach)
  • Personal addresses (Gmail, etc.) flagged or excluded
  • Source provider contracts permit the intended use case
  • Retention plan documented (when to delete)
  • First outreach will include unsubscribe + privacy notice (downstream concern for cold-email skill, but mention it now)