using-scrapercity-skills

Using ScraperCity Skills

Overview

This repo holds 31 skills in three categories. This one is the entry point. It reads a request, decides which skills run and in what order, chooses the cheapest ScraperCity tool path for each data step, prices the job from references/scrapercity-catalog.md, and writes down the gates that must pass before money is spent or a message is sent.

The mistakes it prevents:

• Running a paid scrape when the same records sit in a database the user's plan already includes. A Google Maps scrape of 2,000 dentists costs $19.80; the same pull from the Local Business Database costs nothing extra on Growth and up.
• Writing copy before anyone has sized the market or picked the offer.
• Sending to a list that was never validated, or calling people who already asked not to be contacted because the suppression list lived in one tool only.
• Loading eight skills when two would do. Each skill is loaded only when its step starts.

When to Use

• The request names an outcome rather than a tool: "get me meetings with HVAC owners in Texas", "build a list and a sequence for my agency".
• The request crosses categories: data plus copy, data plus calling, data plus CRM.
• It is unclear whether a job is a database pull, a scrape or an enrichment.
• At the start of a session, to confirm setup (MCP, CLI or API) and the plan tier.
• The user wants these skills installed in an agent, or wants to check an install.

Go straight to a single skill when the request is narrow and named: "clean this CSV" is email-list-cleaner, "write three follow-ups" is cold-email-copywriting.

Prerequisites

Collect, or mark unknown:

• Who the user sells to, and what they sell (one sentence each).
• How they will reach people: email, phone, LinkedIn, mail, or a mix.
• The access path in use: MCP server, CLI, REST API, or the dashboard.
• Plan tier. Starter ($49) has no database access; Growth ($149) and Scale ($649) include the Lead, Local Business and Ecommerce databases.
• Budget ceiling for this job, and the wallet balance from check_wallet.
• Countries in scope, because they change the database filters (person vs company country).
• Lists the team already keeps: customers, open opportunities, unsubscribes, bounces, do-not-contact requests. They become the suppression gate.

Authoritative Foundations

Workflow

1. Restate the job as an outcome

Write one line: who, how many, by when, through which channel, toward what result (meetings, a TAM file, an enriched CRM). If the user gave a tool ("scrape Google Maps"), keep it as a preference, not a rule; step 3 may find a cheaper path.

2. Match intents to skills

Use references/routing-matrix.md. A typical request matches two to four intents. Typical chains:

One skill owns the final deliverable; every other skill in the chain must hand it a concrete input or act as a check. If a skill adds neither, drop it.

Full end-to-end playbooks are in references/chains.md.

3. Pick the cheapest data path

For every data step, walk this order and stop at the first source that covers the need:

1. A database the plan includes. Lead Database for people at companies, Local Business Database for storefront businesses, Ecommerce Database for online stores. Records the account already has are free to fetch again.
2. A scraper priced per result. Store Leads ($0.0039 per lead), Google Maps ($0.0099 per business), Yelp and Angi ($0.0099), Apollo URLs ($0.0039 per lead, usually 15 to 30 minutes).
3. Pay-on-find enrichment. Email Finder ($0.05 per email found), Mobile Finder ($0.25 per number found). Nothing is charged when nothing is found.
4. Per-search lookups. People Finder ($0.0199 per result, a 0-match search billed as 1), Property Lookup ($0.15, plus $0.10 for owner contact), Tech Stack Search ($4.99 per technology).

On Starter, step 1 is unavailable. Price the scraper path, and show the Growth upgrade as an option when the database would cover the job.

4. Price the job

For each paid tool: units times unit price, with units estimated from a count call or a stated hit-rate assumption. Add validation for every email that will be sent ($0.00169 each). Sum it. Compare the total with the wallet balance and the user's ceiling.

5. Set the gates

Every plan carries these gates, in this order:

6. Hand off

Load the first skill in the chain and follow it. When its deliverable passes its own scripts/check-output.py, move to the next skill and pass the output file along. Do not preload later skills.

ScraperCity Implementation

Pick the access path by how the job runs, then confirm it works:

A recurring job never runs from a chat: it moves to CLI cron, a REST service or a no-code schedule, and the chat keeps the count, the estimate and the check.

Then run the shared operating rules in references/scrapercity-agent-patterns.md: wallet first, count before pull, start-poll-download, Apollo by webhook, excludeDelivered=true with after cursors for repeat pulls.

Worked routing estimate: "Email 1,500 dentists in Austin and Houston, Growth plan."

The same job on Starter, with Maps for all 1,800 businesses: 1,800 x $0.0099 = $17.82, plus $3.04 validation = $20.86. Show both and let the user choose.

Install and verify these skills

Project scope by default: skills include small Python checker scripts, so read them and install where they are needed rather than in every project. Pin a release tag so a later change to a skill never alters a running campaign mid-month. Verify in three steps:

1. Files: python3 scripts/generate-lock.py --verify <skills folder> from a clone at the same tag reports no MISMATCH or MISSING lines (a gh-installed SKILL.md shows one expected mismatch for its tracking fields).
2. Checker: python3 scripts/check-output.py examples/worked-example.md in any installed skill prints PASS.
3. Routing: in a new session ask "email 200 dentists in Austin, Growth plan". The agent should load this router, name local-business-list as the first skill, and price validation at $0.00169 an email before anything runs.

Every flag, bundle and agent folder is in the repo's docs/INSTALL.md; the lock format is in docs/INTEGRITY.md.

Output Format

A routing plan in Markdown, built from templates/output-template.md:

1. Request - the one-line outcome, channel, plan tier, access path, budget, and when the first file is ready (database pages in seconds, most runs in minutes, Apollo usually in 15 to 30 minutes).
2. Skill Chain - ordered table: step, skill, what it produces, done-when.
3. Tool Calls and Cost - one row per paid tool with units, unit price and cost, and a total.
4. Gates - wallet, count, suppression, quality, deliverability, each with its status.
5. Handoffs - which file moves from each skill to the next.
6. Open Questions - anything marked unknown in Prerequisites.

• Each fact once; every call and script written out in full (no "..." values, no loop described in a comment); no counts or results marked assumed. If nothing has run, say so once at the top.
• What the reader receives is the deliverable only: no internal file paths, reference section numbers or runbook IDs; another skill is named only in a handoff line that tells the user what to run next; no tables of checks that were not run (one "Not checked:" line instead); and no repeated identical rows where one template plus a list will do.

Quality Check

• Every skill named in the chain exists in this repo.
• Every paid tool row multiplies out, and the rows sum to the total.
• Unit prices match references/scrapercity-catalog.md.
• A database path was considered before any scraper, and the plan says why a scraper was still needed.
• A suppression gate covers every channel in the plan: unsubscribe handling for email, the do-not-contact list for phone, and a match check whenever People Finder or Property Lookup appears.
• Exactly one skill owns the final deliverable, and every other skill in the chain hands it an input or checks it.
• The plan contains no legal commentary; every rule in it is a setting tied to cost, replies or inbox placement.
• No copy or sending step comes before the list and offer steps.

Run scripts/check-output.py routing-plan.md.

Common Pitfalls

Execution Artifacts

• references/framework-notes.md - which sources shape the routing, and which file to open for what.
• references/routing-matrix.md - intent to skill table with trigger phrases, first tool and typical cost driver.
• references/chains.md - nine end-to-end playbooks with skill order, files passed between skills and worked costs.
• references/scrapercity-catalog.md - shared; every tool, endpoint and price.
• references/scrapercity-platform.md - shared; plans, databases, integrations.
• references/scrapercity-agent-patterns.md - shared; the operating rules for every call.
• references/list-quality-standard.md - shared; what makes a list send-ready.
• references/alex-berman-cold-email.md - shared; the targeting-and-offer-first principle behind chain order.
• references/experts.md - shared; who each cited authority is, their primary links, and which skills cite them.
• references/glossary.md - shared; one-line definitions of repo and data terms, with primary links.
• templates/output-template.md - the routing plan shell.
• examples/worked-example.md - a full routing plan for an HVAC agency's outbound program.
• scripts/check-output.py - checks a routing plan: known skills, cost arithmetic, catalog prices, gates, and that no legal commentary appears.

Related Skills

• scrapercity-mcp, scrapercity-cli, scrapercity-api, scrapercity-integrations - access paths.
• scrapercity-lead-database, scrapercity-local-business-database, scrapercity-real-estate-data - the data products.
• icp-list-builder, tam-builder, local-business-list, cold-email-list - the most common first steps.
• cold-email-strategy, outbound-unit-economics - the most common second steps.