Terminal
Terminal/Skill
Builds a Clay workflow that scores contacts 0 to 100 by role and seniority, using Jev, TypeSafe's decision model, for judgment.
By Clay
Works with
npx skills add clay-run/clay-skill-creator --skill score-contacts-with-jevThe insight: a contact score is two different kinds of fact, and only one of them is about the person. "Would this title own the budget?", "is this a recruiter?", "how senior is 'Head of Fleet Ops'?" are judgments about the person, and titles are messy enough that only a model reads them well. "Is their company an A?", "did they start this role in the last four months?", "how many points is that?" are lookups and arithmetic. Ask a model for "a lead score from 0 to 100" and it blends both into a number nobody can decompose, and quietly lets a VP at a poor-fit company outrank a manager at your best account.
The evidence is Jev's own documentation. TypeSafe publishes what Jev 1.13 is bad at, and the top of the list is numbers, counting and comparing dates; it reads literally; it degrades when the record carries fields the question does not need. Its recommended pattern for scoring is to break the judgment into atomic questions and combine them with weights in code. And Jev returns a probability for every option, so a score can use how sure it was.
What follows is the whole design:
not_scored; one the data
cannot judge is insufficient_data, not a D; above that bar, every criterion with no data earns
nothing and is named. A recruiter comes back disqualified.Measured. Run live against Jev (TypeSafe) and a Clay workspace: a VP of Operations at an A-tier account scored 96 A in Clay and in the local preview alike, and a recruiter was disqualified. The build caught Clay attaching an unrelated connection to the Jev step and refused to publish. The live checks, and what was not run, are in
references/live-checks.md.
This skill is not finished when the rubric is agreed. It is finished when the workflow is published, one contact has gone through it in Clay and matched the local preview, and the installer has been shown how to call it. If you stop early, say which step you stopped at and the command that resumes it.
AskUserQuestion
in Claude Code), one decision at a time, likely answer first, free text only as "Other". Never a
paragraph of questions.Nothing here ships with a value. Where a default is offered it is named, and accepting it is
recorded as borrowed ("origin": "default") and said at delivery.
| Input | What the installer supplies | If it is missing |
|---|---|---|
| Where contacts come from | a Clay table, a saved Audiences audience of people, or "another system" (webhook). Picked from a list the agent reads | no default. It decides which fields exist, so which criteria are possible |
| What they sell | a line or two, found in the agent's context first; asked only if not | stop: no rubric can be written without it |
| The buying roles | who signs, who champions, who is consulted, described by function and title | stop at Step 2. Never invented |
| Seniority that matters | whether senior is better, or a level is the sweet spot | a 0-to-top seniority scale is offered, recorded as borrowed if accepted |
| People who are never prospects | recruiters, students, consultants, competitors' staff, or "none" | "none" is a real answer; ask, never assume |
| The account's fit | a column or field carrying the company's tier or score, usually from the account skill | the criterion is left out, and the card says a poor-fit company's VP can outscore a best-fit manager |
| Signals worth points | only those the data carries (new in role, recent job change) | left out |
| Tier cut-offs | what an A must reach | A≥70, B≥45, C≥25 offered, recorded as borrowed if accepted |
| A Jev key | TypeSafe or OpenRouter. Found in the environment, ./.env or ~/.config/jev-lead-score/.env (shared with the account skill); otherwise saved there through a password box | stop at Step 4: nothing can be previewed |
| The same key in a Clay connection | an existing HTTP API connection named by the installer (the account skill's, if built), or a new one they create in Clay's UI | stop at Step 6: the workflow cannot call Jev |
Not asked, ever: column or field names (read and shown as a mapping to correct), which fields the score writes (fixed), a callback URL (the caller's own), whether to preview (always), the provider when only one key exists, point values for every option (proposed in the draft and corrected there), and any key in the chat.
Inputs are the rubric's inputs, one flat field each, plus source_ref (echoed back for joining).
A typical contact rubric reads full_name and title (required), headline, company_name,
account_tier and started_role_on. Output, every key always present:
| Key | |
|---|---|
lead_score | 0 to 100 integer |
lead_tier | the rubric's tiers (A, B, C, D by default), or the status when not scored |
score_status | scored · disqualified · insufficient_data · not_scored · failed. Five, no sixth |
score_reasons | what counted for the record "(+25)", what counted against it "(2 of 25)", and what had no data |
needs_review | answers under the confidence floor, with Jev's split; none otherwise |
coverage_pct | how much of the rubric the data let Jev and the rules judge |
criteria_json | every criterion: answer, confidence, points, status |
rubric, jev_model, jev_cost_usd, error, source_ref, scored_at | provenance |
record_id, isTerminal | plumbing: the audience record written to, and the flag a run is settled on |
~/.local/state/score-accounts-with-jev/, if one exists; the column list and up to ten rows of
the table, or the field list and up to ten records of the audience, the installer picks (Step 1,
Step 5); Clay's action catalogue; the workspace name.~/.local/state/score-contacts-with-jev/; the Jev key into a .env file only through the
password box, at mode 0600, by default ~/.config/jev-lead-score/.env, never into a file git
would commit. In Clay: one workflow "Jev lead score: contacts · " (Step 7); with an
audience, a second workflow and seven "Jev …" fields on people records, adopted if they already
exist. That audience workflow then writes those seven fields onto each person record it
scores, and never writes on a failed Jev call. The table workflow writes onto the rows of any
table later bound to it. Only when a wrong connection is fixed through Clay's default (Step 7),
the installer changes which connection is the workspace default, then changes it back.other, Step 2 other, Step 3 other, Step 4 other, Step 5 sample-review,
Step 6 other, Step 7 write-approval, Step 7 spend-approval.The people, companies and numbers are invented.
What rubric_tool.py check prints for scripts/rubric.example.json, saved under the installer's
own name with the seniority scale and cut-offs accepted as defaults.
Rubric: Route-planning buyer fit (v1) — scores contacts, 0 to 100
Worked out in code (free, no Jev call):
Account fit from Account tier (account scoring): A → +30; B → +20; C → +8; anything
else → +0
New in role from Started current role: under 120 days ago → +10;
120–364 days ago → +5; 365+ days ago → +0
Asked of Jev (one request per contact, all questions together):
Buying role Choice on Job title, Profile headline or summary: decision_maker +30;
champion +25; influencer +10; not_involved +0;
not_enough_information +0
Seniority Score (5 levels) on Job title: 0 to +15
Not a prospect Noul (yes/no) on Job title, Profile headline or summary: yes at
80%+ DISQUALIFIES
Most points possible: 85. Tiers: A ≥ 70, B ≥ 45, C ≥ 25, D ≥ 0.
Below 50% coverage (too little data to judge) a contact is 'insufficient_data', not a low tier.
Answers under 60% confidence are listed in needs_review.
Borrowed defaults you accepted rather than chose: Seniority, tier cut-offs.
Jev cost through TypeSafe: about 659 input tokens per contact (output is free),
so roughly $0.028 per 1,000 contacts.
Scores and tiers are from a live run of the example rubric against Jev; the reasons are shortened (the tool writes "Buying role: likely decision maker (+30) | …"), and the people are invented. A reason counts for the person as "(+30)" and against them as "(0 of 30)", so a low score names what pulled it down.
| Contact | Score | Tier | Why |
|---|---|---|---|
| Dana Ruiz, VP Operations, Northwind Supply | 96 | A | at an A-tier account (+30) · likely decision maker (+30) · Vice president (+11) · started this role in the last 4 months (+10) |
| Sam Okafor, Fleet Manager, Northwind Supply | 69 | B | at an A-tier account (+30) · likely champion (+25) · against: Manager or team lead (4 of 15), in this role over a year (0 of 10) |
| Priya Shah, Head of Fleet Ops, Adventure Works | 69 | B | likely champion (+26) · at a B-tier account (+20) · Director or head of a function (+8) |
| Lee Park, VP Marketing, Tailspin Toys | 13 | D | Vice president (+11) · against: at a low-fit or unscored account (0 of 30), not involved in this purchase (0 of 30) |
| Jo Brandt, Talent Partner, Contoso | 25 | disqualified | Disqualified: not a prospect (recruiter, student or outsider) |
| Ari Moss (no title on record) | 0 | not_scored | Not scored: missing title |
Lee Park is senior and still a D: the title says marketing and the company is a poor fit, which is the case a single "fit score" column gets wrong. Six contacts cost $0.00013.
Contact scoring is live: "Jev lead score: contacts · Route-planning buyer fit" (published)
Rubric Route-planning buyer fit v2 · 2 rules, 3 Jev questions · tiers A/B/C/D (cut-offs borrowed)
Jev TypeSafe, jev-1.13.0 · key in Clay connection "Jev (TypeSafe)"
and locally in ~/.config/jev-lead-score/.env
Account fit read from each contact's "Account tier" column (your account scoring's lead_tier)
Smoke test Dana Ruiz: local 96 A · Clay 96 A · answers match ✓
Preview 10 contacts: A 2, B 3, C 1, D 2, disqualified 1, not_scored 1 · $0.0002
From a Clay table: add this workflow to the table, starting node "1 Intake", and map full_name,
title, headline, company_name, account_tier, started_role_on onto your columns (names need not
match). The score comes back onto the row.
From anywhere else:
curl -X POST 'https://api.clay.com/v3/sources/webhook/…' -H 'Content-Type: application/json' \
-d '{"full_name":"Dana Ruiz","title":"VP Operations","company_name":"Northwind Supply",
"account_tier":"A","started_role_on":"2026-07-01","source_ref":"row-2210"}'
| File | What it is for |
|---|---|
scripts/jev_lib.py | the rubric check, the scoring code the Clay steps run, key discovery, state paths, the clay wrapper |
scripts/rubric_tool.py | check, save (with version bumps), show and export a rubric |
scripts/rubric.example.json | a complete, invented contact rubric to start from |
scripts/jev_key.py | find an existing key, guide, save one through a password box into a .env, test it |
scripts/score_local.py | the preview: score up to 50 real contacts on this machine with the exact workflow code |
scripts/build_scorer.py | build, check the connection on, and publish the workflow(s); backfill an audience |
scripts/smoke_test.py | one contact through the published workflow, compared with the local score |
scripts/test_offline.py | every generated step, the arithmetic and the builder, with no Clay, network or key |
references/jev-api.md | Jev's two routes, request and answer shapes, price, limits, what it is bad at |
references/rubric-format.md | the rubric file, how a score is worked out, writing questions Jev answers well |
references/graph-shape.md | both workflows node by node, and the traps each avoids |
references/live-checks.md | what was run live against Jev and Clay, and what was not |
Run every script with python3 -B. They need only the standard library and the clay CLI.
Do not start a step before the steps above it have their answers. If a declared input is missing, ask for it; never assume one and continue.
Three short paragraphs:
Then, without asking: clay --version && clay whoami (say the workspace name back),
python3 -B scripts/test_offline.py, python3 -B scripts/rubric_tool.py list and
python3 -B scripts/jev_key.py find. A key the account skill saved is found here too. A saved
rubric or a found key means those steps are offered as done. If the platform check fails, say which
part and the one command that fixes it, and stop.
Ask "Where will the contacts you want scored come from?" (A Clay table / A Clay audience of people / Another system, by webhook). Then look, never ask:
clay tables list --filter owner.id=<id from clay whoami>) and ask "Which table?" with up to
four names as options. Read its columns (clay tables columns list).clay audiences list --entity-type people, ask "Which audience?" the same way,
read the people fields (clay audiences fields list --entity-type people).Audiences people records do not carry their company's fields. For an audience, the account tier counts only if it is already a field on the person record. If it is not, say so plainly: a table (where a lookup can bring the company's tier onto each row) is the source that includes account fit, and an audience without it scores people alone.
Note whether a column or field carries the company's tier or score (for example the account
skill's lead_tier written back to a table, or a tier field someone copied onto the person). The
fields that exist decide which criteria are possible; carry the list into Step 2.
Before asking anything, write the brief from your own context. Look in: your memory files and
the project instructions loaded in this session; this conversation; a saved account rubric (the
account skill keeps them under ~/.local/state/score-accounts-with-jev/<workspace id>/rubrics/, and
a rubric's about says what they sell); and documents in the working folder a person would keep
about who buys (a persona doc, an ICP or positioning doc, a strategy or "anchor context" document,
win notes). Read, do not guess.
The brief has six parts:
| Part | Becomes |
|---|---|
| What they sell | the frame for every question's wording |
| Buying roles: who signs, who champions, who is consulted, who is irrelevant | a Choice with described options |
| Seniority that matters | a Score over the title, or a Choice when a middle level is the sweet spot |
| People who are never prospects | a disqualifying Noul (and a match rule for known domains) |
| The account's fit | a lookup rule over the account tier column |
| Signals worth points | rules (time in role) or Nouls (the headline says they are hiring for a team) |
Show the brief as a short table: each part, what you found, and where it came from, or missing. Then ask only for the missing parts that change the rubric, one click at a time, with options drawn from what you found. For example "Who usually signs off on buying this?" (options from their persona doc, plus Other) and "Anyone who should never count as a prospect?" (Recruiters and students / Consultants and agencies / Competitors' staff / None). If no account tier exists in their data, say plainly what that costs (a senior person at a poor-fit company scores high) and ask "Score people without their company's fit, or set up account scoring first?" (Without it for now / Account scoring first). If the brief is complete from context, ask one question instead: "I built this from . Anything wrong or missing?"
Never invent a buying role, a disqualifier or a signal the installer did not state or a source did not say. If what they sell cannot be found or answered, stop.
Write the rubric JSON following references/rubric-format.md, from the brief and the fields Step 1
found:
lookup rule, tier letter to points, never a question.days_since rule. Never ask Jev about a date.not_enough_information automatically. Level 0 of a Score is the most junior.reads: they add nothing to a
judgment and send personal data for no reason."origin": "default"; put what they sell and the
sources in about.Run python3 -B scripts/rubric_tool.py check draft.json --provider <provider if known> and show the
card. Ask "Does this match how you would judge a contact?" (Looks right / Change the points or
cut-offs / Change a criterion / Other). Edit and re-check until it does, then
rubric_tool.py save draft.json.
jev_key.py find already ran. Then:
.env in the working folder (not the shared file, not the
environment): it may belong to another project or client. Ask "Use the key in for this?" (Yes / No, save a separate key). Never bill one project's key silently.jev_key.py guide <provider> and
relay it, then run in the background python3 -B scripts/jev_key.py save <provider>: a
password box opens and the key goes to ~/.config/jev-lead-score/.env at 0600
(--env-file <path> for a project .env; refused if git would commit it). A key pasted into the
chat is exposed: do not use it, ask them to revoke it, and open the box again.Prove it: python3 -B scripts/jev_key.py check <provider>.
Run python3 -B scripts/score_local.py --provider <p> --table <id> (or --audience <id>, or
--file) with --show-map first, show the mapping, take corrections as --map key=Column,
then run it for real and show the table.
Stop here. Ask "Do these scores look right for people you know?" (Yes, build it / Some are off: adjust the rubric / Try ten different contacts). "Some are off" goes back to Step 3 with the specific people in hand: which criterion moved them, and whether the fix is points, an option's description (titles are where literal reading bites: say "Head of Fleet counts as a champion" in the option), or a missing criterion. Rescore after every change.
If the account skill already built a workflow in this workspace, its connection holds the same key: offer it by name first. Otherwise ask "Do you already have a Clay connection holding this key?" (No, I'll create one now / Yes, I'll tell you its name).
Jev (OpenRouter) (or Jev (TypeSafe)) → one header, Authorization, value Bearer followed
by the key → Save. Wait for "done".--connection "<name>".Clay's CLI cannot create or list connections, which is why this one step is theirs.
Build it; never score in the conversation instead. It has to be a workflow because it runs unattended: every row of a bound table, every person who joins an audience, every POST from another system, long after this session ends.
First confirm the node and trigger commands on the installed CLI: clay workflows nodes --help and
clay workflows triggers --help. build_scorer.py creates the workflow (clay workflows create),
its trigger (clay workflows triggers create) and its nodes (clay workflows nodes create, then
update with every pin and edge, then read back), in dependency order:
1 Intake (code: rules, which
questions have data, the one Jev request) → 2 Anything to ask Jev? (conditional) → either
2b Score without Jev (code, terminal) or 3 Ask Jev (HTTP, key from the Clay connection) →
4 Score (code, terminal).2c Save to Audiences after 2b; after 4, 5 Save it? → 6 Save to Audiences, or
5b Not saved (Jev failed).The traps it guards against are in references/graph-shape.md.
Run python3 -B scripts/build_scorer.py --provider <p> --plan (add --audience <id> and
--show-audience-map for an audience). Then one message with everything, and the word write:
This writes to your Clay workspace: one workflow, "Jev lead score: contacts · Route-planning buyer fit", published, calling Jev through your connection "Jev (TypeSafe)". [With an audience: a second workflow triggered by members of "Ops leaders", and seven "Jev …" fields on your people records, which it writes onto every contact it scores from then on.] Each contact costs about $0.00003 in Jev. Nothing is scored until you call it or bind a table [or: until people join; scoring the 3,400 already there is a separate run, about $0.10].
Ask "Go ahead?" (Yes, build it / Build it, but don't score existing audience members yet / Change something first). On yes:
python3 -B scripts/build_scorer.py --provider typesafe [--connection "<name>"] [--audience <id>]
Exit 6 means the Jev step is on the wrong connection, and its workflow was not published. Clay binds a connection to a step by id, its CLI lists no connection ids, and a step written without one gets whatever connection Clay treats as the workspace default (in testing, the first build landed on an unrelated connection). Never publish around it: that connection's key would go to Jev. Fix it in this order, then the same build checks every step again and publishes:
--connection-id <connection id>. Verified in
testing: binds on the first write.--reattach, which rewrites the Jev step
so Clay attaches its default (verified in testing). Then have them set the connection the report
named back as default, so HTTP steps added elsewhere do not pick up the Jev key.references/live-checks.md, check 7), so treat it as the last resort and
let the re-run's check say whether it held.If they approved scoring existing members:
python3 -B scripts/build_scorer.py backfill --audience <id>. It submits, in batches of 50, every
member whose "Jev score rubric" field does not already read this rubric's name and version, so a
re-run after any interruption or Jev outage submits only what is left.
python3 -B scripts/smoke_test.py --from-preview sends the first preview contact through the
published workflow and scores it locally again. Match proves the wiring, the connection's key
and the published rubric. A 401 in Clay's result means the connection holds the wrong key; if the
run fails, the script names the step and Clay's error. With an audience, also run
smoke_test.py --audience, which reads the member's "Jev …" fields back from Audiences. Do not call
either workflow live until it matches.
The delivery card from "Representative output", with the real numbers, then end with how to call it, all three ways:
account_tier to that column so the
account's verdict flows into the person's.curl with a real-shaped body.Say what was borrowed rather than chosen, and what was not tested. When asked later: "change the rubric" is Steps 3, 5, 7 and 8; "score the companies too" is the sibling account skill.
alpha, and was not run live: the live runs
used a TypeSafe key. The two take the same request and return the same answers, per both docs.failed; re-run those contacts.references/live-checks.md.insufficient_data means the record lacked fields, not that the person is a poor lead. The skill
does not enrich.A good run ends with one contact scored identically in Clay and locally, a published workflow
whose 3 Ask Jev step is on the installer's named connection, and a preview the installer read
and agreed with, in which a senior person at a poor-fit company scores below a hands-on champion at
a best-fit one. Every score names the criteria that moved it with their points; a person with no
title is not_scored; a recruiter is disqualified.
A thin run looks finished and is not:
reads includes email or phone, sending personal data for nothing..env git will commit.insufficient_data or not_scored, never a low tier. Five statuses.The workspace, people and company are invented; the steps and outputs are the real shapes.
Ask: "We scored our accounts with Jev last week. Now I want the people in our Ops leaders audience scored too."
Step 0. Workspace Northwind GTM. jev_key.py find: "TypeSafe key: found (TYPESAFE_API_KEY in
~/.config/jev-lead-score/.env)", saved by the account skill. No contact rubric yet.
Step 1. Audience, named in the ask; Ops leaders picked from the list. Its people fields include Job title, Headline, Company name, Started role, and Account tier, a copy of each company's "Jev lead tier" that the team keeps on its people.
Step 2. The brief, from context: what they sell from the saved account rubric's about;
buying roles from personas.md in the folder (the COO signs, fleet and dispatch managers
champion). Missing: who is never a prospect. "Anyone who should never count as a prospect?" →
Recruiters and students. Seniority scale and cut-offs: the defaults, accepted, so borrowed.
Step 3. Two rules, three questions (the card above). "Does this match how you would judge a contact?" → Looks right. Saved as v1.
Step 4. TypeSafe key found and used. check typesafe → "key works".
Step 5. --show-map: account_tier ← Account tier, started_role_on ← Started role, all
matched. Ten contacts for $0.0002. "Some are off": a Head of Fleet Ops came out influencer. The
champion option's description gains "Head of Fleet"; rescored, now champion. Saved as v2, the
version the delivery card shows.
Step 6. The account skill's connection Jev (TypeSafe) exists: offered by name and taken.
Step 7. The gate names both workflows, the seven "Jev …" people fields, $0.00003 a contact, and
the 3,400 existing members as a separate run of about $0.10. "Build it, but don't score existing
members yet." Built and published on the first try: Clay's default HTTP connection was already
Jev (TypeSafe), and the read-back confirmed it before anything was published.
Step 8. Smoke test: Dana Ruiz, local 96 A, Clay 96 A, answers match; --audience reads a
member's "Jev …" fields back and they match too.
Step 9. The card, then: new members of Ops leaders are scored as they join; to score the 3,400
already there, build_scorer.py backfill --audience <id>; or bind any table to 1 Intake and map
account_tier. Borrowed: the seniority scale and the cut-offs.