Skip to main content
skill CX Codex

cost-anomaly — Claude Code skill for session outliers

The cost-anomaly Claude Code skill detects individual sessions with unusual spend and reports their modified z-scores. It runs when a request is about pinpointing a costly outlier session rather than tracking an aggregate trend.

MIT 248 installs ★ 82,234 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ruvnet/ruflo --skill cost-anomaly -a claude-code
Open on GitHub

What cost-anomaly does

The skill reads per-session costs from the cost-tracking namespace and reports outliers using the median and MAD. Set the analysis window with --since and the cutoff with --threshold; --format selects table or JSON output.

For CI checks, --alert-on-outliers sets the outlier count that triggers a nonzero exit code. With fewer than three sessions, the skill reports insufficient data and exits with code 0. When MAD is zero, it prints an explanation instead of dividing by zero.

What it helps with

  • identify sessions with unusually high or low spend
  • compare each session's cost with the median
  • fail a CI check when the outlier count reaches a threshold
  • inspect modified z-scores in JSON output

Example prompts for the agent

  • Find sessions with unusual spend over the last 7 days.
  • List individual cost outliers and return their scores as JSON.
  • Make the CI check fail if at least one session is an outlier.

How to install cost-anomaly

1Skills CLI (Vercel)

npx skills add ruvnet/ruflo --skill cost-anomaly -a claude-code

2Manually: put the files in place

~/.claude/skills/cost-anomaly/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cost-anomaly/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cost-anomaly

How do I install cost-anomaly in Claude Code?

Run npx skills add ruvnet/ruflo --skill cost-anomaly -a claude-code. The skill file is located at ~/.claude/skills/cost-anomaly/SKILL.md.

What does cost-anomaly do?

It finds individual sessions whose spend differs from the median, using MAD to calculate modified z-scores. The --alert-on-outliers option supports CI checks.

What happens when there are fewer than three sessions?

The skill reports insufficient data and exits with code 0.

Source text

SKILL.md · MIT
---
name: cost-anomaly
description: "MAD-based outlier detection on session spend: lists anomalous sessions with modified-z scores, with an optional --alert-on-outliers exit code for CI. Use when asked which individual session is the cost outlier; cost-burn covers the aggregate trend."
argument-hint: "[--since 7d] [--threshold 3.5] [--alert-on-outliers N] [--format table|json]"
allowed-tools: Bash
disable-model-invocation: true
---

Per-session outlier detection — the diagnostic counterpart to cost-burn's
aggregate-trend signal.

| Question | Skill |
|---|---|
| "Is the AGGREGATE rate accelerating?" | `cost-burn` |
| "Which SPECIFIC sessions are anomalous outliers?" | **`cost-anomaly`** ← this |
| "Could we have spent less in aggregate?" | `cost-counterfactual` |
| "When will we hit budget?" | `cost-projection` |

## Algorithm

Implementation: [`scripts/anomaly.mjs`](../../scripts/anomaly.mjs).

1. Read all `session-*` records from `cost-tracking` namespace.
2. Filter to `--since` window (default: all-time).
3. Compute `median(total_cost_usd)` and `MAD = median(|x - median|)`.
4. Per-session modified z-score (Iglewicz-Hoaglin 1993):
   `z = 0.6745 * (x - median) / MAD`
5. Flag sessions with `|z| > --threshold` (default 3.5).

## Why MAD and not mean + sigma?

| Approach | What breaks |
|---|---|
| `mean + sigma` | A single $50 session inflates BOTH mean and sigma so badly that subsequent outliers hide inside the new "normal" band. Catastrophic on small samples. |
| `median + MAD` | Both estimators ignore up to 50% of the data — the outliers themselves can't shift them. Robust on n=10. The canonical cutoff `\|z\| > 3.5` is from Iglewicz-Hoaglin (1993). |

## Smoke transcript (5 baseline sessions $0.08-$0.12 + 1 outlier $5.00)

```
| Sessions considered | 5 |
| Threshold (|modified z|) | 3.5 |
| Median spend | $0.100000 |
| MAD | $0.010000 |
| Min / Max | $0.080000 / $5.000000 |
| **Outliers found** | **1** |

## Outlier sessions
| Session | Spend | Deviation | Modified z | Direction |
| outlier- | $5.000000 | +$4.900000 | 330.505 | high |
```

## Exit codes

```
$ cost anomaly --alert-on-outliers 1
⚠ ALERT: found 1 outlier session(s) (|modified z| > 3.5); threshold was ≥1
exit 1

$ cost anomaly --alert-on-outliers 5
✓ found 1 outlier session(s); under threshold ≥5 — OK
exit 0
```

## CI integration

```bash
# Fail the build if any session this week is a >3.5σ outlier
cost anomaly --since 7d --alert-on-outliers 1 || investigate-bad-session
```

Most useful when paired with `cost-burn`:

```bash
cost burn  --alert-on-acceleration-pct 50  || page-oncall   # rate-of-change alert
cost anomaly --alert-on-outliers 1         || investigate   # point-anomaly alert
```

Together they cover "is the average shifting?" AND "is there a single rogue
session?" — both can fire independently.

## Edge cases

- **n < 3**: emit "Insufficient data" message, exit 0. MAD on 1-2 samples is meaningless.
- **MAD = 0**: ≥50% of sessions share the exact same spend, so z-scores collapse. Emit explainer instead of dividing by zero. Common cause: dry-run sessions all at $0.
- **Low-direction outliers**: usually crashed or dropped sessions, not over-spending. The output table explicitly labels direction so operators interpret correctly.
- **Very small MAD**: even tiny absolute deviations produce huge z-scores. The $5 outlier with MAD=$0.01 yields z=330 — that's correct, not a bug.

## Direction column

| Direction | Likely cause | Action |
|---|---|---|
| `high` | Long session, stuck in expensive tier, or runaway loop | `cost report` + `cost conversation` to investigate |
| `low` | Crash, dropped session, or unfinished work | Verify the session completed normally |

© ruvnet · MIT · ruvnet/ruflo

Similar skills

All skills for Finance and business →

From the same set155

The whole set →
cost-session cost-session is a Claude Code skill that breaks down costs per message in a session to reveal expensive requests. CX Codex +1 249installs cost-projection The cost-projection Claude Code skill projects future spend from recent session data. It estimates daily costs and shows when configured budget thresholds may be reached. CX Codex +1 249installs cost-health cost-health runs four cost checks at once and returns a single status: budget, burn acceleration, session outliers and days left before the budget is gone. CX Codex +1 249installs cost-counterfactual cost-counterfactual evaluates LLM routing by comparing actual session spend against hypothetical always-haiku, always-sonnet, and always-opus baselines. Useful for tracking over-escalation and ROI. CX Codex +1 249installs cost-diff The cost-diff Claude Code skill compares two JSON snapshots of spending. Use it to detect cost changes between a baseline and a pull request branch. CX Codex +1 248installs cost-burn cost-burn — a skill for Claude Code and other platforms that observes production spend trends. It triggers in CI to detect if daily spend acceleration exceeds a specified threshold. CX Codex +1 248installs Ruflo The Ruflo MCP server for Claude Code and Codex coordinates agent teams and keeps memory across sessions. After init, hooks route tasks and coordinate agents in the background. CX Codex +1 ★ 82,234repo stars claude-flow Connect Claude Code to claude-flow tools for agent coordination and shared task context. The MCP setup uses ANTHROPIC_API_KEY. CX Codex +1 ★ 82,234repo stars

Project sponsors

Companies that keep this analytics open