stripe-refund-auditor

name	stripe-refund-auditor
description	Audits Stripe refunds over a date range to surface anomalies (refund-rate spikes, missing reasons, duplicate refunds). Activates when the user asks to "audit refunds", "check Stripe refund anomalies", or "review refund activity".
version	1.0.0
allowed-tools	Bash, Read, Write
mcp-deps	["stripe"]
secrets	["STRIPE_API_KEY"]
runtime-python	>=3.10
runtime-pip	["stripe>=8","pydantic>=2"]
integration-runner	pytest
integration-file	tests/integration_test.py
integration-requires	["STRIPE_API_KEY"]
metadata	{"category":"finance","tags":["stripe","finance","audit"]}

/stripe-refund-auditor

Audit Stripe refunds over a date range to surface anomalies — refund-rate spikes, missing reasons, suspicious duplicates — and emit a markdown report.

When to use

Trigger when the user asks any of:

• "Audit our Stripe refunds for the last 30 days"
• "Check refund anomalies in Stripe"
• "Review refund activity since {date}"

What this skill does

1. Read STRIPE_API_KEY from the environment (or .env.local next to this skill).
2. Run scripts/audit.py with the requested date range. The script paginates through /v1/refunds and emits a JSON record per refund.
3. Run scripts/grader.py over the JSON output to compute a deterministic anomaly score in [0, 1].
4. Render a markdown report listing the highest-scoring anomalies with their id, amount, currency, status, and reason.

Files in this skill

• scripts/audit.py — the deterministic refund-pull + anomaly-detection helper.
• scripts/grader.py — pure-function grader producing a 0..1 numeric score.
• tests/integration_test.py — pytest integration test (skipped without STRIPE_API_KEY).
• references/refund-schema.md — Stripe Refund object field reference.
• evals/evals.json — LLM-judged behavioral evaluation cases.
• .env.example — placeholder template; copy to .env.local and fill in real values.

Preflight

Before invoking, run vskill check stripe-refund-auditor to verify:

• The Stripe MCP server is configured in your Claude config.
• STRIPE_API_KEY is resolvable from env or .env.local.
• Python >=3.10 is on PATH.
• pytest --collect-only tests/ succeeds.

Step 1 — Pull refunds. Run this immediately:

python3 scripts/audit.py --since "$(date -u -v-30d +%Y-%m-%d)" --until "$(date -u +%Y-%m-%d)" > /tmp/refunds.jsonl

Step 2 — Score anomalies. Run this immediately:

python3 scripts/grader.py /tmp/refunds.jsonl > /tmp/refund-scores.json

Step 3 — Render the report. Run this immediately:

python3 -c "import json,sys; data=json.load(open('/tmp/refund-scores.json')); print(json.dumps({'top_anomalies': data['anomalies'][:10], 'score': data['overall_score']}, indent=2))"

The skill's caller is expected to take the JSON from Step 3 and turn it into prose. See references/refund-schema.md for the underlying field semantics.

Failure modes

• STRIPE_API_KEY missing → audit.py exits with code 2 and prints a diagnostic line. Run vskill check stripe-refund-auditor to see which env source is searched.
• Empty result set → grader.py returns {"overall_score": 0.0, "anomalies": []}.
• Network failure → audit.py exits non-zero and the message includes the underlying HTTP status. Re-run after fixing connectivity.