investigating-metric-anomalies skill for Claude Code: anomaly triage
investigating-metric-anomalies turns a PostHog Metrics symptom (rising lag, error spike, falling throughput) into a probable cause backed by logs and traces.
no license 206 installs ★ 101 updated 2026-10-24
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a claude-codeWhat investigating-metric-anomalies does
Starts from a symptom in PostHog Metrics and works toward a cause you can defend. The metric name comes first: metric-names-list takes a fragment such as lag or error, and the type it returns decides the lens, since counters only make sense as a rate or increase, gauges as an average, histograms as a quantile.
One call to characterize-metric-anomaly with anomalyFrom answers three things: how far the value moved, when it started (onset_time), and which label values shifted (top_movers). A single pod or shard in the movers points at a local fault; everything moving at once points upstream. query-metrics then tests those guesses with filters and formulas like errors / requests, and logs (query-logs) plus spans (query-apm-spans) get pulled for the same service in a window around onset_time.
It runs on a project that already has PostHog Metrics and the PostHog MCP tools wired up. Without them there is nothing to call. Scraped Prometheus series also lag real time by 15–60 seconds, so the newest bucket is not the current value.
What it helps with
- pin down which metric an alert refers to
- date the onset of a spike from the alert time
- split a single-pod fault from a shared upstream cause
- separate a real error increase from a traffic jump
- tie a metric spike to a process restart in the logs
Example prompts for the agent
- Ingestion lag is climbing since 20:10 — find the metric and show what moved.
- Investigate
logs_rate_limiter_message_lag_secondsfrom the alert time and check that service's logs around the onset. - Error rate on the checkout endpoint is spiking; look at metrics first, then spans and logs for the same window.
How to install investigating-metric-anomalies
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a claude-code2Manually: put the files in place
~/.claude/skills/investigating-metric-anomalies/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/investigating-metric-anomalies/
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a codex2Manually: put the files in place
.agents/skills/investigating-metric-anomalies/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a cursor2Manually: put the files in place
.cursor/skills/investigating-metric-anomalies/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install PostHog/ai-plugin skills/investigating-metric-anomalies2Manually: put the files in place
.github/skills/investigating-metric-anomalies/SKILL.md1Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a gemini-cli2Platform CLI
gemini skills install https://github.com/PostHog/ai-plugin --path skills/investigating-metric-anomaliesManually: put the files in place
.devin/skills/investigating-metric-anomalies/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -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 investigating-metric-anomalies
How do I install investigating-metric-anomalies in Claude Code?
Run npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a claude-code; the skill lands at ~/.claude/skills/investigating-metric-anomalies/SKILL.md.
What does investigating-metric-anomalies do?
It takes an anomaly from symptom to evidence: identifies the metric, measures the shift and its onset, then looks for what changed in the logs and traces at that moment.
What does it need to work?
A project with PostHog Metrics and the PostHog MCP tools in place: metric listing, anomaly characterization, metric queries, log queries and APM spans. The whole loop runs on those calls.