Blog/

Waterfall Enrichment Skill for Claude Code: How to Build One

A waterfall enrichment skill for Claude Code is a SKILL.md file that encodes the rules of a data enrichment waterfall (which provider to try first, what counts as a found field, when to stop, and what to do when two providers disagree) so Claude Code applies that logic consistently instead of you re-explaining it in every session.

This guide is for RevOps, sales operations, and founders who already run (or want to run) a multi-provider enrichment waterfall and are deciding whether a Claude Code skill is the right place to put that logic. It covers what waterfall enrichment actually is, how to write the skill step by step, and the one part of the job a skill cannot do on its own.

What is waterfall enrichment?

Waterfall enrichment is a data enrichment pattern that sends each record through a sequence of providers, one after another, and stops at the first one that returns a usable, verified value for the field you need. If the first provider in line does not have (or cannot verify) an email or phone number for a contact, the record falls through to the next provider, and the next, until a result is found or the list of providers is exhausted.

The reason this pattern exists at all: no single data provider has complete coverage. Different providers specialize in different regions, industries, and company sizes, so a waterfall combines several partial databases into a result that is more complete than any one of them alone, in exchange for doing more than one lookup per record.

A waterfall is defined by a small number of rules:

  • Provider order, usually cheapest or most-trusted first, so you only pay for a second or third lookup on the records the first provider missed.
  • A stop condition per field, typically "stop once a value is returned and passes verification" rather than just "stop once a value is returned."
  • A conflict rule, for when two providers in the sequence return different values for the same field (most recently verified wins, a fixed provider priority wins, or majority vote).
  • A budget or attempt cap, so a record that no provider can fill does not get queried against every remaining source at full cost.

How does a Claude Code skill actually work?

A skill is not code that executes; it is an instruction file that Claude Code reads and reasons from, stored as SKILL.md inside a folder (.claude/skills/<name>/ for one project, ~/.claude/skills/<name>/ for every project on your machine). Two parts make it work: a description field in the frontmatter, which Claude Code scans across every available skill to decide which one matches the current request (specific and literal beats vague), and the body, plain-English instructions and examples that Claude Code follows the way it would follow a detailed prompt, except the prompt is saved and reused instead of retyped. Anthropic's own guidance recommends keeping that body under 500 lines and moving longer reference material into separate files the skill links to, so Claude only loads the detail when it needs it.

A skill folder can also hold a scripts/ folder for code that runs rather than gets read. For a waterfall skill, that split matters: the ordering and stopping rules belong in SKILL.md; a long, changing list of provider API details belongs in a reference file the skill links to, not inline.

How do you write a waterfall enrichment skill, step by step?

  1. Write the description first, stating exactly when the skill should fire, for example: "Enriches a list of contacts or companies by running each record through a provider waterfall until every required field is found or verified. Use when asked to fill in missing email, phone, or firmographic fields." Specificity here is what keeps the skill from firing on unrelated requests.
  2. List only the fields you actually need. A skill that backfills ten fields per record runs the waterfall ten times longer than one scoped to the two or three fields the next step in your workflow depends on.
  3. Write the provider order as an explicit, numbered list, with the field each provider is trusted for. Claude Code cannot infer an order you have not written down; without it, it will either ask or guess.
  4. State the stop condition precisely. "Stop once found" and "stop once found and verified" produce different outputs for the same input, and "verified" needs its own definition per field (a valid format is not the same as a confirmed-deliverable address).
  5. State the conflict rule and the budget in the same breath: which provider wins when two disagree, and the maximum number of providers to try before a field is left empty rather than guessed.
  6. Separate the rules from the data. Describe how to run a waterfall; do not hardcode a contact list or a live credential inside the file, since both go stale and then need maintaining everywhere the skill is copied.
  7. Test it on a real, messy batch, including records you already know are hard to enrich, and tighten the stop and conflict rules wherever the output does not match what you would have decided by hand.

A minimal example of the core rules section:

---
name: enrich-contact-waterfall
description: Runs a contact through a fixed provider order to fill a missing
  email or direct phone number, stopping at the first verified result. Use
  when asked to enrich or backfill contact fields for a list of people.
---

Given a contact (name + company domain) and the fields still missing:
1. Try Provider A first for email, Provider B first for direct phone.
2. A result counts as found only if it passes format AND deliverability
   verification; a value that only passes format checks does not stop
   the waterfall.
3. If not found and verified, try the next provider in the list for that
   field. Try at most 3 providers per field per contact.
4. If two providers return different verified values for the same field,
   keep the one verified most recently.
5. If no provider returns a verified value after 3 attempts, output the
   field as empty. Do not output an unverified guess.

What should a waterfall enrichment skill not try to do on its own?

A skill is an instruction layer, not a connection to a provider's API. It tells Claude Code the order to try providers in and when to stop; it does not, by itself, give Claude Code the ability to actually query those providers. Without that wiring (an MCP server or a script the skill calls), Claude Code has no live data to apply the waterfall rules to, and asking it to "enrich this list" produces values reasoned from training data rather than a real lookup, indistinguishable from a wrong answer until someone checks it.

This is the same structural gap that shows up in other Claude Code skills for GTM work: the instructions can be exactly right and the output still wrong, because the input was Claude guessing rather than Claude looking something up. The outbound skill for Claude Code guide covers the same problem from the account-research side; the fix in both cases is connecting the skill's logic to a real, live tool before the rules ever run, not rewriting the rules.

The fields worth waterfalling through providers also keep expanding past firmographics and contact details. If part of your ICP depends on social activity rather than company data alone, see which platforms combine social engagement data with ICP matching for what that specific combination requires before assuming a contact-data waterfall covers it.

How does Retriever fit into a waterfall enrichment workflow?

Retriever takes a different approach to the same underlying problem: instead of stacking several static databases and falling through them field by field, Retriever's agents read the live web (a company's site, its job posts, its public reports) and check every lead against your ICP with the source behind it, so what you get is checkable rather than a value pulled from whichever provider answered first.

Buying signals work the same way: Retriever sets up and continuously tracks hiring, funding, tech-stack, and leadership signals, plus LinkedIn and social listening, as part of the same agent rather than a separate lookup bolted on afterward.

Retriever also runs an MCP server, so a Claude Code skill, waterfall or otherwise, can call Retriever directly as a tool instead of asking Claude to guess at a missing field. Retriever supplies the current, verified company data and the evidence behind it; your skill's instructions handle the ordering, stopping, and formatting logic on top. Book a demo or see what data and signals agents use to connect it to your own enrichment workflow.

Frequently asked questions

Is waterfall enrichment the same thing as a Claude Code skill? No. Waterfall enrichment is the data pattern (try provider A, then B, then C, stop at the first verified result). A Claude Code skill is a way to encode that pattern as reusable instructions so Claude Code applies it the same way every time, instead of you restating the provider order and stop rule in every session.

Can a waterfall enrichment skill call provider APIs directly? A SKILL.md file by itself cannot call anything; it is read and reasoned from, not executed. To actually run a waterfall, the skill needs to be paired with a script or an MCP server that can query the providers, with the skill's instructions deciding the order and the stop condition for whatever comes back.

What should the stop condition be: found, or found and verified? Found and verified, for almost every real use case. A value that only passes a format check (a string shaped like an email) is not the same as one confirmed deliverable, and a skill that stops at "found" will silently pass through unverifiable values as if they were checked.

How many providers should a waterfall try before giving up? Set an explicit cap rather than leaving it open-ended, both for cost and for Claude Code's behavior: an unbounded waterfall will keep trying providers on records nothing can fill, at full cost each time. A cap also gives you a clean definition of "exhausted" so the skill knows to output an empty field instead of a guess.

Where should I store a waterfall enrichment skill if my whole team uses the same providers? In a shared, version-controlled location your team installs from, the same as any skill whose rules (provider order, stop condition, conflict resolution) should stay identical across every person running it. A copy that only lives on one person's machine drifts the first time someone tweaks it locally.