Skip to content
Back to skills

Subscription Killer

ASecurity

Analyse a bank transactions CSV to detect recurring subscriptions, score cancellation priority, and surface actionable savings recommendations. Designed as the first module in a broader personal-finance agent; bank data parsing is deliberately decoupled so future savings / deposit / investment skills can reuse it.

  • 3 stars
  • 0 votes
  • 0 copies
  • 6 views
  • Added September 9, 2026
toolspythongobashexpressawsgcpgitapisecurity

Works with

  • terminal
  • api

Security analysis

A100/100

Scanned September 9, 2026

npx -y skills add Lord1Egypt/awesome-skill-forge --skill subscription-killer --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Subscription Killer?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Subscription Killer
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/lord1egypt-subscription-killer/badge)](https://www.skillsdirectory.com/skills/lord1egypt-subscription-killer)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: subscription-killer
description: >
  Analyse a bank transactions CSV to detect recurring subscriptions, score
  cancellation priority, and surface actionable savings recommendations.
  Designed as the first module in a broader personal-finance agent; bank data
  parsing is deliberately decoupled so future savings / deposit / investment
  skills can reuse it.
version: 1.1.0
metadata:
  openclaw:
    requires:
      env: []
      bins:
        - python3
    envVars:
      - name: SUBSCRIPTION_KILLER_CURRENCY
        required: false
        description: >
          ISO 4217 currency code for display (default: GBP). E.g. USD, EUR, GBP.
    primaryEnv: SUBSCRIPTION_KILLER_CURRENCY
---

# Subscription Killer

Analyse a bank transactions CSV file and surface every recurring subscription,
ranked by cancellation / downgrade priority with estimated monthly savings.

## Skill overview

This skill takes a single CSV file of bank transactions and:

1. Sniffs the CSV structure to detect column names automatically.
2. Normalises merchant names using a curated alias dictionary plus fuzzy
   matching (Levenshtein distance ≤ 2 tokens).
3. Detects recurring charges by cadence (monthly / quarterly / annual) and
   amount consistency (±2 % tolerance).
4. Scores each subscription by confidence (0–100).
5. Ranks subscriptions by a composite priority score: spend × inactivity risk ×
   price-creep factor × duplication penalty.
6. Outputs a structured report with clear cancellation and downgrade actions.

---

## Input format

The skill accepts any CSV export from a personal bank account. Common formats
are auto-detected:

| Bank / Provider | Typical columns |
|-----------------|-----------------|
| Monzo | Date, Name, Amount, Category |
| Starling | Date, Counter Party, Amount, Balance |
| Revolut | Started Date, Description, Amount, Currency |
| Standard OFX export | Date, Description, Debit Amount |
| Generic | date, merchant / description, amount (minimum required) |

Column detection priority:
- **Date**: looks for columns named `date`, `transaction date`, `started date`,
  `posted date` (case-insensitive). Falls back to first column that parses as
  ISO 8601 or DD/MM/YYYY.
- **Amount**: looks for `amount`, `debit amount`, `debit`. Ignores credit /
  top-up rows (positive amounts in debit-positive conventions).
- **Merchant**: looks for `name`, `description`, `merchant`, `counter party`,
  `payee`. Falls back to longest non-numeric column.

---

## Core logic

### Step 1 — Parse CSV

```python
import csv, re, difflib
from datetime import datetime, timedelta
from collections import defaultdict

def sniff_columns(header: list[str]) -> dict:
    """Return {'date': col, 'amount': col, 'merchant': col} best guesses."""
    header_lower = [h.lower().strip() for h in header]
    DATE_HINTS    = ['date', 'transaction date', 'started date', 'posted date']
    AMOUNT_HINTS  = ['amount', 'debit amount', 'debit']
    MERCHANT_HINTS = ['name', 'description', 'merchant', 'counter party',
                      'payee', 'narrative']
    def first_match(hints):
        for hint in hints:
            if hint in header_lower:
                return header[header_lower.index(hint)]
        return None
    return {
        'date':     first_match(DATE_HINTS)     or header[0],
        'amount':   first_match(AMOUNT_HINTS)   or header[1],
        'merchant': first_match(MERCHANT_HINTS) or header[2],
    }

def parse_amount(raw: str) -> float | None:
    """Return a positive debit amount, or None for credits / errors."""
    cleaned = re.sub(r'[£$€,\s]', '', raw.strip())
    if not cleaned:
        return None
    try:
        val = float(cleaned)
        # Debit-positive CSV (most UK banks): only keep debits (negatives after
        # sign flip are credits — skip them)
        # Some CSVs use negative for debits; normalise to positive debit.
        return abs(val) if val != 0 else None
    except ValueError:
        return None
```

### Step 2 — Normalise merchant names

Use a two-pass approach:

**Pass 1 — Known alias dictionary** (curated, highest-confidence)

```python
MERCHANT_ALIASES = {
    # Streaming
    r'netflix':                 'Netflix',
    r'spotify':                 'Spotify',
    r'apple\.com/bill':         'Apple Subscriptions',
    r'itunes':                  'Apple Subscriptions',
    r'amazon prime':            'Amazon Prime',
    r'amzn\s?prime':            'Amazon Prime',
    r'disney\+|disneyplus':     'Disney+',
    r'youtube premium':         'YouTube Premium',
    r'hbo|max\.com':            'Max (HBO)',
    r'paramount':               'Paramount+',
    r'dazn':                    'DAZN',
    # Music
    r'tidal':                   'Tidal',
    r'deezer':                  'Deezer',
    r'soundcloud':              'SoundCloud',
    # Productivity / SaaS
    r'github':                  'GitHub',
    r'notion':                  'Notion',
    r'slack':                   'Slack',
    r'dropbox':                 'Dropbox',
    r'google\s?(one|storage|workspace)': 'Google One/Workspace',
    r'microsoft 365|office 365|msft': 'Microsoft 365',
    r'adobe':                   'Adobe Creative Cloud',
    r'figma':                   'Figma',
    r'zoom':                    'Zoom',
    r'1password|lastpass|bitwarden': 'Password Manager',
    r'nordvpn|expressvpn|surfshark':  'VPN Service',
    # News / Reading
    r'medium':                  'Medium',
    r'substack':                'Substack',
    r'kindle unlimited':        'Kindle Unlimited',
    r'audible':                 'Audible',
    r'the times|thetimes':      'The Times',
    r'financial times|ft\.com': 'Financial Times',
    r'economist':               'The Economist',
    # Fitness
    r'peloton':                 'Peloton',
    r'strava':                  'Strava',
    r'myfitnesspal':            'MyFitnessPal',
    r'calm|headspace':          'Meditation App',
    # Utilities / services
    r'amazon web services|aws': 'AWS',
    r'google cloud|gcp':        'Google Cloud',
    r'digitalocean':            'DigitalOcean',
    r'cloudflare':              'Cloudflare',
    r'railway\.app':            'Railway',
    r'openai':                  'OpenAI',
    r'anthropic':               'Anthropic',
}

def normalize_merchant(raw: str) -> str:
    """Return a clean, canonical merchant name."""
    s = raw.lower().strip()
    for pattern, canonical in MERCHANT_ALIASES.items():
        if re.search(pattern, s, re.IGNORECASE):
            return canonical
    # Pass 2 — strip noise tokens (card numbers, references, country codes)
    cleaned = re.sub(
        r'\b(www|com|co\.uk|ltd|limited|uk|us|gb|inc|gmbh)\b'
        r'|\d{4,}'      # card / ref numbers
        r'|\*+\S*'      # asterisk-prefixed tokens
        r'|[^a-z0-9 ]', # special chars
        '', s
    ).strip().title()
    return cleaned or raw.title()
```

**Pass 2 — Fuzzy deduplication** across the transaction list

After normalisation, cluster remaining merchant names by token-set similarity
(`difflib.SequenceMatcher` ratio > 0.82). The most-frequent variant in each
cluster becomes the canonical name.

### Step 3 — Detect recurring charges

```python
def detect_cadence(dates: list[datetime]) -> str | None:
    """
    Return 'monthly', 'quarterly', 'annual', or None.
    Requires ≥ 2 transactions for monthly/quarterly, ≥ 1 for annual hinting.
    """
    if len(dates) < 2:
        # Single occurrence — flag as potential annual if amount > 30
        return 'annual_candidate'
    gaps = sorted([(dates[i+1] - dates[i]).days for i in range(len(dates)-1)])
    median_gap = gaps[len(gaps)//2]
    if 25 <= median_gap <= 35:   return 'monthly'
    if 85 <= median_gap <= 100:  return 'quarterly'
    if 340 <= median_gap <= 380: return 'annual'
    return None

def amounts_consistent(amounts: list[float], tolerance: float = 0.02) -> bool:
    """True if all amounts are within ±2 % of the median."""
    if not amounts:
        return False
    median = sorted(amounts)[len(amounts)//2]
    return all(abs(a - median) / median <= tolerance for a in amounts)
```

### Step 4 — Confidence scoring (0–100)

| Factor | Max points | Logic |
|--------|-----------|-------|
| Cadence regularity | 40 | All gaps within ±3 days of median |
| Amount consistency | 30 | All amounts within ±2 % |
| Known merchant match | 20 | Exact alias dictionary hit |
| Transaction count | 10 | log₂(count) × 3, capped at 10 |

Confidence ≥ 70 → **Confirmed subscription**
Confidence 40–69 → **Probable subscription**
Confidence < 40 → **Possible / flag for review**

### Step 5 — Priority ranking

Each confirmed/probable subscription gets a composite priority score:

```
priority = monthly_cost
         × price_creep_multiplier   # max(amounts) / min(amounts); 1.0 = stable
         × duplication_penalty       # 1.5 if same category has 2+ subscriptions
         × inactivity_risk           # 1.3 if last charge > 45 days ago
```

Higher priority score = stronger cancellation candidate.

**Special flags:**
- **Trial trap**: single charge in the last 7 days from a previously-unseen
  merchant, followed by a recurring pattern. Flag as "check for auto-renew".
- **Price creep**: amount has increased > 5 % over the observation window.
  Flag with the exact amount delta.
- **Annual renewal due**: annual-cadence subscription whose last charge was
  300–365 days ago. Flag with estimated renewal date.
- **Unknown merchant**: low-confidence recurring charge with no alias match.
  Flag for manual review.

---

## Output schema

The skill returns a structured report. Print to stdout as JSON for downstream
agent consumption, or render the human-readable summary below.

```json
{
  "summary": {
    "observation_window_days": 90,
    "total_subscriptions": 12,
    "confirmed": 9,
    "probable": 2,
    "flagged_for_review": 1,
    "monthly_spend_gbp": 187.43,
    "annual_spend_gbp": 2249.16,
    "potential_monthly_saving_gbp": 54.20
  },
  "subscriptions": [
    {
      "merchant": "Adobe Creative Cloud",
      "cadence": "monthly",
      "median_amount": 54.99,
      "last_charge": "2025-04-01",
      "confidence": 95,
      "priority_score": 89.2,
      "flags": ["price_creep"],
      "price_creep_delta": 5.00,
      "cancel_url": "https://account.adobe.com/plans",
      "actions": ["cancel", "downgrade"]
    }
  ],
  "top_cancellation_targets": ["Adobe Creative Cloud", "..."],
  "unknown_merchants": ["TRSF 48291 REF77"],
  "annual_renewals_due": []
}
```

### Human-readable summary (terminal / Telegram)

```
╔══════════════════════════════════════════╗
║        SUBSCRIPTION KILLER  v1.0         ║
╠══════════════════════════════════════════╣
║  12 subscriptions  •  £187/mo  •  £2,249/yr
╚══════════════════════════════════════════╝

TOP CANCELLATION TARGETS
1. Adobe Creative Cloud   £54.99/mo  ↑ price crept +£5.00
2. Calm                   £39.99/yr  last used 3 months ago
3. LinkedIn Premium       £29.99/mo  duplicate: 2 job-search tools

POTENTIAL SAVING:  £54/mo  •  £648/yr

UNKNOWN MERCHANTS (review manually)
• TRSF 48291 REF77  — £12.99/mo  (confidence 38%)
```

---

## Cancel guidance (top 50 services)

The skill bundles a `cancel_urls.json` file mapping canonical merchant names
to their self-serve cancellation pages. This removes friction for the user.

```json
{
  "Netflix":                "https://www.netflix.com/cancelplan",
  "Spotify":                "https://www.spotify.com/account/subscription/cancel",
  "Adobe Creative Cloud":   "https://account.adobe.com/plans",
  "Amazon Prime":           "https://www.amazon.co.uk/mc/pipeline/cancelEndBenefit",
  "Disney+":                "https://www.disneyplus.com/account/subscription",
  "Microsoft 365":          "https://account.microsoft.com/services",
  "GitHub":                 "https://github.com/settings/billing/subscriptions",
  "Dropbox":                "https://www.dropbox.com/account/plan",
  "Zoom":                   "https://zoom.us/billing",
  "LinkedIn Premium":       "https://www.linkedin.com/premium/products",
  "Google One/Workspace":   "https://myaccount.google.com/payments-and-subscriptions",
  "OpenAI":                 "https://platform.openai.com/account/billing"
}
```

---

## Invocation

```bash
# Analyse a CSV file
python3 subscription_killer.py --file transactions.csv

# Override currency display
SUBSCRIPTION_KILLER_CURRENCY=EUR python3 subscription_killer.py --file transactions.csv

# Output raw JSON for piping to another skill
python3 subscription_killer.py --file transactions.csv --json
```

The script reads `SUBSCRIPTION_KILLER_CURRENCY` from the environment for display
only; all internal calculations use the amounts as-found in the CSV.

---

## Roadmap (future skills in this suite)

This skill is intentionally scoped to subscription detection. Planned companion
skills that share the CSV parsing layer:

| Skill | Description |
|-------|-------------|
| `savings-rate-analyser` | Track income vs spend, compute savings rate, compare to benchmarks |
| `deposit-rate-scout`    | Pull live UK/EU savings account rates via open banking APIs |
| `emergency-fund-checker`| Assess months of runway based on average monthly spend |
| `investment-nudger`     | Identify investable surplus after subscriptions + essentials |

The `bank-csv-parser` module within this skill will be extracted into a shared
utility skill once the suite matures.

---

## Security & privacy

- All processing is local. No transaction data leaves the machine.
- The skill does not write any files outside the working directory.
- No API keys required for the core subscription detection flow.
- The `cancel_urls.json` is a static lookup table; no network calls are made
  unless the user explicitly requests live rate data (future skill).

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in tools →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.