Customer Health Scorecard Skill
Produce a structured, data-driven health scorecard for a customer account — giving the CSM and leadership a clear view of renewal risk, expansion potential, and the actions needed to move the account in the right direction.
Reads from / Writes to the Brain
If a professional-brain (brain/) exists, ground in it instead of re-asking for what you already know:
- Read first: the account's
entities/ file, its stakeholders/ (champion, economic buyer, detractors), and knowledge/. Run python3 ../professional-brain/scripts/brain_query.py ./brain "<account name>" and carry each fact's provenance tag through.
- 📥 Propose to the Brain: after producing, propose recording the health verdict + key risks to the account
entities/ file, and a renewal-risk entry to decisions/ if a call is made, each provenance-tagged. Show them, get a yes, then write with ../professional-brain/scripts/brain_write.py … --commit (append-only, dry-run by default).
Required Inputs
Ask for these if not already provided:
- Account name and tier (enterprise / mid-market / SMB)
- Contract value (ARR) and renewal date
- Product usage data — logins, DAU/MAU ratio, key feature adoption
- Support data — open tickets, CSAT or NPS score, recent escalations
- Engagement data — last QBR date, executive sponsor status, champion name
- Commercial data — payment history, expansion conversations, seats used vs. licensed
- Any known risks or recent changes at the account
Scoring Framework
Score each dimension 1–5. Weight as shown. Calculate weighted total out of 100.
| Dimension |
Weight |
What to Score |
| Product Adoption |
30% |
DAU/MAU ratio, breadth of features used, power users identified |
| Engagement |
20% |
QBR cadence, executive sponsor active, champion strength |
| Outcomes |
20% |
Customer hitting their stated goals / success metrics |
| Support Health |
15% |
Ticket volume trend, unresolved escalations, CSAT |
| Commercial |
15% |
On-time payments, seats utilised, expansion signals |
Score → RAG conversion:
- 80–100: Green (healthy, renew likely)
- 60–79: Amber (at risk, needs attention)
- 0–59: Red (high churn risk, escalate)
Programmatic Helper
This skill ships with a stdlib-only Python script that applies the weights above and converts the weighted total to a RAG status — so the headline score is computed identically every time and weights always sum to 100%.
# Five scores 1-5 in order: adoption engagement outcomes support commercial
python3 scripts/health_score.py --scores 4 3 4 2 5 --account "Acme Corp"
# Or from JSON (lets you override the default weights per account/segment)
python3 scripts/health_score.py --input account.json
It returns the per-dimension weighted points, the total out of 100, and the RAG band (Green ≥80, Amber 60–79, Red <60) with a one-line next step. Run it to set the headline number, then write the dimension detail and actions below around it. Add --json for downstream tooling.
Output Format
Customer Health Scorecard: [Account Name]
CSM: [Name] | Tier: [Enterprise / Mid-Market / SMB]
ARR: £/$/€[X] | Renewal date: [Date] | Days to renewal: [N]
Overall health: [Green / Amber / Red] — [Score]/100
Last updated: [Date]
Health Score Summary
| Dimension |
Score (1–5) |
Weight |
Weighted Score |
Trend |
| Product Adoption |
[1–5] |
30% |
[X] |
↑ / → / ↓ |
| Engagement |
[1–5] |
20% |
[X] |
↑ / → / ↓ |
| Outcomes |
[1–5] |
20% |
[X] |
↑ / → / ↓ |
| Support Health |
[1–5] |
15% |
[X] |
↑ / → / ↓ |
| Commercial |
[1–5] |
15% |
[X] |
↑ / → / ↓ |
| Total |
— |
100% |
[X]/100 |
|
Dimension Detail
Product Adoption — [Score]/5
- DAU/MAU ratio: [X]% (benchmark: >25% = healthy)
- Key features adopted: [List features in use]
- Features not adopted: [List unused high-value features]
- Power users identified: [Yes / No — how many]
- Assessment: [1–2 sentences on adoption health]
Engagement — [Score]/5
- Last QBR: [Date] — [Outcome summary]
- Next QBR: [Scheduled / Overdue]
- Executive sponsor: [Active / Passive / Vacant]
- Champion: [Name, role, strength: strong / moderate / weak]
- Assessment: [1–2 sentences]
Outcomes — [Score]/5
- Customer's stated goals: [List 2–3 goals from onboarding or last QBR]
- Progress against goals: [On track / Partial / Off track]
- Evidence of value: [Metric or quote that demonstrates ROI]
- Assessment: [1–2 sentences]
Support Health — [Score]/5
- Open tickets: [N] (priority breakdown: P1: X, P2: X, P3: X)
- CSAT / NPS: [Score] (benchmark: >8 CSAT / >30 NPS = healthy)
- Unresolved escalations: [Yes / No — details if yes]
- Ticket trend (last 90 days): Increasing / Stable / Decreasing
- Assessment: [1–2 sentences]
Commercial — [Score]/5
- Seats licensed: [N] | Seats active: [N] ([X]% utilisation)
- Payment history: [On time / Late — details]
- Expansion signals: [Yes — describe / No]
- Downgrade or cancellation signals: [Yes — describe / No]
- Assessment: [1–2 sentences]
Top Risks
| Risk |
Severity |
Mitigation |
| [Risk description] |
High / Medium / Low |
[Specific action to mitigate] |
Recommended Actions
Immediate (this week):
- [Action — owner — deadline]
This month:
- [Action — owner — deadline]
Before renewal:
- [Action — owner — deadline]
Renewal Forecast
| Scenario |
Probability |
ARR at risk |
| Full renewal at current ARR |
[X]% |
£/$/€0 |
| Renewal with contraction |
[X]% |
£/$/€[X] |
| Churn |
[X]% |
£/$/€[full ARR] |
Recommended renewal play: [Expand / Hold / Save / Manage out]
Deeper Materials
This skill ships with support files — use them when they are available:
references/leading-signals.md — Health Signals That Lead (Instead of Eulogise). Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.templates/account-scorecard.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.
Scoring Rubric (0–40)
Score any output of this skill before handing it over; 32+ is ship-quality.
| Dimension |
0 |
5 |
10 |
| Score integrity |
Weighted total doesn't compute from the dimension scores and stated weights, or the RAG band contradicts the total |
Arithmetic is correct but weights were adjusted silently, or the headline RAG smooths over a dimension that tells a different story |
Total computes exactly (score × weight on the 1–5 scale, out of 100), RAG matches the 80/60 bands, and any dimension that contradicts the overall status is called out rather than averaged away |
| Evidence per dimension |
Dimension scores asserted with no supporting data ("engagement feels weak") |
Most dimensions cite data, but at least one score leans on gut feel or a stale data point presented as current |
Every dimension score is anchored to named, dated evidence (usage figures, ticket counts, QBR dates, seat utilisation) and benchmarks are applied where the format provides them |
| Risk specificity |
Risks are labels ("low engagement", "churn risk") with no people, dates, or dollar amounts |
Risks are real but partially vague — severity assigned without a mitigation, or mitigations without owners |
Every risk names the person/event/amount involved ("champion departs 25 July, no successor"), carries a severity, and has a mitigation someone could start this week |
| Renewal calibration |
Forecast missing, probabilities don't sum to 100%, or the recommended play ignores the score |
Forecast present and sums correctly, but ARR-at-risk figures don't reconcile to contract line items, or the play is generic |
Probabilities sum to 100%, ARR at risk maps to actual contract components, the play (Expand/Hold/Save/Manage out) follows from the score and risks, and actions are owned, dated, and sequenced against the renewal date |
Quality Checks
Anti-Patterns
1---2name: cs-health-scorecard3description: Build a customer health scorecard for a specific account. Use when asked to score account health, assess renewal risk, build a health dashboard, or evaluate an account's likelihood to renew or expand. Produces a structured health scorecard with a RAG status, dimension scores, key risks, and recommended actions.4---5
6# Customer Health Scorecard Skill
7
8Produce a structured, data-driven health scorecard for a customer account — giving the CSM and leadership a clear view of renewal risk, expansion potential, and the actions needed to move the account in the right direction.
9
10## Reads from / Writes to the Brain
11
12If a [`professional-brain`](../professional-brain/SKILL.md) (`brain/`) exists, ground in it instead of re-asking for what you already know:
13
14- **Read first:** the account's `entities/` file, its `stakeholders/` (champion, economic buyer, detractors), and `knowledge/`. Run `python3 ../professional-brain/scripts/brain_query.py ./brain "<account name>"` and carry each fact's provenance tag through.
15- **📥 Propose to the Brain:** after producing, propose recording the health verdict + key risks to the account `entities/` file, and a renewal-risk entry to `decisions/` if a call is made, each provenance-tagged. Show them, get a yes, then write with `../professional-brain/scripts/brain_write.py … --commit` (append-only, dry-run by default).
16
17## Required Inputs
18
19Ask for these if not already provided:
20- **Account name** and tier (enterprise / mid-market / SMB)
21- **Contract value** (ARR) and **renewal date**
22- **Product usage data** — logins, DAU/MAU ratio, key feature adoption
23- **Support data** — open tickets, CSAT or NPS score, recent escalations
24- **Engagement data** — last QBR date, executive sponsor status, champion name
25- **Commercial data** — payment history, expansion conversations, seats used vs. licensed
26- **Any known risks or recent changes** at the account
27
28## Scoring Framework
29
30Score each dimension 1–5. Weight as shown. Calculate weighted total out of 100.
31
32| Dimension | Weight | What to Score |
33|---|---|---|
34| **Product Adoption** | 30% | DAU/MAU ratio, breadth of features used, power users identified |
35| **Engagement** | 20% | QBR cadence, executive sponsor active, champion strength |
36| **Outcomes** | 20% | Customer hitting their stated goals / success metrics |
37| **Support Health** | 15% | Ticket volume trend, unresolved escalations, CSAT |
38| **Commercial** | 15% | On-time payments, seats utilised, expansion signals |
39
40**Score → RAG conversion:**
41- 80–100: Green (healthy, renew likely)
42- 60–79: Amber (at risk, needs attention)
43- 0–59: Red (high churn risk, escalate)
44
45## Programmatic Helper
46
47This skill ships with a stdlib-only Python script that applies the weights above and converts the weighted total to a RAG status — so the headline score is computed identically every time and weights always sum to 100%.
48
49```bash
50# Five scores 1-5 in order: adoption engagement outcomes support commercial
51python3 scripts/health_score.py --scores 4 3 4 2 5 --account "Acme Corp"
52
53# Or from JSON (lets you override the default weights per account/segment)
54python3 scripts/health_score.py --input account.json
55```
56
57It returns the per-dimension weighted points, the **total out of 100**, and the **RAG band** (Green ≥80, Amber 60–79, Red <60) with a one-line next step. Run it to set the headline number, then write the dimension detail and actions below around it. Add `--json` for downstream tooling.
58
59## Output Format
60
61---
62
63# Customer Health Scorecard: [Account Name]
64
65**CSM:** [Name] | **Tier:** [Enterprise / Mid-Market / SMB]
66**ARR:** £/$/€[X] | **Renewal date:** [Date] | **Days to renewal:** [N]
67**Overall health:** [Green / Amber / Red] — [Score]/100
68**Last updated:** [Date]
69
70---
71
72## Health Score Summary
73
74| Dimension | Score (1–5) | Weight | Weighted Score | Trend |
75|---|---|---|---|---|
76| Product Adoption | [1–5] | 30% | [X] | ↑ / → / ↓ |
77| Engagement | [1–5] | 20% | [X] | ↑ / → / ↓ |
78| Outcomes | [1–5] | 20% | [X] | ↑ / → / ↓ |
79| Support Health | [1–5] | 15% | [X] | ↑ / → / ↓ |
80| Commercial | [1–5] | 15% | [X] | ↑ / → / ↓ |
81| **Total** | — | 100% | **[X]/100** | |
82
83---
84
85## Dimension Detail
86
87### Product Adoption — [Score]/5
88- **DAU/MAU ratio:** [X]% (benchmark: >25% = healthy)
89- **Key features adopted:** [List features in use]
90- **Features not adopted:** [List unused high-value features]
91- **Power users identified:** [Yes / No — how many]
92- **Assessment:** [1–2 sentences on adoption health]
93
94### Engagement — [Score]/5
95- **Last QBR:** [Date] — [Outcome summary]
96- **Next QBR:** [Scheduled / Overdue]
97- **Executive sponsor:** [Active / Passive / Vacant]
98- **Champion:** [Name, role, strength: strong / moderate / weak]
99- **Assessment:** [1–2 sentences]
100
101### Outcomes — [Score]/5
102- **Customer's stated goals:** [List 2–3 goals from onboarding or last QBR]
103- **Progress against goals:** [On track / Partial / Off track]
104- **Evidence of value:** [Metric or quote that demonstrates ROI]
105- **Assessment:** [1–2 sentences]
106
107### Support Health — [Score]/5
108- **Open tickets:** [N] (priority breakdown: P1: X, P2: X, P3: X)
109- **CSAT / NPS:** [Score] (benchmark: >8 CSAT / >30 NPS = healthy)
110- **Unresolved escalations:** [Yes / No — details if yes]
111- **Ticket trend (last 90 days):** Increasing / Stable / Decreasing
112- **Assessment:** [1–2 sentences]
113
114### Commercial — [Score]/5
115- **Seats licensed:** [N] | **Seats active:** [N] ([X]% utilisation)
116- **Payment history:** [On time / Late — details]
117- **Expansion signals:** [Yes — describe / No]
118- **Downgrade or cancellation signals:** [Yes — describe / No]
119- **Assessment:** [1–2 sentences]
120
121---
122
123## Top Risks
124
125| Risk | Severity | Mitigation |
126|---|---|---|
127| [Risk description] | High / Medium / Low | [Specific action to mitigate] |
128
129---
130
131## Recommended Actions
132
133**Immediate (this week):**
1341. [Action — owner — deadline]
135
136**This month:**
1371. [Action — owner — deadline]
138
139**Before renewal:**
1401. [Action — owner — deadline]
141
142---
143
144## Renewal Forecast
145
146| Scenario | Probability | ARR at risk |
147|---|---|---|
148| Full renewal at current ARR | [X]% | £/$/€0 |
149| Renewal with contraction | [X]% | £/$/€[X] |
150| Churn | [X]% | £/$/€[full ARR] |
151
152**Recommended renewal play:** [Expand / Hold / Save / Manage out]
153
154---
155
156## Deeper Materials
157
158This skill ships with support files — use them when they are available:
159
160- **`references/leading-signals.md`** — Health Signals That Lead (Instead of Eulogise). Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
161- **`templates/account-scorecard.md`** — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.
162
163## Scoring Rubric (0–40)
164
165Score any output of this skill before handing it over; 32+ is ship-quality.
166
167| Dimension | 0 | 5 | 10 |
168|---|---|---|---|
169| Score integrity | Weighted total doesn't compute from the dimension scores and stated weights, or the RAG band contradicts the total | Arithmetic is correct but weights were adjusted silently, or the headline RAG smooths over a dimension that tells a different story | Total computes exactly (score × weight on the 1–5 scale, out of 100), RAG matches the 80/60 bands, and any dimension that contradicts the overall status is called out rather than averaged away |
170| Evidence per dimension | Dimension scores asserted with no supporting data ("engagement feels weak") | Most dimensions cite data, but at least one score leans on gut feel or a stale data point presented as current | Every dimension score is anchored to named, dated evidence (usage figures, ticket counts, QBR dates, seat utilisation) and benchmarks are applied where the format provides them |
171| Risk specificity | Risks are labels ("low engagement", "churn risk") with no people, dates, or dollar amounts | Risks are real but partially vague — severity assigned without a mitigation, or mitigations without owners | Every risk names the person/event/amount involved ("champion departs 25 July, no successor"), carries a severity, and has a mitigation someone could start this week |
172| Renewal calibration | Forecast missing, probabilities don't sum to 100%, or the recommended play ignores the score | Forecast present and sums correctly, but ARR-at-risk figures don't reconcile to contract line items, or the play is generic | Probabilities sum to 100%, ARR at risk maps to actual contract components, the play (Expand/Hold/Save/Manage out) follows from the score and risks, and actions are owned, dated, and sequenced against the renewal date |
173
174## Quality Checks
175
176- [ ] Score is based on data, not gut feel — each dimension has evidence
177- [ ] Risks are specific (not "low engagement" — something like "executive sponsor left in March, no replacement identified")
178- [ ] Actions have owners and deadlines
179- [ ] Renewal probability is calibrated against pipeline reality
180- [ ] Trend arrows reflect direction of change vs. last scorecard, not just current state
181
182## Anti-Patterns
183
184- [ ] Do not score health dimensions on gut feel — every score needs specific supporting evidence
185- [ ] Do not give a Green status to accounts with unresolved P1 issues or missed milestones
186- [ ] Do not list risks vaguely — "low engagement" without specifics is not actionable
187- [ ] Do not leave recommended actions without named owners and deadlines
188- [ ] Do not conflate product usage frequency with product value delivery
Mohit Aggarwal