Terminal
Terminal/Skill
Translates your ICP into filter fields and allowed values, flagging which criteria can be filtered, which need paid checks and which cannot be seen.
By Clay
Works with
npx skills add clay-run/clay-skill-creator --skill icp-matrix-builderThe insight: an ICP is a vocabulary problem before it is a strategy problem, and the translation fails silently in both directions.
Verified against the live field metadata. The industry taxonomy both axes must filter on has 457 closed values, and the five words a B2B team is most likely to use for its ICP match none of them:
| Your word | Values it matches in the taxonomy |
|---|---|
SaaS | 0 |
B2B | 0 |
Fintech | 0 |
Healthcare | 0 |
Cybersecurity | 0 |
Software is not a value either — only compounds like Embedded Software Products. And short
terms are worse than useless with naive matching: AI substring-matches 53 values including
Air, Water, and Waste Program Management and Airlines and Aviation.
Now the part that makes this dangerous rather than merely annoying. Neither failure mode errors. The platform's own filter guidance states: "Omit fields instead of passing empty arrays; empty arrays do not restrict results." So a dimension that failed to translate either
Both look like facts about the market. Neither is. So the deliverable is not a strategy document; it is a translation with a receipt: every dimension mapped to a real field and a real allowed value, everything that failed to map named, and every criterion that cannot be filtered priced instead of quietly dropped.
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 |
|---|---|---|
| The account axis | what kind of company: industry, size, geography, revenue, funding, ownership | no default. Take it verbatim, including the parts that will not survive |
| The persona axis | who inside it: titles, seniority, function, tenure | no default |
| The non-firmographic qualifiers | tech stack, growth, funding stage, "enterprise-ready", "similar to our best customers" | collect these explicitly rather than letting them arrive as adjectives — they need pricing rather than filtering, and that is the finding |
| Required versus nice-to-have | which dimensions gate and which only score | their call, and it decides what goes in the filter versus the score |
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, run the Clay plugin's setup skill and
re-run.
Pull the authoritative field lists — free, and never from memory, because taxonomies and allowed-value sets change:
clay search filters-mode fields --source-type companies > /tmp/fields-companies.json
clay search filters-mode fields --source-type people > /tmp/fields-people.json
Field counts, enum sets, and the two axes' dialects are catalogued in
references/field-vocabulary.md. Read the guidance.behavior block in each response: it states
the AND/OR semantics and the empty-array trap in the platform's own words.
Take it verbatim, including the parts that will not survive. Ask for:
Do not correct their vocabulary here. The mismatch is the finding, and you need their original words to report it.
Per dimension, resolve to a real field and real values from step 0's metadata. Three outcomes, all recorded:
Insurance and
Manufacturing are literal taxonomy values; most terms are not.SaaS, that means picking specific taxonomy values, or moving the concept to
description_keywords, or to a derived_* field. The choice is theirs, presented with what
each option costs in recall — never made silently on their behalf.Two rules on matching, because both are verified failure modes:
AI matching
Air, Water, and Waste Program Management is not a near miss, it is noise that will look like
a broad industry selection.This is the step that makes the matrix costable, and the classes differ in price by orders of magnitude:
| Class | Meaning | Cost |
|---|---|---|
| filter | expressible in the search filters — narrows the population before you pay | free, inside the query |
| verify | not a filter; needs a per-row enrichment call after the population exists | credits × rows |
| unobservable | no arm carries it at all | declare it; never let it look satisfied |
A filter may additionally carry refine: verify — see below — when band alignment widened it
past the stated bound. That is a modifier on a filter, not a fourth class.
The platform's guidance names several things teams routinely put in an ICP that are explicitly not filters: "Lookalike company search, funding stage, Fortune 500, unicorn status, and technographics" on the account axis, and "Email addresses, phone numbers, Fortune 500, unicorn status, and employer lookalikes" on the persona axis.
So uses Salesforce is not an ICP filter — it is a tech-stack enrichment at 4–8 credits per
row, applied to whatever the filters already returned. Note the ordering consequence: a verify
dimension does not shrink your spend, it multiplies it. Put three verify dimensions in an ICP
and every row of the eventual market costs three enrichments before it is even qualified.
State per verify dimension: which arm, its per-row cost, and whether it is required (gates every row) or nice-to-have (scored, not gated).
One dimension can be both, and this is the case people miss. A banded numeric filters coarsely
and verifies precisely: 50–2,000 employees filters to the bands covering 50–4,999, and the stated
ceiling of 2,000 can only be enforced by a per-row call that returns an exact count. So classify it
filter and add the modifier refine: verify, naming the arm and its per-row cost, whenever
band alignment widened the dimension past what the user asked for.
Two things then have to be said out loud, because the alternative is a silent choice:
The classes stay mutually exclusive — refine is a modifier on a filter, never a third verdict —
and which one the user takes is their decision, priced.
Numeric criteria do not survive as stated. Both axes offer nine headcount bands and twelve revenue bands, and an arbitrary threshold rounds to a band edge:
50–2,000 employees cannot be expressed. The bands available on the account axis are
1, 2, 10, 50, 200, 500, 1000, 5000, 10000 — floors — so the nearest selection covers
50–4,999. That is not the ICP the user stated, and the difference must appear in the
output rather than being absorbed.0-500K … 100B-1T. A stated $10M ARR floor maps to 10M-25M upward;
a stated $12M does not exist as a boundary at all.funding_amounts includes an explicit unknown value. Including it is the recall-preserving
choice — companies whose funding was never recorded are otherwise excluded by a funding filter,
which turns a sparse field into a smaller market. Omitting unknown is a deliberate tightening
the user asks for.And the two axes use different dialects for the same bands. The account axis takes band
floors ('50'); the persona axis takes band labels ('51-200'). The same stated band must
be translated twice, differently. A matrix that carries one spelling to both axes fails on one of
them — silently, per the empty-array rule.
Four parts, and the last two are what make it honest:
If the user wants weights and tiers on top, that is account-tier-scoring, and this matrix is
its input: the filter set becomes the gate, the verify set becomes the scored dimensions. If they
want to know how big the resulting market is, that is tam-builder.
50–2,000 became 50–4,999.SaaS as an industry, passing it through, and reporting a market
of zero as a market fact. The second-worst: dropping an untranslatable dimension silently, so
the user believes a criterion is being applied when nothing is applying it.refine: verify with its per-row cost wherever band alignment widened a dimension past
the stated bound, and let the user choose the wider band or the paid refinement; NEVER pick
between them silently.unknown in a funding filter, or state that it was deliberately excluded.Stated ICP, verbatim: "mid-market B2B SaaS in the US and UK, 50–2,000 people, $10M+ ARR, uses Salesforce, and the buyer is a VP of RevOps or above."
Translation log, as delivered:
| Their word | Outcome | Resolved to |
|---|---|---|
B2B SaaS | approximated | no taxonomy value exists for either word; user picked specific software-taxonomy values, with description_keywords as the alternative they declined |
US and UK | translated | country_names |
50–2,000 people | approximated + rounded, refine: verify | account axis sizes: ['50','200','500','1000'] → covers 50–4,999, not 50–2,000; persona axis needs company_sizes: ['51-200','201-500','501-1,000','1,001-5,000']. Enforcing the stated 2,000 ceiling needs an exact-count call per row — priced, and the user chose the wider band |
$10M+ ARR | approximated + rounded | annual_revenues from 10M-25M upward; no $10M boundary exists as stated |
uses Salesforce | verify, not filter | technographics are explicitly not a native filter; tech-stack arm at 4–8 cr per row |
VP of RevOps or above | translated | job_title_seniority_floor_level: 'vp' with match_mode: 'floor', plus job_title_keywords for the function |
Delivered as: a filter set that runs on both axes in their own dialects; one verify dimension
priced at 4–8 credits per row and flagged as required, which means it gates every row of the
eventual market; nothing unobservable; and the two rounding disclosures stated at the top rather
than buried — because 50–4,999 instead of 50–2,000 changes the market size before anyone
enumerates it.