Calculate a customer health score and review churn or expansion signals from SaaS account data. This Skill includes three Python tools for usage, engagement, support, relationship and revenue inputs, helping a customer-success team identify accounts that need attention and explain the rules behind each recommendation.
This Skill is designed for account-based customer success, including software sold to merchants. It reads structured JSON data and applies rules to produce health, retention-risk and expansion assessments across account segments.
Use it when your team already has the relevant customer data and needs a repeatable review process. The results support account discussions and follow-up planning; they are not machine-learning forecasts or predictions of consumer repeat purchases. CRM synchronization and customer outreach are not included.
Three standard-library Python tools separate account health, churn risk and expansion assessment. Keeping those views distinct helps a team avoid treating an active account as automatically ready for an upsell or a support-heavy account as certain to cancel.
The sample schemas make required account fields explicit, while rule-based outputs can be reviewed and rerun on updated exports. Check the input definitions before comparing segments, then use the recommendations to choose the next customer-success action.
Account-level usage, engagement, support, relationship, revenue, renewal, and expansion fields matching the sample schemas.
Use a Skill-capable agent with file access. Python 3 is required for the bundled Python helpers; inspect their sample schemas before supplying data.
These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.
Copy this request into Codex or Claude Code. The assistant downloads the original repository at the specified commit, installs the complete files and checks required dependencies.
Install customer-success-manager in the app I am using and carry out the file installation, not just explain it.
Original repository: https://github.com/alirezarezvani/claude-skills.git
Commit: 6d2f02ea077eead1bee5411a31bcc6db5a11a70c
Skill folder: business-growth/skills/customer-success-manager
1. Download this exact source into a new directory. Read SKILL.md and its setup references before running any bundled scripts. Do not substitute another author’s package.
2. For Codex, use ~/.agents/skills/customer-success-manager; for Claude Code, use ~/.claude/skills/customer-success-manager. Install only for my current app. Install the complete Skill folder, including scripts, references, assets and bundled notices. Keep any root license with the installed folder. Check all destination folders first; if any already exist, report differences before replacing them.
3. Compare the source and installed file lists and hashes. Inspect documented runtimes, dependencies and required connections. Configure only the local dependencies needed for this Skill; use an isolated environment when appropriate. Ask me to complete any account login locally, without putting credentials in chat.
4. Report the source commit, actual installation path, file-check results and any remaining runtime setup. Explain how to invoke customer-success-manager in this app. Check discovery separately from file copying; start a new session if needed. Do not run production tasks or claim a successful business outcome from installation alone.This is the unchanged source SKILL.md for the reviewed version. Install the complete package to retain referenced scripts, assets, and instructions. Starter prompts below are EcomAgentTools examples.
---
name: "customer-success-manager"
description: Monitors customer health, predicts churn risk, and identifies expansion opportunities using weighted scoring models for SaaS customer success. Use when analyzing customer accounts, reviewing retention metrics, scoring at-risk customers, or when the user mentions churn, customer health scores, upsell opportunities, expansion revenue, retention analysis, or customer analytics. Runs three Python CLI tools to produce deterministic health scores, churn risk tiers, and prioritized expansion recommendations across Enterprise, Mid-Market, and SMB segments.
license: MIT
metadata:
version: 1.0.0
author: Alireza Rezvani
category: business-growth
domain: customer-success
updated: 2026-02-06
python-tools: health_score_calculator.py, churn_risk_analyzer.py, expansion_opportunity_scorer.py
tech-stack: customer-success, saas-metrics, health-scoring
---
# Customer Success Manager
Production-grade customer success analytics with multi-dimensional health scoring, churn risk prediction, and expansion opportunity identification. Three Python CLI tools provide deterministic, repeatable analysis using standard library only -- no external dependencies, no API calls, no ML models.
---
## Table of Contents
- [Input Requirements](#input-requirements)
- [Output Formats](#output-formats)
- [How to Use](#how-to-use)
- [Scripts](#scripts)
- [Reference Guides](#reference-guides)
- [Templates](#templates)
- [Best Practices](#best-practices)
- [Limitations](#limitations)
---
## Input Requirements
All scripts accept a JSON file as positional input argument. See `assets/sample_customer_data.json` for complete schema examples and sample data.
### Health Score Calculator
Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `usage` (login_frequency, feature_adoption, dau_mau_ratio), `engagement` (support_ticket_volume, meeting_attendance, nps_score, csat_score), `support` (open_tickets, escalation_rate, avg_resolution_hours), `relationship` (executive_sponsor_engagement, multi_threading_depth, renewal_sentiment), and `previous_period` scores for trend analysis.
### Churn Risk Analyzer
Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, `contract_end_date`, and nested objects `usage_decline`, `engagement_drop`, `support_issues`, `relationship_signals`, and `commercial_factors`.
### Expansion Opportunity Scorer
Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `contract` (licensed_seats, active_seats, plan_tier, available_tiers), `product_usage` (per-module adoption flags and usage percentages), and `departments` (current and potential).
---
## Output Formats
All scripts support two output formats via the `--format` flag:
- **`text`** (default): Human-readable formatted output for terminal viewing
- **`json`**: Machine-readable JSON output for integrations and pipelines
---
## How to Use
### Quick Start
```bash
# Health scoring
python scripts/health_score_calculator.py assets/sample_customer_data.json
python scripts/health_score_calculator.py assets/sample_customer_data.json --format json
# Churn risk analysis
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json --format json
# Expansion opportunity scoring
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json --format json
```
### Workflow Integration
```bash
# 1. Score customer health across portfolio
python scripts/health_score_calculator.py customer_portfolio.json --format json > health_results.json
# Verify: confirm health_results.json contains the expected number of customer records before continuing
# 2. Identify at-risk accounts
python scripts/churn_risk_analyzer.py customer_portfolio.json --format json > risk_results.json
# Verify: confirm risk_results.json is non-empty and risk tiers are present for each customer
# 3. Find expansion opportunities in healthy accounts
python scripts/expansion_opportunity_scorer.py customer_portfolio.json --format json > expansion_results.json
# Verify: confirm expansion_results.json lists opportunities ranked by priority
# 4. Prepare QBR using templates
# Reference: assets/qbr_template.md
```
**Error handling:** If a script exits with an error, check that:
- The input JSON matches the required schema for that script (see Input Requirements above)
- All required fields are present and correctly typed
- Python 3.7+ is being used (`python --version`)
- Output files from prior steps are non-empty before piping into subsequent steps
---
## Scripts
### 1. health_score_calculator.py
**Purpose:** Multi-dimensional customer health scoring with trend analysis and segment-aware benchmarking.
**Dimensions and Weights:**
| Dimension | Weight | Metrics |
|-----------|--------|---------|
| Usage | 30% | Login frequency, feature adoption, DAU/MAU ratio |
| Engagement | 25% | Support ticket volume, meeting attendance, NPS/CSAT |
| Support | 20% | Open tickets, escalation rate, avg resolution time |
| Relationship | 25% | Executive sponsor engagement, multi-threading depth, renewal sentiment |
**Classification:**
- Green (75-100): Healthy -- customer achieving value
- Yellow (50-74): Needs attention -- monitor closely
- Red (0-49): At risk -- immediate intervention required
**Usage:**
```bash
python scripts/health_score_calculator.py customer_data.json
python scripts/health_score_calculator.py customer_data.json --format json
```
### 2. churn_risk_analyzer.py
**Purpose:** Identify at-risk accounts with behavioral signal detection and tier-based intervention recommendations.
**Risk Signal Weights:**
| Signal Category | Weight | Indicators |
|----------------|--------|------------|
| Usage Decline | 30% | Login trend, feature adoption change, DAU/MAU change |
| Engagement Drop | 25% | Meeting cancellations, response time, NPS change |
| Support Issues | 20% | Open escalations, unresolved critical, satisfaction trend |
| Relationship Signals | 15% | Champion left, sponsor change, competitor mentions |
| Commercial Factors | 10% | Contract type, pricing complaints, budget cuts |
**Risk Tiers:**
- Critical (80-100): Immediate executive escalation
- High (60-79): Urgent CSM intervention
- Medium (40-59): Proactive outreach
- Low (0-39): Standard monitoring
**Usage:**
```bash
python scripts/churn_risk_analyzer.py customer_data.json
python scripts/churn_risk_analyzer.py customer_data.json --format json
```
### 3. expansion_opportunity_scorer.py
**Purpose:** Identify upsell, cross-sell, and expansion opportunities with revenue estimation and priority ranking.
**Expansion Types:**
- **Upsell**: Upgrade to higher tier or more of existing product
- **Cross-sell**: Add new product modules
- **Expansion**: Additional seats or departments
**Usage:**
```bash
python scripts/expansion_opportunity_scorer.py customer_data.json
python scripts/expansion_opportunity_scorer.py customer_data.json --format json
```
---
## Reference Guides
| Reference | Description |
|-----------|-------------|
| `references/health-scoring-framework.md` | Complete health scoring methodology, dimension definitions, weighting rationale, threshold calibration |
| `references/cs-playbooks.md` | Intervention playbooks for each risk tier, onboarding, renewal, expansion, and escalation procedures |
| `references/cs-metrics-benchmarks.md` | Industry benchmarks for NRR, GRR, churn rates, health scores, expansion rates by segment and industry |
---
## Templates
| Template | Purpose |
|----------|---------|
| `assets/qbr_template.md` | Quarterly Business Review presentation structure |
| `assets/success_plan_template.md` | Customer success plan with goals, milestones, and metrics |
| `assets/onboarding_checklist_template.md` | 90-day onboarding checklist with phase gates |
| `assets/executive_business_review_template.md` | Executive stakeholder review for strategic accounts |
---
## Best Practices
1. **Combine signals**: Use all three scripts together for a complete customer picture
2. **Act on trends, not snapshots**: A declining Green is more urgent than a stable Yellow
3. **Calibrate thresholds**: Adjust segment benchmarks based on your product and industry per `references/health-scoring-framework.md`
4. **Prepare with data**: Run scripts before every QBR and executive meeting; reference `references/cs-playbooks.md` for intervention guidance
---
## Limitations
- **No real-time data**: Scripts analyze point-in-time snapshots from JSON input files
- **No CRM integration**: Data must be exported manually from your CRM/CS platform
- **Deterministic only**: No predictive ML -- scoring is algorithmic based on weighted signals
- **Threshold tuning**: Default thresholds are industry-standard but may need calibration for your business
- **Revenue estimates**: Expansion revenue estimates are approximations based on usage patterns
---
**Last Updated:** February 2026
**Tools:** 3 Python CLI tools
**Dependencies:** Python 3.7+ standard library only
Starter prompts for the main use cases—copy and use them directly.
Review account health for a merchant-software customer base Use for: Review account health for a merchant-software customer base. Prepare: Account-level usage, engagement, support, relationship, revenue, renewal, and expansion fields matching the sample schemas.
Use the installed customer-success-manager Skill. Task: Review account health for a merchant-software customer base. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.[INPUT][CONSTRAINTS]Prioritize renewal-risk accounts for human follow-up Use for: Prioritize renewal-risk accounts for human follow-up. Prepare: Account-level usage, engagement, support, relationship, revenue, renewal, and expansion fields matching the sample schemas.
Use the installed customer-success-manager Skill. Task: Prioritize renewal-risk accounts for human follow-up. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.[INPUT][CONSTRAINTS]Compare expansion opportunities and effort Use for: Compare expansion opportunities and effort. Prepare: Account-level usage, engagement, support, relationship, revenue, renewal, and expansion fields matching the sample schemas.
Use the installed customer-success-manager Skill. Task: Compare expansion opportunities and effort. Inputs: [INPUT]. Constraints: [CONSTRAINTS]. Check missing information first. Produce a reviewable result with evidence, assumptions, and next steps. These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.[INPUT][CONSTRAINTS]A homeware ecommerce team preparing a software-vendor QBR supplies usage, contract and support records to decide between onboarding improvements, seat changes and additional spend. Account data is synthetic.
Case input files: business-inputs.zip
Use the customer-success-manager Skill.
Our ecommerce operations team is preparing a quarterly review and renewal discussion for its shared order, stock and customer-support software. Use the supplied account export to assess adoption, unused capacity, support risk and renewal options. Run the Skill’s health, churn-risk and expansion analysis, but interpret ARR as our annual vendor bill and any expansion amount as additional software spend, never store revenue. Recommend onboarding actions, seat right-sizing or expansion only where usage supports it, and prepare a vendor meeting agenda with owners and success checks. We have no measured labor-saving or sales-uplift data, so do not invent an ROI.
The attached business materials are:
- inputs/business-brief.json
- inputs/software-account.json
Deliver a complete result.md report that the operations team can read, plus any finished files needed for this task. Keep supporting calculations and evidence with the deliverables. Write the report in English; use the requested target language for customer-facing copy. The business datasets are fictional examples unless the brief explicitly names a live public website.The primary file produced by this prompt is shown below in its original language.
Keep the existing 100-seat scope while checking the five inactive seats and resolving the export issue. The original Skill's three tools report health 86.2/100 (green), churn risk 0.6/100 (low) and seven expansion suggestions. The expansion output is a vendor upsell model; it is not evidence that the store needs those purchases or would earn more revenue.
| Measure | Supplied or calculated value | Merchant implication |
|---|---|---|
| Annual vendor subscription charge | $120,000 | Software expense, not merchandise revenue |
| Active / licensed seats | 95 / 100 = 95% | Five seats currently inactive; inspect intended use before cutting or adding |
| Prior seat utilization | 85% | Ten percentage-point increase; not a measured labor saving |
| Adopted modules | 3 of 5 = 60% | Identify why integrations and advanced reporting are not used |
| Module usage | Core 85%, analytics 60%, API 40% | Focus onboarding on a defined business workflow |
| Support | 2 open tickets, 18-hour average resolution, 5% escalation rate | These are snapshots; compare with the actual contractual SLA |
| Export issue | Formatting workaround; supplied ETA Nov 10 | Obtain a reproducible example and verify the eventual fix |
| Contract end | Dec 31, 2027 | 421 days from this run; no artificial immediate-renewal pressure |
Health dimensions are usage 91.6 (30%), engagement 82.0 (25%), support 78.5 (20%) and relationship 90.1 (25%). Their weighted sum is approximately 86.2. The prior overall score is 67; this is a model-score improvement, not measured commercial value. The field called nps_score is an 8/10 response under this Skill's definition, not an aggregate NPS of +8.
The scorer estimates $80,000 for a tier upgrade, $30,000 for 25 more seats, $21,600 for advanced reporting, $14,400 for integrations and $48,000 for each of three departments. Its sum is $290,000. These are model-generated potential vendor charges using generic assumptions, not a quote or a justified budget. Options can overlap and must not be blindly added to the existing bill.
At the current average $1,200 annual bill per licensed seat, five inactive seats represent a nominal $6,000 allocation. This is not guaranteed removable spend: minimum commitments, blended modules and contract terms may prevent proportional savings. Verify entitlements and the hiring/coverage plan before right-sizing. A 95% snapshot alone does not justify buying 25 extra seats.
| Owner | Action | Due / success check |
|---|---|---|
| Workspace administrator | Review five inactive seats with team leads | Within 7 days; each seat has a named business purpose or a removal proposal |
| Operations process owner | Choose one order/stock reporting workflow and document the current steps | Within 7 days; baseline completion time and error count measured before training |
| Vendor support owner | Confirm the export defect scope and Nov 10 target | On the target date, reproduce the workflow and compare the exported fields with the agreed format |
| Team training owner | Run focused onboarding for the selected workflow using existing entitlements | Within 14 days; users complete the task and unresolved issues are logged |
| Finance/procurement owner | Obtain current tier, module and seat pricing with minimums | Within 30 days; separate optional expansion from existing contractual spend |
| Operations sponsor | Review utilization and workflow evidence | Day 30; retain, right-size or pilot a module based on evidence |
Do not promise the vendor's roadmap dates: no confirmed release commitments are supplied. The named export ETA is an input to verify, not a new guarantee created by this report.
Five minutes: agree on the merchant's order, stock and support tasks and the current $120,000 annual cost. Ten minutes: review active seats, inactive-seat intent and existing module entitlements. Ten minutes: reproduce the export issue and agree on an acceptance check. Ten minutes: discuss training and a bounded workflow pilot. Five minutes: request written renewal and optional-expansion pricing with an owner and follow-up date.
No labor-hours saved, order uplift or ROI was supplied, so the QBR deliberately contains no invented return-on-investment claim. The three original JSON outputs are retained for traceability, with their vendor-oriented revenue labels interpreted as possible merchant expense in this report. No account plan, seat count or subscription was changed.
Merchant business data is synthetic. Website observations, when present, come from the public URLs listed in the report.
These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.
Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.
Use authorized inputs and keep secrets out of prompts. Review customer-facing claims, calculations, code changes, and any proposed external action before applying them.
Score SaaS account health, churn risk, and expansion opportunities from local JSON data. Three standard-library Python tools produce repeatable scores and recommendations across account segments.
Choose the method for your agent and install the complete package, not just the displayed SKILL.md. Account-level usage, engagement, support, relationship, revenue, renewal, and expansion fields matching the sample schemas. Start a new agent session and explicitly ask to use customer-success-manager. Try one use case below with a small sample and review the output.
Review account health for a merchant-software customer base; Prioritize renewal-risk accounts for human follow-up; Compare expansion opportunities and effort
These are rules-based SaaS account models, not ML forecasts or consumer repurchase predictions. No CRM connection or automatic outreach is included.
Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.
Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.
Source and package files reviewed: GitHub 6d2f02ea077e. This is a static review, not an installation or business-outcome test.
No reviews yet.