lookalike-customer-finder-skill

Lookalike Customer Finder

Pull Epiphan's best customers live from HubSpot and the customer-orders tables, derive an ideal customer profile (ICP) tied to Epiphan verticals (Higher Ed, Courts/Legal, Government, Corporate AV, Healthcare, Houses of Worship, K-12), expand to 100+ net-new lookalike companies via Apollo and Clay, score each 0-100, and gate every company and contact through `qualify_lead` before it appears in the list. Output is a ranked XLSX plus an optional HubSpot list, not a static template. Keywords: `lookalike`, `similar companies`, `target account list`, `ICP`, `expand vertical`

<quick_start> Trigger: "find companies like [customer names]" or "build a lookalike target account list for [vertical]".

Tool order (every call is live; nothing in the list is inferred):

1. Seeds — execute_sql (Epiphan AI; read crm://schema.md first) over hubspot_companies joined to orders: lifecyclestage = 'customer' or device_count >= 1, ranked by order revenue. Fallback: crm_search_customers + crm_get_customer_orders, or hubspot_search_companies when the user names the seeds.
2. ICP derive — apollo_organizations_enrich (or apollo_organizations_bulk_enrich) on each seed for industry, headcount, revenue, tech, growth. Compute the ICP from the returned fields.
3. Expand — apollo_mixed_companies_search with the ICP filters (industry keywords, employee range, USA/Canada), plus search_companies_by_description (Epiphan AI) for description-similarity and Clay find-and-enrich-company for gaps. Target 150+ raw candidates.
4. Gate Q — qualify_lead on every candidate company (and every contact surfaced later). Exclusions, STALE AE LEAD, and ATL/BTL tier come from its verdict only.
5. Score + tier — weighted similarity model below; Tier 1 ≥ 85, Tier 2 70-84, Tier 3 60-69.
6. Decision makers — for Tier 1 only: hubspot_find_contacts_by_role then apollo_mixed_people_api_search with ATL titles; each contact back through qualify_lead.
7. Deliver — write ~/.claude/skill-state/lookalike-customer-finder/<date>-<vertical>.xlsx (ranked sheet + ICP sheet + excluded-by-gate sheet); on request hubspot_create_list + hubspot_update_list_membership (confirm-first). Any outreach copy goes through Gate B then create_draft. </quick_start>

<house_rules> Customer-facing skill. Before output, run the gates in order (details: ~/.claude/skills/epiphan-house-rules-skill/reference/gates.md): S: search_product_catalog (Epiphan AI) or Epiphan Knowledge search before any product claim. B: check_my_copy on every customer-facing string. Q: qualify_lead right after the candidate pull, before tiering/enrichment/drafts. D: outbound text becomes a Gmail draft, never a send. Identifiers (owner IDs, portal, emails, seats) come from reference/identifiers.md in that skill — do not restate them here. On any gate failure follow reference/self-healing.md (retry, degrade with a flag, alert Tim, halt) and append a line to ~/.claude/skill-runs/.jsonl. </house_rules>

<success_criteria>

• Seeds pulled live (SQL or customer-orders MCP); seed list and revenue rank shown in the ICP sheet
• ICP derived from Apollo-enriched seed fields, mapped to an Epiphan vertical and ICP score
• 100+ candidates expanded via Apollo/Clay; raw count and post-gate count both reported
• Every candidate company and contact passed through qualify_lead before tiering; exclusions counted by reason
• Similarity score 0-100 per company with the dimension breakdown visible
• XLSX written to skill-state; HubSpot list only on explicit request
• Outcome sidecar and run-log line written </success_criteria>

Stage 1 — Seed customers (live)

Preferred: one execute_sql query. Read crm://schema.md (or get_schema) before writing it; do not guess column names.

-- strategy: best customers by lifetime order revenue, USA/Canada, with vertical and headcount
SELECT c.id, c.name, c.domain, c.industry, c.numberofemployees, c.country, c.device_count,
       SUM(o.total) AS lifetime_revenue, COUNT(o.id) AS orders
FROM hubspot_companies c
JOIN crm_orders o ON o.hubspot_company_id = c.id
WHERE (c.lifecyclestage = 'customer' OR c.device_count >= 1)
  AND c.country IN ('United States','USA','US','Canada','CA')
GROUP BY c.id ORDER BY lifetime_revenue DESC LIMIT 25;

If the user names the seeds: hubspot_search_companies per name, then crm_get_customer_orders for revenue. Keep 10-25 seeds. Fewer than 5 usable seeds → ask for more or widen to the vertical, mark the run partial (stage: seeds).

Stage 2 — ICP derivation

apollo_organizations_enrich per seed domain (bulk variant for >10). Build the ICP from returned fields only:

Dimension	Source field	Weight
Industry / vertical	industry, keywords → Epiphan vertical	25%
Company size	estimated_num_employees	20%
Tech stack	technologies (Panopto, Kaltura, Zoom, Crestron, etc.)	15%
Growth stage	founded_year, funding events, headcount trend	15%
Geography	country, state (USA/Canada default)	10%
Revenue range	annual_revenue	15%

Record the median/mode per dimension; that is the ICP. Attach the vertical ICP score from CLAUDE.md (Higher Ed 90 … K-12 65) as a tiebreaker.

Stage 3 — Expansion

1. apollo_mixed_companies_search: organization_num_employees_ranges from the ICP, q_organization_keyword_tags from the vertical keywords, organization_locations USA/Canada. Page until ≥ 150 raw candidates or results exhaust.
2. search_companies_by_description (Epiphan AI) with a one-paragraph ICP description → adds companies already in the CRM graph that Apollo misses.
3. Clay find-and-enrich-company for candidates missing headcount/revenue after step 1.

Dedupe on domain before Gate Q.

Stage 4 — Gate Q (mandatory, before scoring)

qualify_lead per candidate company. Keep only verdicts that are net-new and in geo. STALE AE LEAD verdicts go to a separate sheet with the AE name and last-activity date; Tim decides. If qualify_lead is unavailable after one retry, halt: write the raw candidate file to skill-state, alert Tim, no list is produced. Suppression and AE rules are evaluated inside qualify_lead; see reference/gates.md and reference/identifiers.md in epiphan-house-rules-skill rather than restating them here.

Stage 5 — Similarity scoring

Score each surviving company against the ICP with the weights above (0-100). Tiers: Tier 1 85-100, Tier 2 70-84, Tier 3 60-69, drop < 60. Show the per-dimension contribution in the sheet so a low score is explainable.

Stage 6 — Decision makers (Tier 1 only)

hubspot_find_contacts_by_role (role: IT / AV / academic technology leadership) then apollo_mixed_people_api_search with ATL titles for the vertical. Every contact goes through qualify_lead for exclusion and tier; the sheet shows the returned tier badge. Contacts with no verified email stay flagged enrich-needed and are handed to prospect-enrich-skill rather than guessed.

Stage 7 — Deliver

• XLSX: ~/.claude/skill-state/lookalike-customer-finder/<date>-<vertical>.xlsx with sheets Ranked, ICP, Stale AE, Excluded (reason per row).
• Summary in chat: seed count, ICP one-liner, raw → post-gate → tiered counts, top 10 table.
• Optional, confirm-first: hubspot_create_list ("Lookalike ") + hubspot_update_list_membership.
• Any suggested opener for a Tier 1 account: get_writing_style once, check_my_copy per string, then create_draft from the Tim mailbox. Never send.

Cadence, tier playbook, and KPI tracking live in reference/targeting-playbook.md.

Stage 8 — Emit outcome sidecar + run log

Write ~/.claude/skill-analytics/last-outcome-lookalike-customer-finder-skill.json:

{"ts":"[UTC ISO8601]","skill":"lookalike-customer-finder-skill","version":"<frontmatter version>","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"seed_customers_analyzed":[n],"raw_candidates":[n],"excluded_by_qualify":[n],"stale_ae_surfaced":[n],
 "lookalikes_found":[n],"tier1":[n],"tier2":[n],"tier3":[n],"icp_dimensions_scored":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

status partial/error must name the failing stage in error. Append one line to ~/.claude/skill-runs/lookalike-customer-finder-skill.jsonl.

<self_healing> partial = a list was produced but a stage degraded: seeds fell back to user-named companies, Apollo expansion failed after retry (Clay-only), search_companies_by_description empty, XLSX written but HubSpot list skipped. error = fewer than 5 seeds and no vertical to widen to, or qualify_lead unavailable (halt: never emit a list Gate Q has not seen). Ladder per ~/.claude/skills/epiphan-house-rules-skill/reference/self-healing.md: retry once → degrade with a flag → Slack DM Tim → halt with state in ~/.claude/skill-state/lookalike-customer-finder/. </self_healing>

<anti_patterns>

• Inventing seed customers or lookalikes from memory; every row traces to a tool result.
• Re-implementing the Golden Rules or ATL/BTL keyword tables inline; qualify_lead owns the verdict.
• Guessing emails from a domain pattern; unknown contacts go to prospect-enrich-skill.
• Treating the response-rate benchmarks in the playbook as measured; they are illustrative until outcomes.jsonl says otherwise. </anti_patterns>

<reference_guides>

• reference/targeting-playbook.md — tier cadence, KPI tracking, monthly/quarterly refresh
• ~/.claude/skills/epiphan-house-rules-skill/reference/gates.md — Gate Q verdict semantics, geo default
• ~/.claude/skills/epiphan-house-rules-skill/reference/identifiers.md — owner IDs, portal, emails (never restate here)
• Siblings: contact-hunter-skill (point lookups), intent-signal-aggregator-skill (timing), prospect-enrich-skill (phones/emails) </reference_guides>