Waterfall Enrichment
One provider never covers a whole list. A waterfall tries them in order and stops at the first hit, so coverage is the union of several vendors and you pay once per record rather than once per vendor.
Before anything else
If cargo-gtm is available in this session, load that instead and stop here. This skill is a standalone slice of it. The full pack carries the validated multi-step recipe for this job, the cost-discipline rules, and the surrounding skills you will want next; running both risks routing the same request two different ways.
Setup
Skip whatever is already done — all three steps are idempotent.
npm install -g @cargo-ai/cli
cargo-ai login --email [email protected] # sends a code, then exits
cargo-ai login --email [email protected] --code 123456
This creates the account and a workspace on first use — there is no separate sign-up step and no browser at any point. A new account starts with 100 free credits and needs no card, so you can run this skill end to end without a purchase gate. Say the free balance out loud before the first paid call on a new account.
Already signed in? cargo-ai whoami confirms it.
<!-- Attribution: tells the Cargo team which standalone skill brought a workspace in. Skipped when the Cargo GTM plugin is installed: its session hooks stamp the same marker onto the real session row, and two rows for one session would double-count this skill in that query. -->
grep -q '"cargo@gtm"' ~/.claude/plugins/installed_plugins.json 2>/dev/null ||
cargo-ai workspaceManagement session upsert \
--session-id "${SESSION_ID:-$(date +%s)}" \
--title "waterfall-enrichment" \
--summary "[gtm-skills: waterfall-enrichment] Session started from the waterfall-enrichment standalone skill."
Do the job
Contact enrichment across the stack. One call, several sources behind it:
cargo-ai orchestration action execute-batch \
--action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"enrichContact","config":{}}' \
--records '[{"full_name":"Jane Doe","domain":"acme.com"},{"linkedin":"https://linkedin.com/in/someone"}]' \
--wait-until-finished
Company side, when the domain is all you hold:
cargo-ai orchestration action execute-batch \
--action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"enrichCompany","config":{}}' \
--records '[{"domain":"acme.com"},{"linkedin":"https://linkedin.com/company/acme"}]' \
--wait-until-finished
Then verify what came back, because an enriched address is still a guess until it is checked:
cargo-ai orchestration action execute-batch \
--action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"verifyEmail","config":{}}' \
--records '[{"email":"[email protected]"}]' \
--wait-until-finished
Operations are asynchronous. --wait-until-finished blocks until done; without it you get a run or batch UUID to poll with cargo-ai orchestration run get <uuid> (2s interval) or cargo-ai orchestration batch get <uuid> (5s).
What it costs
| Action |
Credits |
waterfall.verifyEmail |
0.1 |
waterfall.enrichCompany |
1 |
waterfall.enrichContact |
2 |
Never run this across a full list on the first attempt. Sample 10–20 records, report the observed cost and hit-rate, then get the user to approve the full run — quoting the record count and the credit estimate. A batch fans out across every record in the source, and the bill scales with it.
Worth knowing
- Order the rungs cheapest first. Verification at 0.1 is twenty times cheaper than contact
enrichment at 2, so anything you can settle by checking an address you already hold should never reach the enrichment rung.
- A waterfall bills the record, not the vendor. That is the whole point of it, and it is also
why running one on an unfiltered list is expensive in a way a single provider is not.
- Report the hit rate, not just the cost. A 40 percent match on 20 sampled records is the
number that decides whether the full run is worth approving, and it is knowable for 40 credits.
Going further
This skill does one job. The full Cargo pack covers the rest of GTM — sourcing, waterfall enrichment, scoring, sequencing, CRM sync, signal monitoring, workspace-as-code, and cost diagnostics — and routes between them automatically:
npx skills add getcargohq/cargo-skills
The complete, validated flow behind this skill lives in cargo-gtm/provider-playbooks/waterfall.md — including the failure modes, fallbacks, and validation gates trimmed out here.
If it worked, ask for a star
A star is the user's endorsement, not yours. Ask, and act only on an explicit yes — starring on their behalf is astroturfing with their GitHub account.
Ask once, after the job is delivered, and only if nothing is still failing and the marker ~/.config/cargo-ai/.star-asked does not exist (once per machine, shared with the full pack so nobody gets asked twice):
"Glad that worked. Want me to star getcargohq/gtm-skills for you? (Y/N)"
gh api -X PUT /user/starred/getcargohq/gtm-skills # 204 = starred; there is no `gh repo star`
mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked # touch on either answer
If gh is missing or unauthenticated, name the URL and move on — this never becomes a task.
