Account scoring

State: to-be-approved. Deploy-verified against a live workspace: not yet. Treat Done when below as the acceptance test and review cargo-ai cdk plan before deploying. Make no outcome claim for this skill until it is approved.

The outcome

Every company in your TAM tiered A, B, C or disqualified, with a two-sentence reason and the page that decided it written on the row, so a rep can read why an account is tier A and argue with it. New companies are tiered as they land. The tiers are four segments: tier A is what contact sourcing and engagement run on, and disqualified is what everything else suppresses.

It runs on tam_companies, the model tam-building lands, and needs nothing else: no CRM, no scoring code, no point weights. When reps work in a CRM, one setting writes the tier, its reason and the scored-at date onto the matching HubSpot or Salesforce company as well, in the same run.

The judgment lives in the context repo, not in code. The agent reads the ICP and tiering-rubric.md from the workspace context on every call. Changing what tier A means is a reviewed commit to that file, with no deploy, and the rep reading the tier can read the same file the agent read.

Firmographics are tam-building's job; the tier is about what no column holds. Headcount band, industry and country are already in the filter that sourced the row. What separates an A from a C is whether the company runs the motion you sell into: an open role, a public stack, an engineering post. So the agent judges on the sourced row first, and searches only to settle one doubt that would change the tier.

Two failure modes worth knowing before you start. Writing a custom column with its custom__ read-side name drops the value while the node reports success, so the play runs perfectly over a book with no tiers in it. And a play enabled without a backfill never tiers the rows that were already there: changeKinds: ["added"] only enrols rows that arrive after it is on.

Example

Tier every company in our TAM against the ICP and the rubric in our context repo, and keep new ones tiered as they land.

Illustrative output, fictional records:

Every row also gets tiered_at and lands in tier_a_accounts, tier_b_accounts, tier_c_accounts or disqualified_accounts. With crmWriteback set to HubSpot, northwind.example's company record gets cargo_tier = A, the same rationale in cargo_tier_reason, and today's date in cargo_tiered_at. The report closes on the tier distribution and one recommended next step.

Guide the operator through every phase

flowchart LR
  rubric["1. Rubric"] -->|"Approve the rubric"| build["2. Build"]
  build -->|"Approve deploy, play disabled"| pilot["3. Pilot"]
  pilot -->|"Approve the backfill and the play"| run["4. Backfill, enable, report"]

Every substantive message starts with the current phase and ends with a Next step section giving the operator one concrete decision, what it unlocks, and what stays blocked. During an in-progress operation, say No action needed and name the next checkpoint. Never end with a generic offer to help.

1. Rubric. Read the ICP and any tiering rubric from the workspace context. If there is no ICP, stop and send the operator to tam-building's first phase: tiering against an unwritten ICP is guessing. If there is no rubric, propose A, B, C and disqualified from the ICP's own language, using this skill's context/tiering-rubric.md as the shape, and have the operator correct it. End by asking the operator to approve the rubric. Nothing bills in this phase.
2. Build. Reconcile with tam-building, adapt, run the contract, types, check and plan, and show the plan: the tier columns added to tam_companies, the agent, the play disabled, and the four segments. End by asking to deploy with the play disabled. A deploy tiers nothing.
3. Pilot. Run ten rows through the workflow as a batch, with the play still disabled (references/run.md). Spot-check one A, one C and one disqualified against the rubric, quote the evaluator results, and give the observed cost per company and what the whole book would cost. With crmWriteback set, read one piloted company back from the CRM and show its three fields. End by asking to approve the backfill at that cost and to enable the play.
4. Backfill, enable, report. Backfill every untiered row, enable the play, and report the tier distribution, the disqualified share, the evaluator pass rate and actual credits, with a direct Cargo link to each segment. Recommend one next step.

Put it in your project

This folder is a worked example: real CDK resources written for some other company. The job is to end up with the code your company would have written, in your project, and an agent does the adapting.

Install the required authoring skill first. If cargo-cdk is absent, run:

npx skills add getcargohq/cargo-skills --skill cargo-cdk

Then read .agents/skills/cargo-cdk/SKILL.md directly; no session reload is needed. Complete its bootstrap and use its authoring, state, plan, and deployment rules throughout. Stop before any template work if the skill cannot be installed or read.

1. Install it: the CLI does the copy. From inside the CDK project, cargo-ai cdk add cookbook/account-scoring writes this example to infra/account-scoring/ and this procedure to .claude/skills/account-scoring/. No project yet? cargo-ai cdk init <dir> --cookbook account-scoring && cd <dir> && npm install does both. If you are reading this from the project's .claude/skills/, the install already happened: start at step 2.
2. Reconcile it with tam-building. This example carries a copy of tam_companies and its AI Ark connector so it deploys on its own. When infra/tam-building/ exists, move the four additionalColumns from the copy onto tam-building's model, point the play and the segments at that export, and delete the copy and its connector: one slug declared twice collides at deploy. Reuse an existing Anthropic connector the same way. This skill declares no defineContext: that resource is a per-workspace singleton the project owns.
3. Write or confirm the rubric. Phase 1 above. It goes in the project's context repo beside the ICP, never into the agent's prompt.
4. Adapt and deploy disabled. Work the sections below in order: What should not change is what you argue back about (say what breaks, then do it if they still want it); What you can change is what you offer unprompted; What you will be asked is the floor, and you derive before you ask. Record what you changed and why under a ## Decisions section in your copy of this file. Then run node --import tsx evals/contract.mjs from this skill's folder, followed by cargo-ai cdk types && cargo-ai cdk check && cargo-ai cdk plan from the project root. Show the diff, and deploy only on a yes. Never run cargo-ai cdk init --force in a non-empty directory.
5. Pilot, backfill, verify. Follow references/run.md, then walk Done when line by line with evidence. Deployed cleanly and tiered nothing is the normal failure.

What you will be asked

Derive before you ask. An input with a lookup is looked up, not asked.

Checked before moving on, not after the deploy:

• icp: it names at least one disqualifier, not only fit signals
• tier_rubric: every tier is decidable from the sourced row plus at most one search, and each tier names what evidence counts for it
• model: the column names in the workflow input match cargo-ai storage column list on the live model
• crmWriteback: the three properties exist on the CRM company object (HubSpot company properties, Salesforce Account fields), and the match property holds the same value as the row: a bare domain, or the record id when the play runs on a CRM model

What you can change

The code is a worked example. These reshapes are expected, and the agent offers them rather than waiting to be asked. Every one costs something; that is what makes it a variation and not the default.

What should not change

However far you adapt, these hold. Ask for one anyway and the agent tells you what breaks, then does it if you still want it, and records why under ## Decisions in your copy of this file.

• The rubric lives in the context repo. (context/tiering-rubric.md in the project's knowledge layer.) Put it in the prompt and changing what tier A means becomes a deploy, the reason for the change stops being reviewable, and the rep reading the tier can no longer read the same file the agent read.
• The agent judges and the play writes. (infra/agents/tier-analyst.ts) The agent carries no model in uses. Give it one and it decides its own routing, at which point an untiered row could be a failed run, a skip, or a choice.
• Custom columns are written with their bare slugs. (infra/plays/tier-accounts.ts) custom__tier on the write becomes custom.custom__tier, the node reports "Record upserted", and the value is dropped.
• Eligibility is the stamp, not the tier. (infra/plays/tier-accounts.ts) Filter on tiered_at being null or stale. Filter on the tier and a failed run looks the same as a legitimate disqualified, so it is either retried forever or never.
• A tier ships with its rationale, its evidence, and its stamp, on the same write. (infra/plays/tier-accounts.ts) A tier nobody can audit is a number a rep will not trust, and a tier with no stamp is judged again on every tick.
• changeKinds: ["added"] stays. (infra/plays/tier-accounts.ts) Runs are created for rows entering the filter. Without it, the LLM bill scales with how often the cron fires.
• The CRM write-back updates, never creates, and writes only the fields named in settings.ts. (infra/plays/tier-accounts.ts) upsertRecords would create a CRM company for every TAM row the CRM does not hold, and a field nobody named is a CRM value overwritten without a decision. It runs after the row write, so the row is the record of the judgment whatever the CRM does.
• Every tier the agent can emit has a segment. (infra/segments/tiers.ts) A tier with no segment is a row that lands nowhere and quietly disappears from the book.

Done when

• the ICP and the tiering rubric are in the workspace context, and the rubric was approved
• the pilot tiered ten rows, and one A, one C and one disqualified were checked against the rubric by hand
• every row in the model carries a tier the rubric defines, a rationale naming the deciding lines, and a tiered_at stamp, and no row carries one without the others
• the four segments resolve, and their counts sum to the tiered row count
• the agent's evaluator pass rate is at or above its threshold
• with crmWriteback set, one piloted company read back from the CRM carries the same tier, reason and scored-at date as its row
• editing the rubric in the context repo changes the next tier with no deploy
• the report gave the tier distribution, actual credits against the pilot's estimate, and one recommended next step
• node --import tsx evals/contract.mjs passes against the adapted resources

What it costs

Tiering is one agent run per company, billed as LLM tokens through the bound connector, plus the web searches the agent decides to make. maxSteps is the per-company ceiling, and the rubric's one-question-one-search rule is what keeps a normal row far below it. The pilot is how you learn the real number: read actual credits for the ten rows, then multiply by the untiered row count before approving the backfill.

After the backfill, the play only tiers what arrives (changeKinds: ["added"]) and what goes stale after rescoreAfter, so the steady-state cost follows how many companies tam-building lands and how short that window is, not how often the cron fires. A weekly window bills every account every week. The CRM write-back is one connector action per tiered company; the pilot's actual credits include it.

Composes into

contact-sourcing (the buyers at every tier A account), agentic-engagement (talk to the accounts this ranked), new-hire-detection (watch tier A for the hires that move a C up). Works best after tam-building, whose tam_companies it tiers.