ZenUml/conf-app / .claude/skills/client-health
client-health
VerifiedRank active ZenUML Lite tenants on two independent 0-100 scores — Opportunity (upsell candidate) and Risk (disengagement) — to decide which clients to focus on. Use whenever the user asks "which clients should we focus on", "who's a good upsell candidate", "which tenants are at risk of churning", "health score", or wants a ranked list of Lite tenants by engagement strength or fragility. Scope: Lite only, active tenants only (macro_viewed > 0 in the scoring window). For a SINGLE named tenant's paid status/profile use the `tenant` skill instead; for lifetime revenue/renewals/overdue payers use `marketplace`.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| scripts/health_score.py | script | 17.7 KB |
| scripts/percentile.py | script | 1.3 KB |
| scripts/test_health_score.py | script | 22.0 KB |
| scripts/test_percentile.py | script | 1.8 KB |
SKILL.md
View on GitHub---
name: client-health
description: >
Rank active ZenUML Lite tenants on two independent 0-100 scores —
Opportunity (upsell candidate) and Risk (disengagement) — to decide
which clients to focus on. Use whenever the user asks "which clients
should we focus on", "who's a good upsell candidate", "which tenants
are at risk of churning", "health score", or wants a ranked list of
Lite tenants by engagement strength or fragility. Scope: Lite only,
active tenants only (macro_viewed > 0 in the scoring window). For a
SINGLE named tenant's paid status/profile use the `tenant` skill
instead; for lifetime revenue/renewals/overdue payers use `marketplace`.
---
# Client Health Scoring
Two independent percentile scores per active Lite tenant:
- **Opportunity** — seat tier + ARR potential, adoption breadth, usage
volume, growth trend, paywall friction. Higher = stronger upsell
candidate.
- **Risk** — declining trend, recency of last activity, thin adoption
breadth. Higher = more likely to disengage.
A tenant can rank high on one and low on the other — they are never
combined into a single number. See
[docs/superpowers/specs/2026-09-04-client-health-scoring-design.md](../../../docs/superpowers/specs/2026-09-04-client-health-scoring-design.md)
for the full design and the reasoning behind each signal (and which
signals were considered and explicitly excluded).
## Usage
```bash
S=.claude/skills/client-health/scripts/health_score.py
python3 $S # top 20 by Opportunity, 90-day window
python3 $S --sort risk --top 10 # top 10 by Risk instead
python3 $S --days 60 # minimum window (growth_trend needs a
# full 30-vs-30-day split; --days < 60
# is rejected)
python3 $S --json # machine-readable output
```
Credentials: same as the `marketplace` and `mixpanel` skills —
`FORGE_EMAIL`/`FORGE_API_TOKEN` (auto-discovered from `.env.forge.local`,
override with `--env`) and `.env.mixpanel`'s `API_Secret`.
Unit tests (no network, no credentials):
```bash
python3 -m unittest discover -s .claude/skills/client-health/scripts
```
## Reading the output
Each row includes the raw signals alongside the two composite scores —
`adoption_breadth%`, `usage_volume`, `growth_trend%`,
`days_since_last_event`, `paywall_friction` — so you can sanity-check a
ranking rather than just trust the number, the same transparency
principle the `marketplace` skill's tables follow.
A tenant with near-identical seat tier and usage volume to another can
still score very differently — that was the finding that motivated this
skill (see the design doc's "Purpose" section): usage volume alone
doesn't distinguish broad real adoption from a handful of people
generating heavy repeat views.
This system is Lite-only and does not cross-reference Full entitlement:
a tenant that already has Full (paying) can still show up highly ranked
on Opportunity if they also have a leftover Lite install with real
usage. Sanity-check a top-ranked domain against the `tenant` skill
before treating it as a genuine upsell candidate.
## Related
- `marketplace` — lifetime revenue, renewals, overdue payers, pricing
(`mp_pricing.py`, reused here for ARR potential).
- `mixpanel` — event names, project id, internal-domain filter
(reused here via `mp_query.py`).
- `tenant` — single-tenant lookup ("is X paying", "how big is X").
- `paywall` — CSS enrollment and paywall friction mechanics (the
`paywall_friction` signal here is a coarse count, not the full
A/B analysis that skill does). It counts `paywall_gate_evaluated`
events where the gate fired, or the space is over its limit, enforced
and unpaid. The older `paywall_triggered` / `paywall_blocked_*` events
stopped on 2026-09-11 when the editor block was switched off.
## Customer follow-up boundary
This score ranks active Lite sites within its cohort. It does not verify whether the same site already has Full or whether a person can buy. Before an upgrade decision, use `tenant` for cross-product licenses/payments and verify the contact role. Return unknown if that check was not made. For the cross-product check over the whole ranking, pass `--json` output to `customer-followup/scripts/behaviour_targets.py`: it marks sites that pay for another app as `skip` and adds contact and partner fields. Known placeholder accounts are excluded from creator counts; activity window, anonymity and prior-window-zero caveats still apply. Use `customer-followup` for the final decision and authorised action.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |