Health Scoring

skill

Pull usage and support data via API, compute a health score, and write an account health file.

Download .md

Health Scoring

Pull usage and support data via API, compute a per-account health score, and write an account health file for downstream review.

When to use

  • A recurring health-check cadence (weekly or monthly) is due for an account.
  • A customer-success owner asks for a current health snapshot before a renewal or QBR (quarterly business review).
  • Support ticket volume or usage patterns look unusual and need a scored assessment.
  • Onboarding a new account into the health-monitoring rotation.

Tools

  • http-get: read usage metrics and support ticket data from the org's product analytics and support platforms.
  • shell-execute: run a small script to normalize the pulled data and compute the composite health score.
  • write-file: save the resulting account health file (score, inputs, trend) to the workspace.

Playbook

  1. Confirm the account identifier and the reporting window (e.g. trailing 30 days) before pulling any data.
  2. Call the product analytics REST API with http-get (e.g. GET https://api./v1/accounts/{id}/usage) to fetch login counts, active seats, and feature adoption. Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  3. Call the support platform REST API with http-get (e.g. GET https://api./v2/tickets?account_id={id}) to fetch open ticket count, severity mix, and average resolution time. Apply the same Integration and auth-failure handling as above.
  4. If either API call returns an empty or zero-record result, re-check the account identifier and date-range parameters before concluding the account has no activity.
  5. Use shell-execute to run a short script that normalizes usage and support fields into comparable ranges (e.g. 0-100 scales).
  6. Use shell-execute to combine the normalized inputs into a single composite health score using a documented, consistent weighting (e.g. usage 60%, support 40%).
  7. Use shell-execute to compare the new score against the prior period's score (if available) to compute a trend direction.
  8. Use write-file to save an account health file containing the score, its component inputs, the trend, and the reporting window.
  9. If any input data looks stale, inconsistent, or an API repeatedly errors, escalate via send-message rather than publishing a score built on incomplete data.

Failure modes

  • 401/403 from either API -> missing Integration row; stop and escalate to a human via send-message, naming the service and required scopes.
  • Empty result set from usage or support API -> verify the account identifier and date-range parameters are correct before retrying.
  • Rate limit (429) response -> back off and retry later; note the rate limit in memory via update-memory so future runs pace requests.
  • Underlying support or analytics platform has no read endpoint for a needed field, or would require a write-back (PATCH/PUT/DELETE) to the source system -> this skill only reads and computes; any correction to source data is NOT POSSIBLE here and must be handed off to a human via send-message.

Done when

  • An account health file has been written via write-file containing the composite score, its component inputs, and the trend.
  • Both the usage and support data pulls succeeded (or failures were escalated) before the score was computed.
  • The health file's reporting window and account identifier are unambiguous and match the request.