Build a Customer Health Score Prompt With a Scoring Contract

Every customer success tool sells a health score. Almost none of them tell you how it's calculated. You get a green, yellow, or red dot and a vague promise that machine learning is involved. Then a "green" account churns and nobody can explain what the dot missed.

A customer health score prompt does the opposite. It takes the signals you actually have (usage trend, support load, engagement) and returns a 0-100 score with named risk flags, in a fixed contract, showing which signal moved the number and why. Transparent, portable, and tunable in plain language. You can run it on one account in thirty seconds or a portfolio in a batch.

This post shows how to build that prompt, why the scoring output contract is what makes it trustworthy, and how to keep the score honest instead of a number the model made up.

Why CS-platform blogs won't hand you the prompt

Search "customer health score prompt" and you mostly find vendor blogs explaining the philosophy of scoring while steering you toward a demo. ChurnZero's health scores in the age of AI walks through what scores are and why they matter, but by its own structure provides no copyable prompt, no scoring schema, and no worked example mapping inputs to a score. Velaris' AI for customer health scoring guide lists the signals a score should combine, then stops short of any prompt or output format and books you a demo.

They're not wrong about the inputs. They just never show the mechanics. A reader finishes either post knowing health scores combine usage, support, and engagement, and still has no idea how to actually prompt a model to produce one.

That's the gap. The concept is well covered. The copyable artifact (a prompt with a real scoring contract) isn't. And without the contract, you get a different number every run, which is worse than a static spreadsheet.

What you can do with a customer health score prompt

• Compute a 0-100 score for one account from usage, support, and engagement signals
• See a per-signal breakdown so you know which input dragged the score down
• Get named risk flags (USAGE_DECLINE, SUPPORT_SPIKE, NO_EXEC_SPONSOR)
• Tune the weighting in plain language instead of editing a spreadsheet formula
• Run it per account on demand or batch a portfolio for a QBR prep
• Keep the logic transparent and portable across whatever data you can paste

Anatomy of the prompt: signals, weights, contract

The structure separates the raw signals, the weighting rule, and the output shape. The contract is what makes the score auditable.

VARIABLES
  {{usage_signals}}      active users, feature breadth, 30/90-day trend
  {{support_signals}}    ticket volume, severity mix, sentiment
  {{engagement_signals}} QBR attendance, exec sponsor, renewal date
  {{weights}}            usage 50, support 25, engagement 25

INSTRUCTION
  Score each signal family 0-100. Apply {{weights}} for the
  composite. Flag any family scoring below 50 with a named
  risk flag and a one-line reason. Do not invent signals
  not present in the inputs.

OUTPUT CONTRACT
  health_score:  0-100 (weighted composite)
  band:          GREEN >=70 | YELLOW 40-69 | RED <40
  breakdown:     usage / support / engagement sub-scores
  risk_flags:    [named flag + one-line reason, ...]
  top_action:    the single most useful next move

Put the contract last. When you paste rich {{usage_signals}} and a long support history, a contract at the top loses out to the recent context and the model returns prose instead of a parseable block. Restate the fields on the final line and the structure holds. It's the same reason a repo health scorecard prompt puts its dimension list at the end, not the top.

Make the model show the math, then refuse to fabricate

The opinionated take: a health score prompt that doesn't refuse missing data is a churn-prediction generator, not a health score. If you feed it usage data but no support data and it still returns a confident composite, it invented the support sub-score. That number then drives a renewal decision. Bad.

DATA BOUNDARY
  Score a family only from signals actually present in its
  variable. If {{support_signals}} is empty, set support to
  null, exclude it from the weighted composite, and add flag
  INSUFFICIENT_DATA: support. Never estimate a missing family.

A null sub-score is honest. A guessed one is a trap dressed as insight. The same discipline that makes a hallucination spot-checker catch unsupported claims applies here: no source, no score.

Step-by-step usage

1. Pull the signals

Gather real numbers into the three signal variables. Usage trend matters more than usage level (a heavy user trending down is a bigger risk than a light user holding steady), so include the 30 and 90-day direction, not just the snapshot.

2. Set the weights

Fill {{weights}} for how your business reads risk. A product-led account weights usage heavily; an enterprise relationship weights the exec sponsor and engagement. Putting weights in a variable means you tune them in plain language, no formula editing.

3. Run and read the breakdown

Run the prompt. Read the breakdown before the headline score. A 65 composite hiding a usage sub-score of 30 is a different story than a flat 65 across the board. The breakdown is where the action lives.

4. Act on top_action

The top_action field names the single move that shifts the score most. That's the point of scoring: not to label the account, but to tell the CSM what to do this week.

5. Re-score on a cadence

Re-run weekly or before every QBR. A health score is a trend, not a snapshot. A green account sliding toward yellow over three weeks is the early-warning signal a static dashboard misses.

Variables you'll set

Model behavior worth knowing

Claude holds the sub-score breakdown and the INSUFFICIENT_DATA flag reliably when the data boundary is a hard rule, and it explains its weighting transparently when asked to show the per-family math. GPT-4o computes the composite accurately but tends to fill a missing family with an average rather than null it, so the explicit "set to null, exclude from composite" instruction matters more there. Both models produce a more useful top_action when you cap it to one move, since an open-ended "recommendations" field invites a generic five-item list instead of the one thing that matters.

Keep the inputs honest and recheck the weights quarterly. The score is only as good as the signals you paste, and weights that fit last year's renewals can drift as the product changes. Treat the prompt as a transparent calculator you tune, not an oracle.

Getting started

1. Pull real usage, support, and engagement signals into the three variables
2. Set {{weights}} to match how your business reads risk
3. Run the prompt and read the breakdown before the headline score
4. Act on the single top_action this week
5. Watch the risk_flags for INSUFFICIENT_DATA and backfill those signals
6. Re-score weekly so you catch the slide, not just the snapshot
7. Batch the portfolio before each QBR cycle for prioritization

When a score goes red and the account escalates, the Customer Escalation Agent Pack triages the ticket fast, and the QBR Production Prompt Pack turns the health breakdown into a renewal-ready review deck. Or browse the full catalog for the rest of the CS toolkit.

Two related reads: the repo health scorecard prompt applies the same weighted-dimension scoring to a codebase, and the LLM-as-a-judge rubric shows how a fixed scoring contract keeps any AI-graded score consistent run to run.