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
npx skills add ruvnet/ruflo --skill cost-anomaly -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/cost-anomaly/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cost-anomaly/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-anomaly -a codex2Manually: put the files in place
.agents/skills/cost-anomaly/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-anomaly -a cursor2Manually: put the files in place
.cursor/skills/cost-anomaly/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ruvnet/ruflo plugins/ruflo-cost-tracker/skills/cost-anomaly2Manually: put the files in place
.github/skills/cost-anomaly/SKILL.md1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-anomaly -a gemini-cli2Platform CLI
gemini skills install https://github.com/ruvnet/ruflo --path plugins/ruflo-cost-tracker/skills/cost-anomalyManually: put the files in place
.devin/skills/cost-anomaly/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-anomaly -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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