| 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
- Read
STRIPE_API_KEY from the environment (or .env.local next to this skill).
- Run
scripts/audit.py with the requested date range. The script paginates
through /v1/refunds and emits a JSON record per refund.
- Run
scripts/grader.py over the JSON output to compute a deterministic
anomaly score in [0, 1].
- 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.