# icp-matrix-builder

Translates your ICP into filter fields and allowed values, flagging which criteria can be filtered, which need paid checks and which cannot be seen.

Skill by Clay. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add clay-run/clay-skill-creator --skill icp-matrix-builder
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add clay-run/clay-skill-creator --skill icp-matrix-builder -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 3. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/clay-run/clay-skill-creator/icp-matrix-builder)

## Source

[Open the source](https://github.com/clay-run/clay-skill-creator/tree/HEAD/skills/clay/icp-matrix-builder). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: icp-matrix-builder
description: |
  Turn an ICP described in your own words into an executable matrix — every dimension
  translated into the exact field and allowed value the platform will accept, classified as
  filterable now, verifiable later for a per-row price, or not observable at all. It reports
  what failed to translate instead of quietly dropping it, band-aligns every threshold you
  state, and hands off a filter set that runs and a verify set that is priced. Use whenever
  someone asks: define our ICP, build an ICP matrix or scorecard, turn our ideal customer
  profile into search criteria, which of our ICP criteria can we actually filter on, or set up
  our targeting definition. Do NOT use it to score or tier a list against an ICP
  (account-tier-scoring), to enumerate the market it defines (tam-builder), to build a working
  prospect list (build-prospect-list), or to classify buyers (buyer-classification). The words
  teams use for their ICP mostly are not in the taxonomy, and it says so.
category: score-and-qualify
personas: [revops, founder]
mechanism: functions
touches: read-only
keywords: []
---

# ICP matrix builder (translate, classify, price)

The 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

- resolves to an unmatched value and **narrows to nothing** — read downstream as "our market is
  tiny", or
- is passed as an empty array and **restricts nothing** — read downstream as "our ICP is huge".

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.

## Declared inputs

**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?"*

## What this skill touches

- **Reads** — the account and persona axes you define, and the qualifiers you supply.
- **Writes** — nothing. The deliverable is handed back to you.
- **Never** — writes to a CRM — the matrix is a definition you take elsewhere.

## Step 0 — Verify Clay and pull the field metadata

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.

## Step 1 — Collect the ICP in the user's words (do not translate yet)

Take it verbatim, including the parts that will not survive. Ask for:

1. **The account axis** — what kind of company. Industry, size, geography, revenue, funding,
   ownership type.
2. **The persona axis** — who inside it. Titles, seniority, function, tenure.
3. **The qualifiers they care about that are not firmographic** — tech stack, growth, funding
   stage, "enterprise-ready", "well-funded", "similar to our best customers". These are the ones
   that will need pricing rather than filtering, so collect them explicitly rather than letting
   them arrive as adjectives.
4. **Which dimensions are required and which are nice-to-have.** This decides what goes in the
   filter and what goes in the score, and it is the user's call.

Do not correct their vocabulary here. The mismatch is the finding, and you need their original
words to report it.

## Step 2 — Translate, and log every failure

Per dimension, resolve to a real field and real values from step 0's metadata. Three outcomes,
all recorded:

- **Translated** — the field name and the exact allowed values. `Insurance` and
  `Manufacturing` are literal taxonomy values; most terms are not.
- **Approximated** — no exact value exists, so the user chooses from candidates you present. For
  `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.
- **Untranslatable** — no field carries it. Say so, and move it to step 3's classification.

Two rules on matching, because both are verified failure modes:

- **Never substring-match a term under about five characters.** `AI` matching
  `Air, Water, and Waste Program Management` is not a near miss, it is noise that will look like
  a broad industry selection.
- **Never pass a value that is not in the closed set.** An unmatched enum value narrows to
  nothing, and nothing is indistinguishable from a small market.

## Step 3 — Classify every dimension: filter, verify, or unobservable

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:

- **Accepting the band** means the ICP is now the wider range. Say which range.
- **Refining to the stated bound** costs a per-row call across everything the filter returned, and
  those calls are spent on rows that the refinement will then discard.

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.

## Step 4 — Band-align every threshold, and declare the rounding

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**:

- A stated `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.
- Revenue bands are `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.

## Step 5 — Emit the matrix

Four parts, and the last two are what make it honest:

1. **The filter set, per axis** — field names and exact allowed values, ready to execute. Account
   axis and persona axis stated separately, in each one's own dialect.
2. **The verify set** — dimension, arm, per-row cost, required or scored.
3. **The unobservable list** — declared, with what the user asked for in their words, so nobody
   later assumes it was applied.
4. **The translation log** — every dimension, its original wording, its outcome (translated /
   approximated / untranslatable), and for approximations which candidate the user chose and what
   was left out.

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`.

## What this skill does not claim

- No real customer ICP has been translated, so the filter/verify/unobservable mix is unmeasured.
- The 24% taxonomy hit rate is measured against an author-written term list, not real customer briefs.
- The derived_* fields are named as an approximation route without having been tested.

## What good looks like

- Every dimension in the output names a real field and real values, or is explicitly listed as
  approximated or unobservable.
- The user can see which of their words did not exist in the taxonomy, in a list, before they
  discover it as a strange result count.
- Band rounding is stated, not absorbed — the user knows their `50–2,000` became `50–4,999`.
- The verify dimensions carry per-row prices, so the cost of the ICP is visible at definition
  time rather than at run time.
- The common failure: accepting `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.

## Rules

- MUST pull the field metadata live and translate against it; NEVER recall taxonomy values from
  memory, and never invent an allowed value.
- MUST report every untranslatable and approximated dimension; NEVER drop one silently, and never
  pick an approximation on the user's behalf.
- MUST classify every dimension as filter, verify, or unobservable, and price the verify set per
  row; NEVER let a non-filterable criterion sit in the matrix as though it filters.
- MUST band-align stated thresholds and declare the resulting range; NEVER present a band
  selection as though it matched the number the user said.
- MUST add `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.
- MUST translate bands separately for each axis — floors on the account axis, labels on the
  persona axis; NEVER carry one spelling to both.
- MUST include `unknown` in a funding filter, or state that it was deliberately excluded.
- NEVER substring-match a term shorter than about five characters against the taxonomy.
- NEVER pass an empty array to narrow a dimension — per the platform's guidance it restricts
  nothing; omit the field instead, and record the dimension as unapplied.

## Worked example

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.
````

- Previous: [find-work-email](https://syn4pse.dev/terminal/clay-find-work-email.md)
- Next: [job-posting-language-signal](https://syn4pse.dev/terminal/clay-job-posting-language-signal.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
