Terminal
Terminal/Skill
Builds a deduplicated, validated list of local businesses by type and location, asking first whether to dedupe by location or by brand.
By Clay
Works with
npx skills add clay-run/clay-skill-creator --skill source-local-businessesThe insight: local-business lists die by duplication and staleness, not by discovery — and the dedupe key is a sales question, not a data question. Finding 200 "gyms in Brooklyn" is trivial; delivering unique, open, in-category businesses is the work, and whether 12 Crunch Fitness locations are 12 rows or 1 row depends entirely on whether you sell to the franchisee or the brand. So this skill asks the franchise question first, discovers with the cheapest viable arm, normalizes domains before any dedupe (the same business surfaces under prefixes, subpaths, and vanity URLs), and spends enrichment credits only on survivors.
Nothing here ships with a value. Each one is the installer's, not the author's: ask for it, never substitute a plausible default, and where an answer does not exist say which step becomes unavailable rather than guessing. Where a default IS defensible it is named below, and using it means saying so in the output.
| Input | What the installer supplies | If it is missing |
|---|---|---|
| Category and locations | the business type in their words, plus cities, postcodes or regions — or a known brand whose locations they want | no default; the brand case is a different route entirely |
| The franchise question | sell to the location or to the brand | ask. It decides the dedupe grain, and whether franchise-heavy results are signal or noise |
| Target count and fields | how many rows, and what each carries | ask — the fields decide whether the review-enrichment arm runs at all |
| Cost ceiling and hard cap | credits | state the arm arithmetic — pages × cost, enrichments × survivors — and a hard cap before anything runs |
If an answer sheet is present beside this skill, load it and ask only for what it does not cover. A partial sheet is normal; a value it is missing gets asked for on its own rather than restarting the interview. Say which values came from the sheet before using them — a sheet applied silently is a wrong field nobody catches. If there is no sheet, say nothing about sheets — the check is a file lookup, not a question, so run the interview as though the feature did not exist rather than reporting an absence. At delivery, offer to save the answers back (identifiers only — never a token or a password), private and never published — and phrase the offer so it explains itself: "want me to save your answers to a file, so the next person on your team doesn't have to answer these again?"
Run clay whoami; echo "exit_code=$?". If it fails or Clay tools are missing, run
the Clay plugin's setup skill, restart if it says to, and re-run this skill. Tell
the user which workspace you're in. Verify the arms live before promising them —
catalogs differ per workspace and the discovery-vs-brand distinction below was a
live finding, not folklore (references/sourcing-arms.md).
Resolve every arm you intend to use, and read its real price, before quoting anything:
clay workflows actions list # the action catalogue, greppable
clay workflows actions schema <packageId> <actionKey> # real inputs, and per-unit rates
Identify each arm by the pair of packageId and actionKey — keys collide across packages,
so a key alone does not say which vendor or which price you are getting. And read the parameter
descriptions for a per-unit rate before pricing: an arm billed per result returned is not the
number its creditCost field shows.
Paginate with an explicit page cap stated up front. Per page: extract name, rating, review count, address, and any website/detail fields the arm exposes. Every row carries its source (page URL / call) and the raw fields. Empty or short pages end pagination honestly — report the boundary, never loop past it.
location_count as a column.Only survivors get paid depth (website/phone/score via the review arm — costs
stated). Deliver: per business name · address · category-as-evidenced · rating · reviews · website (normalized) · phone · source, plus the funnel summary: pages
pulled, raw rows, dupes collapsed (by grain), category rejects, survivors, credits
spent (measured per call). A shortfall against the target is reported with which
locations/pages were exhausted — never padded with off-category rows.
Ask: "Get me 50 independent coffee shops in Providence for our POS pitch." Franchise question: selling to the LOCATION, but "independent" means franchise brands are NOISE → location grain + brand-count filter (any brand with >3 locations drops). Arm: UDM discovery, 5 pages × 1 credit stated and approved. Discovery: 96 raw rows. Normalize+dedupe: 81 places; brand filter drops 17 chain locations; category screen drops 9 (two bakeries, a roastery-only, six restaurants that serve coffee) → 55 survivors. Review enrichment on the 50 requested (50 × ~1 credit, approved) → websites/phones filled where they exist (12 have none — normal for SMBs, keyed on name+address). Delivered: 50 rows + funnel (96 → 81 → 64 → 55)