agentleFS
NimblewayNimbleway/agent-skills/skills/market-finder/SKILL.md

market-finder

Skill74 starsChanged 3 months agoMITView on GitHub

Discovers all businesses of a given type in any geography using Nimble WSAs. Two modes: Discovery finds businesses from scratch; Audit compares a user's existing list (Google Sheet, CSV, inline) against fresh discovery, categorizing entries as matched, discovered-only, or reference-only. Vertical presets (Healthcare, SaaS, Restaurants, Legal, Auto/Home) auto-select WSA routing.

The file

Show its rules and text

We split this skill into the rules it gives an agent

35 rules. About 0 are common, 17 are distinctive, and 18 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 18

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the …

    line 57
  2. Very specific:

    Check for existing checkpoints: ls ~/.nimble/memory/market-finder/checkpoints/ 2>/dev/null

    line 61
  3. Distinctive:

    No profile -> fine. Market-finder doesn't require onboarding.

    line 69
  4. Very specific:

    Check $ARGUMENTS for a reference list.

    line 77
  5. Distinctive:

    If a reference list is present but intent is ambiguous, ask: "Want me to audit your list against fresh discovery, or use it as a starting …

    line 86
  6. Distinctive:

    If audit language is detected but no reference list is provided, ask: "You mentioned auditing — please provide your list (Google Sheet URL, …

    line 89
  7. Distinctive:

    Do not proceed with Audit mode until a reference list is received.

    line 91
  8. Distinctive:

    Use AskUserQuestion with up to 3 questions:

    line 110
  9. Very specific:

    Read references/vertical-presets.md and match the user's business type against preset trigger keywords.

    line 127
  10. Very specific:

    Follow the Checkpointing & Resume pattern from references/memory-and-distribution.md.

    line 166
  11. Distinctive:

    Run these searches simultaneously (one per target domain).

    line 184
  12. Very specific:

    Prefer managed_by: "nimble" over managed_by: "community"

    line 186
  13. Very specific:

    If no WSA found for a domain, mark it for nimble search fallback

    line 187
  14. Very specific:

    If no WSAs found for ANY domain, fall back entirely to nimble search for all metros

    line 188
  15. Distinctive:

    Run tertiary domain WSAs only if the preset includes them AND primary + secondary return < 10 combined unique results for that metro.

    line 208
  16. Distinctive:

    If no WSA was found for a target domain, or if a WSA fails for any metro:

    line 226
  17. Very specific:

    Run enrichment using the WSAs discovered in Step 5a for the preset's enrichment target domains.

    line 240
  18. Very specific:

    Only run enrichment WSAs that apply to the current vertical's enrichment targets (see references/vertical-presets.md).

    line 248
  19. Distinctive:

    Source found: Use the sourced amount and date

    line 264
  20. Very specific:

    Final deduplication: Run a final dedup pass across all phases following the Entity Deduplication pattern from references/nimble-playbook.md.

    line 272
  21. Very specific:

    Read references/audit-mode.md for the full matching algorithm, normalization rules, and output template.

    line 300
  22. Distinctive:

    Source links are mandatory: Every entity must have at least one clickable source URL (Google Maps link, Yelp listing, website, BBB profile, …

    line 367
  23. Very specific:

    Use the audit output template from references/audit-mode.md.

    line 371
  24. Very specific:

    Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a …

    line 391
  25. Very specific:

    Always offer distribution -- do not skip this step: Follow references/memory-and-distribution.md for connector detection, sharing flow, and …

    line 397
  26. Very specific:

    Use nimble-researcher agents (agents/nimble-researcher.md) when:

    line 438
  27. Very specific:

    Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, fallback on failure).

    line 442
  28. Very specific:

    Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

    line 449
  29. Distinctive:

    Discovery teammate(s): Run all discovery WSAs across metro batches

    line 453
  30. Distinctive:

    Enrichment teammate: Run enrichment WSAs for top entities

    line 454
  31. Distinctive:

    Don't abort the entire job for one empty metro.

    line 472
  32. Distinctive:

    SaaS with geography: If the selected preset has no geo-tiling but the user specified a geography, offer it as a search qualifier instead.

    line 475
  33. Distinctive:

    Reference list parse failure: If Google Sheet extraction returns garbage or CSV is malformed, ask the user to paste the data inline instead.

    line 477
  34. Distinctive:

    Empty reference list: If parsed list has 0 valid records, warn and offer to switch to Discovery mode.

    line 479
  35. Distinctive:

    No matches found: If all three matching layers produce zero matches, report it — a 0% coverage score is valid and informative.

    line 481

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Market Finder

Market intelligence powered by Nimble Web Search Agents.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously:

  • mkdir -p ~/.nimble/memory/{reports,market-finder/checkpoints}
  • Check for existing checkpoints: ls ~/.nimble/memory/market-finder/checkpoints/ 2>/dev/null

From the results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note industry keywords if any. Apply smart date windowing from references/nimble-playbook.md. Market-finder tweak: in quick refresh mode, skip enrichment and only discover new metros.
  • No profile -> fine. Market-finder doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Request & Detect Mode

Parse $ARGUMENTS for business type, geography, qualifiers, and mode detection.

Mode detection

Check $ARGUMENTS for a reference list. Read references/audit-mode.md for the full detection signals and parsing rules.

SignalMode
Google Sheet URL, CSV path, or inline list of 3+ businessesAudit
Explicit audit language ("audit my list", "compare against", "gap analysis")Audit
No reference list providedDiscovery (default)

If a reference list is present but intent is ambiguous, ask: "Want me to audit your list against fresh discovery, or use it as a starting point?"

If audit language is detected but no reference list is provided, ask: "You mentioned auditing — please provide your list (Google Sheet URL, CSV file path, or paste inline)." Do not proceed with Audit mode until a reference list is received.

Extract fields

FieldRequiredSource
Business type / verticalYesUser input ("dentists", "SaaS CRM tools")
GeographyYes (except SaaS)User input ("Florida", "Austin TX", "nationwide")
Reference listAudit mode onlyGoogle Sheet URL, CSV path, or inline
Qualification criteriaOptionalUser input ("must have website", "10+ reviews")
Output preferenceOptionalUser input ("quick summary", "full dataset")

If both type and geography are clear from $ARGUMENTS, confirm briefly and proceed: "Finding dentists in Florida..." (or "Auditing your list against dentists in Florida..." in Audit mode)

If partial or ambiguous, ask one combined question (counts as 1 of max 2 AskUserQuestion prompts):

Use AskUserQuestion with up to 3 questions:

  1. Vertical -- "What type of business?" with options: Healthcare, SaaS/Software, Restaurants/Food, Legal/Financial, Auto/Home Services, Other
  2. Geography -- "What geography?" (free text or: City, State, Region, Nationwide)
  3. Depth -- "Quick scan or comprehensive discovery?"

Skip questions already answered by $ARGUMENTS.

Depth modes (determines how much work each step does):

DepthDiscoveryEnrichmentVerificationDistribution
Quick scanAll sources, 1 passSkip (or top 5 only)Top 5 entitiesOffer
ComprehensiveAll sources + fallback retriesFullAll entitiesOffer

Step 2: Vertical Detection & Preset Loading

Read references/vertical-presets.md and match the user's business type against preset trigger keywords.

MatchAction
Clear matchLoad that preset's WSA routing and query pattern
Partial matchConfirm: "This looks like Healthcare. Use healthcare presets?"
No matchUse Custom preset with user's keywords
SaaS matchSwitch to non-geographic pipeline (no geo-tiling)

Note which discovery WSAs and enrichment WSAs the preset specifies.

Step 3: Geographic Scoping

Skip this step for SaaS vertical (no geography needed).

Geography levelTiling strategy
CitySingle query, no tiling
Metro areaSingle query per WSA
StateTile by top 5-10 metros in the state
RegionTile by states, then top metros per state
NationwideTile by all states, then top metros per state

Estimate API calls: metros * discovery_wsas * (1 + enrichment_ratio) where enrichment_ratio is ~0.3. Follow the Scaled Execution pattern from references/nimble-playbook.md to choose execution tier (individual / batch / multi-batch / confirmation gate):

Estimated API calls: ~1,560 (50 states x 8 metros x 3 WSAs + enrichment)
This is a nationwide search. Proceed? [Y/n]

Derive a slug for checkpointing: lowercase, hyphenated, includes vertical + geo (e.g., dentists-florida, saas-crm-tools, hvac-nationwide).

Step 4: Check for Existing Checkpoint

Follow the Checkpointing & Resume pattern from references/memory-and-distribution.md.

Check: cat ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json 2>/dev/null

  • Checkpoint found -> offer: "Found previous run ({N} entities from {date}). Resume and fill gaps, or start fresh?"
  • No checkpoint -> proceed to Step 5

Step 5: WSA Discovery & Execution

5a: Discover available WSAs

For each target domain in the selected vertical preset, discover current WSAs:

nimble extract:templates list --limit 100  # then filter items for "{domain}"

Run these searches simultaneously (one per target domain). From the results:

  1. Filter by entity_type (SERP for discovery, PDP/Profile for enrichment)
  2. Prefer managed_by: "nimble" over managed_by: "community"
  3. If no WSA found for a domain, mark it for nimble search fallback
  4. If no WSAs found for ANY domain, fall back entirely to nimble search for all metros

Then validate each discovered WSA's input params:

nimble extract:templates get --extract-template-name {discovered_name}

Cache the discovered WSA names + params for the rest of the run.

5b: Geographic discovery (all except SaaS)

For each metro in the tiling plan, run the discovered WSAs simultaneously:

nimble extract:templates run --template {maps_wsa} --params '{...validated params...}'
nimble extract:templates run --template {yelp_wsa} --params '{...validated params...}'

Run tertiary domain WSAs only if the preset includes them AND primary + secondary return < 10 combined unique results for that metro.

Choose execution tier per the Scaled Execution pattern in references/nimble-playbook.md (based on total estimated calls from Step 3).

5c: SaaS discovery (non-geographic)

SaaS skips WSA discovery. Run the two-pass search queries defined in the SaaS preset from references/vertical-presets.md:

  • Pass 1 -- Product discovery: G2, Capterra, general, ProductHunt, GitHub
  • Pass 2 -- Financial discovery: Crunchbase, funding news, market landscape

Both passes run simultaneously. Pass 2 is critical -- without it, funding and traction data will be missing or wrong.

5d: Fallback

If no WSA was found for a target domain, or if a WSA fails for any metro:

nimble search --query "[type] in [metro]" --max-results 20 --search-depth lite

After discovery:

  1. Parse all results into a unified entity list
  2. Deduplicate following the Entity Deduplication pattern from references/nimble-playbook.md: place_id -> domain -> fuzzy name + city
  3. Track source_count per entity (how many WSAs/sources found it)
  4. Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json

Step 6: Enrichment

Run enrichment using the WSAs discovered in Step 5a for the preset's enrichment target domains. Prioritize entities with the highest source count first. Choose execution tier per Scaled Execution in references/nimble-playbook.md.

nimble extract:templates run --template {enrichment_wsa} --params '{...validated params...}'

Only run enrichment WSAs that apply to the current vertical's enrichment targets (see references/vertical-presets.md). Skip entities without the required ID/URL for the enrichment WSA.

Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/enrichment.json

Step 6b: Financial Verification (SaaS vertical)

For SaaS entities, verify funding claims before reporting. Never label a company's funding stage without a source.

For each entity in the top results (top 5 in quick scan, all in comprehensive):

nimble search --query "{company name} funding raised series" --max-results 5 --search-depth lite
  • Source found: Use the sourced amount and date
  • No source found: Display "Undisclosed" -- never guess "Early stage" or "Bootstrapped"

This step prevents publishing unverified financial claims. It's fast (one search per entity, lite depth) and catches recent funding rounds that directory sites miss.

Step 7: Deduplication & Scoring

Final deduplication: Run a final dedup pass across all phases following the Entity Deduplication pattern from references/nimble-playbook.md. Merge fields from multiple sources into a single record per entity.

Discovery strength scoring (skill-specific, varies by vertical):

Geographic verticals (Healthcare, Restaurants, Legal, Auto/Home, Custom):

LevelCriteria
High3+ sources OR 2+ sources with reviews > 50
Medium2 sources OR 1 source with reviews > 10
Low1 source only, few/no reviews

SaaS vertical (funding + directory presence matter more than review count):

LevelCriteria
HighVerified funding > $10M OR 3+ directory sources OR 1000+ G2 reviews
MediumVerified funding < $10M OR 2 sources OR 100+ G2 reviews
Low1 source only, no verified funding, few reviews

Display as: *** High, ** Medium, * Low

Step 7b: Audit Comparison (Audit mode only)

Skip this step in Discovery mode.

Read references/audit-mode.md for the full matching algorithm, normalization rules, and output template.

  1. Parse reference list — detect format (Google Sheet / CSV / inline), extract records, normalize to {name, domain, city, state, phone} per the parsing rules in references/audit-mode.md
  2. Run three matching layers in order (domain → name+city → phone). Once an entity matches at any layer, stop. Track which layer produced the match.
  3. Categorize every entity:
    • matched — in both reference list and discovery results
    • discovered_only — found by discovery, not in reference list
    • reference_only — in reference list, not found by discovery
  4. Calculate coverage score — matched / reference_count × 100

Proceed to Step 8 with the categorized results.

Step 8: Output

# Market Finder: [Business Type] in [Geography]
*Found [N] businesses | [Date] | Strength: [H] High, [M] Medium, [L] Low*

## Summary
- **Total discovered:** [N] unique businesses across [M] metros
- **Geographic breakdown:** [top 5 metros by count]
- **Source coverage:** [list each source used with entity counts]

## Top Results (High Strength)

| # | Name | Location | Rating | Reviews | Strength | Sources |
|---|------|----------|--------|---------|----------|---------|
| 1 | Acme Dental | Miami, FL | 4.8 | 312 | *** High | Maps, Yelp, BBB |
| 2 | WidgetCo Health | Orlando, FL | 4.6 | 89 | *** High | Maps, Yelp |
...

## All Results by Geography

### Miami, FL ([n] businesses)
[Table of businesses in this metro]

### Orlando, FL ([n] businesses)
[Table of businesses in this metro]
...

## What's Missing
[Data gaps: metros with low coverage, entities without websites, etc.]

SaaS output variant (when vertical is SaaS, replace "All Results by Geography" with tier-based grouping):

## Players by Tier

### Pure-Play (dedicated to this vertical)
| # | Name | Domain | Funding | Key Metric | Strength | Sources |
...

### Adjacent (feature overlap from larger platforms)
| # | Name | Domain | Funding | Key Metric | Strength | Sources |
...

### Open Source
| # | Name | Repo | Stars | Key Metric | Strength | Sources |
...

Source links are mandatory. Every entity must have at least one clickable source URL (Google Maps link, Yelp listing, website, BBB profile, G2 page, or GitHub repo).

Audit output variant (when in Audit mode, replace the Discovery output above): Use the audit output template from references/audit-mode.md. Key sections: Summary with coverage score, Matched table, Discovered Only table (expansion candidates), Reference Only table (coverage gaps), and "What This Means" interpretation.

Step 9: Save to Memory

Make all Write calls simultaneously:

Discovery mode:

  • Report -> ~/.nimble/memory/reports/market-finder-{slug}-{date}.md
  • Entity data -> ~/.nimble/memory/market-finder/{slug}/entities.json

Audit mode:

  • Report -> ~/.nimble/memory/reports/market-finder-audit-{slug}-{date}.md
  • Structured data -> ~/.nimble/memory/market-finder/{slug}/audit-{date}.json (all three categories with match metadata)

Both modes:

  • Profile -> update last_runs.market-finder in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Step 10: Share & Distribute

Always offer distribution -- do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Notion: full results table as a dated subpage. Slack: TL;DR with total count + top 10 entities only.

Step 11: Follow-ups

Discovery mode follow-ups:

  • "Tell me more about #N" -> show full detail for that entity
  • "Filter by [criteria]" -> re-filter existing results
  • "Expand to [new geography]" -> add metros and re-run discovery
  • "Export as CSV" -> generate CSV from entities.json
  • "Run enrichment on all" -> extend enrichment beyond top entities
  • "Audit against my existing list" -> switch to Audit mode with this run's results
  • "Looks good" -> done

Audit mode follow-ups:

  • "Export discovered-only as CSV for outreach?" -> CSV of expansion candidates
  • "Investigate reference-only gaps?" -> targeted searches for reference_only entries
  • "Run company-deep-dive on new discoveries?" -> deep research on discovered_only
  • "Re-run with a different geography?" -> audit the same list against a new area
  • "Looks good" -> done

Sibling skill suggestions:

Next steps:

  • Run company-deep-dive for a full 360 profile on any business from this list
  • Run competitor-positioning to compare top players in this market
  • Run local-places for neighborhood-level discovery with social enrichment and maps

Sub-Agent Strategy

For large jobs, nimble extract:templates batch handles WSA parallelism server-side (see Scaled Execution in references/nimble-playbook.md). Sub-agents are useful for preparing batch inputs and processing results, not for running individual WSA calls.

Use nimble-researcher agents (agents/nimble-researcher.md) when:

  • Building metro query lists for large geographies (one agent per state)
  • Processing and deduplicating batch results in parallel

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, fallback on failure).


Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn teammates for parallel phases:

  • Discovery teammate(s): Run all discovery WSAs across metro batches
  • Enrichment teammate: Run enrichment WSAs for top entities
  • Lead (you): Coordinate, scope, deduplicate, score, generate output

Solo mode (flag not set): Standard sequential flow from Steps 5-8.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • WSA not found: Skip silently and rely on other discovery sources. Log which WSAs were unavailable.
  • Search 500/timeout: Retry once without --focus flag. If still failing, retry with a simplified query. Log the failure but don't skip the entire search category -- partial data is better than none.
  • No results for metro: "No [type] found in [metro]. Skipping to next metro." Don't abort the entire job for one empty metro.
  • Ambiguous business type: "Did you mean [option A] or [option B]?" (e.g., "practice" could be medical, dental, legal)
  • SaaS with geography: If the selected preset has no geo-tiling but the user specified a geography, offer it as a search qualifier instead.
  • Reference list parse failure: If Google Sheet extraction returns garbage or CSV is malformed, ask the user to paste the data inline instead.
  • Empty reference list: If parsed list has 0 valid records, warn and offer to switch to Discovery mode.
  • No matches found: If all three matching layers produce zero matches, report it — a 0% coverage score is valid and informative.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.