Cost Anomaly Detection
FreeIdentify individual spending outliers in session data.
Free · Opens the source repo
What Cost Anomaly Detection does
Cost Anomaly Detection is a specialized tool designed to pinpoint anomalous spending in session data using a robust statistical approach. Unlike traditional methods that rely on mean and standard deviation, this skill employs Median Absolute Deviation (MAD) for outlier detection, making it resilient to the very anomalies it aims to identify. This ensures that even in datasets with extreme values, the detection remains accurate and reliable. The skill calculates modified z-scores for each session, allowing users to determine which sessions deviate significantly from typical spending patterns.
The skill operates by reading session records from the cost-tracking namespace and filtering them based on a specified time window. By calculating the median total cost and MAD, it flags sessions with modified z-scores exceeding a defined threshold, typically set at 3.5. This approach is particularly useful for teams looking to maintain budgetary control and identify rogue spending that could impact financial forecasts. The ability to integrate with CI pipelines through alert exit codes further enhances its utility, allowing for automated checks on spending anomalies as part of the development workflow.
Cost Anomaly Detection is particularly beneficial for developers and financial analysts who need to monitor and analyze cost behaviors in real-time. By providing insights into individual session outliers, it complements aggregate trend analysis tools like cost-burn, enabling a comprehensive understanding of spending patterns. This dual approach helps teams not only assess whether overall spending is accelerating but also to investigate specific sessions that may warrant further scrutiny.
In summary, this skill is an essential addition for any team focused on financial oversight and session tracking, providing a clear mechanism to detect and address unusual spending behaviors efficiently.
When to use it
Use this tool when you need to detect specific outlier sessions in your cost data, especially when monitoring for unexpected spending spikes.
When not to use it
This skill is not suitable for general cost analysis or aggregate trend monitoring; it focuses solely on identifying individual session anomalies.
What you can build with it
Monitoring Weekly Spending
Integrate the skill into your CI pipeline to automatically check for outlier sessions in the past week.
Investigating Cost Spikes
Use this tool to identify specific sessions that caused a sudden increase in spending, allowing for targeted analysis.
Budget Compliance Checks
Regularly run this skill to ensure that no individual session exceeds expected spending thresholds, maintaining budget compliance.
How to install Cost Anomaly Detection
View source1. Install with the skills CLI
npx skills add ruvnet/ruflo/cost-anomaly --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by ruvnetPer-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.
- Read all
session-*records fromcost-trackingnamespace. - Filter to
--sincewindow (default: all-time). - Compute
median(total_cost_usd)andMAD = median(|x - median|). - Per-session modified z-score (Iglewicz-Hoaglin 1993):
z = 0.6745 * (x - median) / MAD - 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
# 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:
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 |
Frequently asked questions about Cost Anomaly Detection
Similar skills
Initiating Coverage
Create institutional-quality equity research reports.
Financial Tear Sheet Generator
Create professional company profiles with live data.
Pitch Deck Population
Effortlessly fill pitch deck templates with data.
Tax Season Organizer
Streamline your tax prep for accountants.
Month End Prep
Streamline your month-end close process with ease.
Funding Digest
Summarize funding rounds in a single slide.