Build a scored prospect list in minutes — drop 50 accounts, get back research + CSV — Claude Skill

Example Company Research File

Each research subagent writes one markdown file per company to {OUTPUT_DIR}/{company-slug}.md, where {OUTPUT_DIR} is the per-run Desktop directory set up by the main agent in Step 0 (e.g., ~/Desktop/acme_research_2026-04-23/). The YAML frontmatter contains structured fields for report + CSV compilation. The body contains human-readable research.

Template

---
company_name: Acme Inc
website: https://acme.com
product_description: AI-powered inventory management for e-commerce brands
industry: E-commerce / SaaS
target_audience: Mid-market e-commerce brands
key_features: demand forecasting | automated reordering | multi-warehouse sync
icp_fit_score: 8
icp_fit_reasoning: Series A e-commerce SaaS, uses Selenium for scraping, expanding to EU — strong fit
employee_estimate: 50-100
funding_info: Series A, $12M
headquarters: San Francisco, CA
---

## Product
AI-powered inventory management for e-commerce brands. Helps DTC brands
automate reordering and sync across multiple warehouses.

## Research Findings
- **[high]** Checkout optimization for Shopify stores, serving mid-market DTC brands with $5M-$50M revenue (source: acme.com/about)
- **[high]** Series A, $12M raised in Q3 2025 from Sequoia (source: TechCrunch)
- **[medium]** Recently hired 3 data engineers, expanding platform team (source: LinkedIn job posts)
- **[medium]** Uses Selenium for web scraping in their data pipeline (source: careers page)

Field Rules

• YAML frontmatter: All structured fields go here. These are extracted for CSV compilation.
• key_features: Pipe-separated (|) list in YAML, not a JSON array.
• icp_fit_score: Integer 1-10.
• icp_fit_reasoning: One line, references specific findings.
• Body sections: ## Product, ## Research Findings.
• Findings format: - **[confidence]** fact (source: url or description)
• Filename: {OUTPUT_DIR}/{company-slug}.md where slug is lowercase, hyphenated (e.g., acme-inc.md).
• Deduplication: One file per company. If a subagent encounters a company that already has a file, overwrite with richer data.

Writing via Bash Heredoc

Subagents write these files using bash heredoc to avoid security prompts. Use the full literal {OUTPUT_DIR} path — no ~ or $HOME:

cat << 'COMPANY_MD' > {OUTPUT_DIR}/acme-inc.md
---
company_name: Acme Inc
website: https://acme.com
...
---

## Product
...

## Research Findings
...
COMPANY_MD

Use 'COMPANY_MD' (quoted) as the delimiter to prevent shell variable expansion.

IMPORTANT: Write ALL company files in a SINGLE Bash call using chained heredocs to minimize permission prompts.

Company Research — Deep Research Patterns

Overview

This reference defines two research contexts:

1. Self-Research (Step 1) — Deep research on the user's own company to build a strong ICP foundation
2. Target Research (Step 6) — Research each discovered company using Plan→Research→Synthesize

Both use the same 3-phase pattern but with different sub-questions and goals.

Self-Research (User's Company)

This is the most important research in the pipeline. Every downstream decision depends on it.

Sub-Questions

• "What does {company} sell and what specific problem does it solve?"
• "Who are {company}'s existing customers? What industries, company sizes, and use cases?"
• "Who are {company}'s competitors and what differentiates them?"
• "What pricing model does {company} use and who is the typical buyer persona?"
• "What use cases and pain points does {company}'s marketing emphasize?"

Page Discovery

Discover site pages dynamically — do NOT hardcode paths like /about or /customers:

1. Fetch browse cloud fetch --allow-redirects "{company website}/sitemap.xml" — primary source, has ALL pages
2. Scan sitemap URLs for keywords: customer, case-stud, pricing, about, use-case, blog, docs, industry, solution
3. Optionally fetch browse cloud fetch --allow-redirects "{company website}/llms.txt" for page descriptions
4. Pick the 3-5 most relevant URLs from the sitemap and fetch those
5. Sitemap is the source of truth. llms.txt is bonus context but often incomplete.

External Research

• Search: "{company} customers use cases reviews"
• Search: "{company} alternatives competitors vs"
• Fetch 1-2 of the most informative third-party results (G2, blog posts, comparisons)

Synthesis Output

From all findings, produce a company profile:

• Company: name
• Product: what they sell, how it works, key capabilities (2-3 sentences, specific)
• Existing Customers: named customers or customer types found
• Competitors: who they compete with, key differentiators
• Use Cases: broad list of use cases the product serves (NOT tied to one vertical)

Do NOT include ICP, pitch angle, or sub-verticals in the profile. Those are per-run targeting decisions made in Step 2 after the profile is confirmed. The profile is a general-purpose company fact sheet that works regardless of which vertical you target next.

Why This Matters

A thin profile produces generic search queries, weak lead scoring, and cookie-cutter emails. A rich profile with specific customers, competitors, and use cases produces targeted queries, accurate scoring, and emails that reference real pain points.

Target Company Research (Step 6)

Sub-Question Templates

Generate sub-questions from these categories based on the ICP and enrichment fields requested. Not every category applies to every company — pick the most relevant.

Priority 1 (Always ask)

• Product/Market: "What does {company} sell and who are their customers?"
• ICP Fit: "How does {company}'s product/market relate to {sender's ICP description}?"

Priority 2 (Ask in deep/deeper)

• Tech Stack: "What technologies, frameworks, or infrastructure does {company} use?"
• Growth Signals: "Has {company} raised funding, launched products, or expanded recently?"
• Pain Points: "What challenges might {company} face that {sender's product} addresses?"

Priority 3 (Ask in deeper only)

• Decision Makers: "Who leads engineering, product, or growth at {company}?"
• Competitive Landscape: "Who are {company}'s competitors and how are they differentiated?"
• Customers/Case Studies: "Who are {company}'s notable customers and what results do they highlight?"

Search Query Patterns

For each sub-question, generate 2-3 search query variations:

# Product/Market
"{company name} what they do"
"{company name} product features customers"

# Tech Stack
"{company name} tech stack engineering blog"
"{company name} careers software engineer" (job posts reveal stack)

# Growth Signals
"{company name} funding round 2025 2026"
"{company name} launch announcement"
"{company name} hiring"

# Pain Points
"{company name} challenges {relevant domain}"
"{company name} {problem sender solves}"

# Decision Makers
"{company name} VP engineering CTO LinkedIn"
"{company name} head of growth product"

Finding Format

Each finding is a self-contained factual statement tied to a source:

{
  "subQuestion": "What does Acme sell and who are their customers?",
  "fact": "Acme provides checkout optimization for Shopify stores, serving mid-market DTC brands with $5M-$50M revenue",
  "sourceUrl": "https://acme.com/about",
  "sourceTitle": "About Acme - Checkout Optimization",
  "confidence": "high"
}

Confidence levels:

• high: Directly stated on the company's own website or official press
• medium: Inferred from job postings, third-party articles, or indirect signals
• low: Speculative based on industry/category, or from outdated sources

Research Loop Rules

1. Process sub-questions by priority — Priority 1 first, then 2, then 3
2. 3-5 findings per sub-question, then move on — Don't exhaust a topic
3. Use parallel tool calls — Search multiple queries simultaneously when possible
4. Rephrase, don't retry — If a search returns poor results, try different keywords
5. Fetch selectively — Don't fetch every URL from search results. Pick the 1-2 most relevant based on title and URL
6. Stop at step limit — Respect the depth mode's step budget per company
7. Homepage first — Always fetch the company's homepage before branching to other pages
8. Deduplicate findings — Don't record the same fact twice from different sources

Depth Mode Behavior

Quick Mode (100+ leads)

• Skip Phase A — No sub-question decomposition
• Phase B: Fetch the company homepage. Run 1-2 supplementary searches if homepage data is thin.
• Phase C: Extract available data, score ICP, write email from what's available
• Budget: 2-3 total tool calls per company
• Trade-off: Fast and cheap, but emails may be less personalized

Deep Mode (25-50 leads)

• Phase A: Decompose into 2-3 sub-questions (Priority 1 + selected Priority 2)
• Phase B: For each sub-question, run 2-3 searches + fetch 1-2 URLs. Target 3-5 findings per sub-question.
• Phase C: Synthesize from all findings. ICP reasoning references specific evidence. Email uses the most specific/compelling finding.
• Budget: 5-8 total tool calls per company
• Trade-off: Good balance of depth and scale

Deeper Mode (10-25 leads)

• Phase A: Decompose into 4-5 sub-questions (Priority 1 + 2 + selected Priority 3)
• Phase B: Research exhaustively. Fetch multiple pages per company (homepage, about, blog, careers, product pages). Target 3-5 findings per sub-question.
• Phase C: Synthesize with cited evidence. ICP reasoning is detailed. Email references multiple specific signals.
• Budget: 10-15 total tool calls per company
• Trade-off: High quality intelligence, but slow and expensive

Synthesis Instructions

After the research loop completes for a company, synthesize findings into the output record:

ICP Scoring

Score 1-10 using ALL accumulated findings as evidence:

• 8-10: Strong match. Multiple high-confidence findings confirm right industry, company stage, and clear pain point alignment. The pitch angle directly addresses a visible need supported by evidence.
• 5-7: Partial match. Some findings suggest relevance but key signals are missing or low-confidence. Adjacent industry or unclear pain point.
• 1-4: Weak match. Findings indicate wrong segment, too large/small, or no apparent connection to sender's product.

Write icp_fit_reasoning referencing specific findings: "Series A fintech (from Crunchbase), uses Selenium for scraping (from job posting), expanding to EU market (from blog) — strong fit for browser infrastructure."

Email Personalization

Use the richest, most specific findings for email context:

• Opening: Use the most concrete finding (a specific product feature, a recent launch, a job posting)
• Bridge: Connect a finding about their challenges/stack to the sender's pitch angle
• If only low-confidence findings exist, keep the email shorter and more general — don't fabricate specificity

Enrichment Fields

Map findings to enrichment fields:

• product_description → from Product/Market findings
• industry → inferred from Product/Market
• employee_estimate → from LinkedIn search or careers page findings
• funding_info → from Growth Signals findings
• headquarters → from company homepage or about page
• target_audience → from Product/Market findings
• key_features → from product page findings

If a field has no supporting findings, leave it empty rather than guessing.

Anti-Hallucination Rules

Apply these at synthesis time. They exist because the failure mode — especially on Framer/Next.js landing pages with little server-rendered copy — is for the subagent to pattern-match visual cues onto the sender's ICP and fabricate a plausible-sounding description:

1. Typography is not a product. Never infer product_description, industry, or target_audience from fonts, design system, framework choice (Framer, Next.js, React), or site polish. "Framer-built" and "uses Geist Mono" are observations about tooling, not signals of what the company sells.
2. No ICP leakage. If the homepage is thin and external search turns up nothing, do NOT default the target's description toward the sender's ICP. Manufacturing AI ≠ browser automation just because both use AI.
3. Quote, don't paraphrase from memory. product_description must quote or closely paraphrase a specific phrase from extract_page.mjs output (TITLE / META_DESCRIPTION / OG_DESCRIPTION / HEADINGS / BODY) or from an external search result. If no such phrase exists, write Unknown — homepage content not accessible.
4. Cap scores on thin evidence. If product_description is Unknown, set icp_fit_score ≤ 3 and icp_fit_reasoning: Insufficient evidence — homepage returned no readable content. Do not justify a higher score on inferred signals alone.

Company Research — Workflow Reference

Discovery Batch JSON Schema

File: /tmp/company_discovery_batch_{N}.json

browse cloud search --output writes a JSON object (NOT a flat array):

{
  "requestId": "abc123",
  "query": "AI data extraction startups",
  "results": [
    { "url": "https://example.com", "title": "Example Corp", "author": null, "publishedDate": null },
    ...
  ]
}

The list_urls.mjs script handles both formats (flat array and { results: [...] }).

Company Research Markdown Format

File: {OUTPUT_DIR}/{company-slug}.md

Where {OUTPUT_DIR} is the per-run directory on the user's Desktop (e.g., ~/Desktop/acme_research_2026-04-23/). The main agent sets this up in Step 0 and passes the full literal path to every subagent.

Each research subagent writes one markdown file per company. See references/example-research.md for the full template.

YAML frontmatter fields (used for report + CSV compilation):

• company_name (required)
• website (required)
• product_description
• industry
• target_audience
• key_features (pipe-separated: feature1 | feature2 | feature3)
• icp_fit_score (integer 1-10, required)
• icp_fit_reasoning
• employee_estimate
• funding_info
• headquarters

Body sections:

• ## Product — what they do
• ## Research Findings — evidence with confidence levels and sources

CRITICAL: Use consistent field names across all files. The compile_report.mjs script reads these fields.

Extracting Page Content

Use extract_page.mjs for all homepage/product-page content extraction. It fetches via browse cloud fetch --output, parses title + meta + visible body text, and falls back to browse get markdown automatically when fetch fails or returns thin JS-rendered content:

node {SKILL_DIR}/scripts/extract_page.mjs "https://example.com" --max-chars 3000

Output is a structured block:

URL: https://example.com
FETCH_OK: true|false
FALLBACK_TO_BROWSE: true|false
TITLE: ...
META_DESCRIPTION: ...
OG_TITLE: ...
OG_DESCRIPTION: ...
HEADINGS: h1/h2/h3 joined by " | "
BODY_CHARS: N
BODY:
<cleaned visible text, max N chars>

Why not a raw browse cloud fetch | sed pipeline? Without --output, browse cloud fetch returns a JSON envelope with the HTML embedded as an escaped string. A naive sed pipeline strips <> from the wrapper and content, and it removes <meta> tags, which on Framer/Next.js SPAs are often the only readable content. extract_page.mjs uses --output to parse raw HTML directly.

When to use raw browse cloud fetch: Only for small structured files where you want the JSON envelope intact — e.g. sitemap.xml, robots.txt, llms.txt. For any HTML page you'd feed to a model, use extract_page.mjs.

Verifying content is real (not hallucinated)

Before writing product_description, industry, or target_audience into a company file, confirm the claim is grounded in extract_page.mjs output. Quote or closely paraphrase from TITLE, META_DESCRIPTION, OG_DESCRIPTION, HEADINGS, or BODY.

If extract_page.mjs returns FETCH_OK: false AND FALLBACK_TO_BROWSE: false (or BODY_CHARS < 50), the homepage is inaccessible. Do not fabricate. Write:

• product_description: Unknown — homepage content not accessible
• icp_fit_score: 3 (or lower)
• icp_fit_reasoning: Insufficient evidence — homepage returned no readable content

A classic failure mode this prevents: a Framer/Next.js landing page with no server-rendered copy, where the subagent pattern-matches visual cues ("design-forward", "Geist Mono", "Framer-built") onto the user's own ICP. Typography is not a product.

Discovery Subagent Prompt Template

You are a company discovery subagent. Run search queries and save results.

TOOL RULES — CRITICAL, FOLLOW EXACTLY:
1. You may ONLY use the Bash tool. No exceptions.
2. Run ALL searches in a SINGLE Bash call using && chaining.
3. BANNED TOOLS: WebFetch, WebSearch, Write, Read, Glob, Grep — ALL BANNED.
   If you use ANY banned tool, the entire run fails. Use ONLY Bash.
4. NEVER use ~ or $HOME in paths — use full literal paths.

TASK:
Run ALL of the following searches in ONE Bash command:

browse cloud search "{query1}" --num-results 25 --output /tmp/company_discovery_batch_{N1}.json && \
browse cloud search "{query2}" --num-results 25 --output /tmp/company_discovery_batch_{N2}.json && \
browse cloud search "{query3}" --num-results 25 --output /tmp/company_discovery_batch_{N3}.json && \
echo "Discovery complete"

After the command completes, report back ONLY the count of results found per batch.
Do NOT analyze, summarize, or return the actual results.

Research Subagent Prompt Template

You are a company research subagent. For each company URL, research the company and score ICP fit.

CONTEXT:
- User's company: {user_company}
- User's product: {user_product}
- ICP description: {icp_description}
- Depth mode: {depth_mode}
- Output directory: {OUTPUT_DIR}   ← write research files HERE, as a full literal path

URLS TO PROCESS:
{url_list}

TOOL RULES — CRITICAL, FOLLOW EXACTLY:
1. You may ONLY use the Bash tool. No exceptions.
2. All searches: Bash → browse cloud search "..." --num-results 10
3. All homepage/product-page content extraction:
   Bash → node {SKILL_DIR}/scripts/extract_page.mjs "URL" --max-chars 3000
   This returns structured TITLE / META_DESCRIPTION / OG_DESCRIPTION / HEADINGS / BODY and auto-falls back to browse get markdown when fetch fails or returns thin JS-rendered content.
   DO NOT hand-roll a `browse cloud fetch | sed` pipeline — it strips meta tags and doesn't parse the stdout JSON envelope. Use `browse cloud fetch` raw only for sitemap.xml, robots.txt, llms.txt.
4. BATCH all file writes: Write ALL markdown files in a SINGLE Bash call using chained heredocs (one permission prompt, not one per file).
5. BANNED TOOLS: WebFetch, WebSearch, Write, Read, Glob, Grep — ALL BANNED.
   If you use ANY banned tool, the entire run fails. Use ONLY Bash.
6. NEVER use ~ or $HOME in paths — use full literal paths.

ANTI-HALLUCINATION RULES — CRITICAL:
- NEVER infer product_description, industry, or target_audience from fonts, framework (Framer/Next.js/React), design system, or visual style. Typography is not a product.
- NEVER let the sender's ICP leak into a target's description. If you don't know what the target does, write "Unknown" — do not pattern-match them onto the ICP.
- product_description MUST quote or closely paraphrase a phrase from extract_page.mjs output. If none of TITLE/META/OG/HEADINGS/BODY yield a recognizable product statement, write "Unknown — homepage content not accessible" and cap icp_fit_score at 3.

RESEARCH PATTERN (per company):

Phase A — Plan (skip in quick mode):
Decompose what you need to know into sub-questions based on ICP and enrichment fields.

Phase B — Research Loop:
For each sub-question (or just the homepage in quick mode):
1. Run browse cloud search with relevant query
2. Pick 1-2 most relevant URLs from results
3. Extract page content: node {SKILL_DIR}/scripts/extract_page.mjs "URL" --max-chars 3000
   (uses `--output` to avoid the stdout JSON envelope, preserves meta tags, and falls back to browse get markdown when needed)
4. Smart page discovery: use `browse cloud fetch --allow-redirects` on /sitemap.xml or /llms.txt to find relevant URLs — these are small XML/text files where the raw JSON envelope is fine. For the actual HTML pages you discover, use extract_page.mjs.
5. Extract findings: factual statements with source, confidence level
6. Accumulate findings, move to next sub-question
7. Respect step budget: quick=2-3 calls, deep=5-8, deeper=10-15

Phase C — Synthesize:
From accumulated findings:
1. Score ICP fit 1-10 (see rubric below)
2. Fill enrichment fields from findings
3. Reference specific findings in icp_fit_reasoning

ICP SCORING RUBRIC:
- 8-10: Strong match. Multiple high-confidence findings confirm fit.
- 5-7: Partial match. Some findings suggest relevance but key signals missing.
- 1-4: Weak match. Wrong segment or no apparent connection.

OUTPUT — write ALL company files in a SINGLE Bash call using chained heredocs directly to {OUTPUT_DIR}:

cat << 'COMPANY_MD' > {OUTPUT_DIR}/{slug1}.md
---
company_name: {name}
website: {url}
product_description: {description}
industry: {industry}
target_audience: {audience}
key_features: {feature1} | {feature2} | {feature3}
icp_fit_score: {score}
icp_fit_reasoning: {reasoning}
employee_estimate: {estimate}
funding_info: {funding}
headquarters: {location}
---

## Product
{product description paragraph}

## Research Findings
- **[{confidence}]** {finding} (source: {url})
COMPANY_MD
cat << 'COMPANY_MD' > {OUTPUT_DIR}/{slug2}.md
---
...
---
...
COMPANY_MD

Use 'COMPANY_MD' (quoted) as the heredoc delimiter to prevent shell variable expansion.

Report back ONLY: "Batch {batch_id}: {succeeded}/{total} researched, {findings_count} total findings."
Do NOT return raw data to the main conversation.

Wave Management

Key Principle: Maximize Parallelism, Minimize Prompts

Launch as many subagents as possible in a single message (up to ~6 Agent tool calls per message). Each subagent MUST batch all its Bash operations to minimize permission prompts.

Discovery Phase

• Launch up to 6 discovery subagents in a single message
• Each subagent runs ALL its queries in a SINGLE Bash call using && chaining
• After all waves complete, run node {SKILL_DIR}/scripts/list_urls.mjs /tmp
• Filter URLs: Remove blog posts, news articles, directories, competitors, and existing customers. Keep only company homepages.

Research Phase

• Companies per subagent varies by depth:
  • quick: ~10 companies per subagent
  • deep: ~5 companies per subagent
  • deeper: ~2-3 companies per subagent
• Each subagent writes ALL its markdown files in a SINGLE Bash call (chained heredocs) directly to {OUTPUT_DIR}

Sizing Formula

search_queries = ceil(requested_companies / 35)
discovery_subagents = search_queries
expected_urls = search_queries * 20

quick:  research_subagents = ceil(expected_urls / 10)
deep:   research_subagents = ceil(expected_urls / 5)
deeper: research_subagents = ceil(expected_urls / 3)

Error Handling

• If a subagent fails, log the error and continue with remaining batches
• If >50% of subagents fail in a wave, pause and inform the user
• extract_page.mjs already handles the browse cloud fetch → browse get markdown fallback internally. If it still returns FETCH_OK: false with empty BODY, skip the company and mark product_description as Unknown (do not guess).

Report + CSV Compilation

After all research subagents complete, compile the HTML report and CSV in one command:

node {SKILL_DIR}/scripts/compile_report.mjs {OUTPUT_DIR} --open

The script:

• Reads all .md files in {OUTPUT_DIR}
• Parses YAML frontmatter + body sections
• Deduplicates by normalized company name (keeps highest ICP score)
• Generates {OUTPUT_DIR}/index.html — scored overview page
• Generates {OUTPUT_DIR}/companies/{slug}.html — one page per company
• Generates {OUTPUT_DIR}/results.csv — spreadsheet for sheets/CRM
• Opens index.html in the default browser (--open flag)
• Prints a JSON summary to stderr