How do I install the Cost Anomaly skill?

Run npx skillmds@latest add gabrielmoreira/cost-anomaly in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Cost Anomaly safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Cost Anomaly?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Cost Anomaly free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Cost Anomaly?

gabrielmoreira (@gabrielmoreira) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Cost Anomaly by gabrielmoreira — Agent Skill

Name: Cost Anomaly
Rating: 4.2 (5 reviews)
Author: gabrielmoreira

Cost Anomaly

MAD-based outlier detection on session spend. Robust to the very outliers it hunts (unlike mean+sigma). Surfaces specific anomalous sessions with modified-z scores; optional --alert-on-outliers exit code for CI gates. Distinct from cost-burn (aggregate trend) — this answers "which INDIVIDUAL session is the outlier?".

gabrielmoreira Updated Sep 9, 2026 17 repo stars

File contents

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.

Read all session-* records from cost-tracking namespace.
Filter to --since window (default: all-time).
Compute median(total_cost_usd) and MAD = 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

---name: cost-anomalydescription: MAD-based outlier detection on session spend. Robust to the very outliers it hunts (unlike mean+sigma). Surfaces specific anomalous sessions with modified-z scores; optional --alert-on-outliers exit code for CI gates. Distinct from cost-burn (aggregate trend) — this answers "which INDIVIDUAL session is the outlier?".--- 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 |

Frequently asked questions