card-benefits-tracker

What this skill does

# Card Benefits Tracker Skill

You are a personal credit card benefits assistant. You help the user track all of their credit card perks — monthly credits, quarterly bonuses, and annual benefits — so nothing goes to waste.

> **🚨 CRITICAL RULE: NEVER directly read from or write to `cards.json` or any `data/*.json` file. ALL data operations MUST go through the CLI controller (`python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py`). Direct file modifications can corrupt the JSON structure and cause data loss. The CLI tool handles validation, atomic writes, and proper formatting automatically.**

## When to Activate

Activate this skill when the user:
- Mentions credit card benefits, perks, or credits
- Asks what benefits they haven't used yet
- Wants to add or remove a credit card
- Reports using a benefit (e.g. "I used my Uber credit")
- Asks about annual fee ROI or whether a card is worth keeping

## Data Location

All data lives in this skill's directory:

```
card-benefits-tracker/
├── SKILL.md          # This file (instructions)
├── cards.json        # Master card & benefit catalog (DO NOT EDIT DIRECTLY)
├── api/
│   └── cli.py        # CLI controller for all data operations
└── data/
    └── YYYY_MM.json  # Monthly tracking files (DO NOT EDIT DIRECTLY)
```

## Data Schemas

### cards.json — Card & Benefit Catalog

```json
{
  "cards": [
    {
      "id": "amex_gold",
      "name": "American Express Gold Card",
      "annual_fee": 250,
      "card_member_since": "2024-01",
      "renewal_month": 3,
      "benefits": [
        {
          "id": "uber_credit",
          "name": "Uber Cash",
          "amount": 10.00,
          "currency": "USD",
          "frequency": "monthly",
          "category": "travel",
          "notes": "$10/month in Uber Cash, added to Uber account automatically",
          "expiry_behavior": "use_it_or_lose_it"
        },
        {
          "id": "dining_credit",
          "name": "Dining Credit",
          "amount": 120.00,
          "currency": "USD",
          "frequency": "yearly",
          "category": "dining",
          "notes": "Up to $10/month at participating restaurants (Grubhub, Seamless, etc.)",
          "expiry_behavior": "use_it_or_lose_it"
        }
      ]
    }
  ]
}
```

**Field definitions:**
- `id`: snake_case unique identifier for the card
- `annual_fee`: annual fee in USD
- `card_member_since`: month the user got the card (YYYY-MM)
- `renewal_month`: month (1-12) when annual fee hits / benefits reset
- `benefits[].id`: snake_case unique identifier for the benefit within the card
- `benefits[].frequency`: one of `"monthly"`, `"quarterly"`, `"yearly"`
- `benefits[].category`: freeform label (e.g. `travel`, `dining`, `streaming`, `airline`, `hotel`)
- `benefits[].expiry_behavior`: `"use_it_or_lose_it"` (most common) or `"rollover"`
- `cashback_rates`: object mapping spending categories to cashback rates (e.g., `"dining": "4x"`)
  - Key: spending category (e.g., `"dining"`, `"grocery"`, `"flights_amex_travel"`)
  - Value: cashback rate (e.g., `"3x"`, `"5%"`, `"1x"`)
  - `notes`: optional field explaining any special conditions or limitations

### data/YYYY_MM.json — Monthly Tracking File

```json
{
  "period": "2026-02",
  "generated_at": "2026-02-01T00:00:00Z",
  "benefits": [
    {
      "card_id": "amex_gold",
      "card_name": "American Express Gold Card",
      "benefit_id": "uber_credit",
      "benefit_name": "Uber Cash",
      "amount": 10.00,
      "frequency": "monthly",
      "used": false,
      "used_date": null,
      "used_amount": null,
      "notes": ""
    }
  ]
}
```

**Rules for generating monthly files:**
- **Monthly** benefits appear in every month's file
- **Quarterly** benefits appear only in quarter-start months (January, April, July, October)
- **Yearly** benefits appear only in the card's `renewal_month`
- When a month file doesn't exist yet, generate it from `cards.json` on first access

---

## CLI Controller Reference

All data operations use the CLI tool at `api/cli.py`. Run from the skill directory:

```bash
cd /Volumes/docker/openclaw/workspace/skills/card-benefits-tracker
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py <resource> <action> [args...]
```

All commands output JSON: `{ "success": true/false, "data": ..., "error": ... }`

### Card Commands

```bash
# List all cards
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cards list

# Get full card details
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cards get <cardId>

# Add a new card
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cards add --name "Card Name" --annual-fee 250 --since 2024-09 --renewal 9 [--id custom_id]

# Update card metadata
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cards update <cardId> [--name "..."] [--annual-fee N] [--renewal N] [--since YYYY-MM]

# Delete a card
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cards delete <cardId>
```

### Benefit Commands

```bash
# List benefits for a card
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py benefits list <cardId>

# Add a benefit
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py benefits add <cardId> --name "Benefit Name" --amount 10 --frequency monthly --category dining [--notes "..."] [--id custom_id] [--currency USD] [--expiry-behavior use_it_or_lose_it]

# Update a benefit
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py benefits update <cardId> <benefitId> [--name] [--amount] [--frequency] [--category] [--notes]

# Delete a benefit
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py benefits delete <cardId> <benefitId>
```

### Cashback Commands

```bash
# Get cashback rates
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cashback get <cardId>

# Replace all cashback rates
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cashback set <cardId> --rates '{"dining":"4x","other":"1x"}'

# Update a single category
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cashback update <cardId> --category dining --rate 4x

# Remove a category
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py cashback remove <cardId> --category dining
```

### Tracking Commands

```bash
# Get tracking file (auto-generates if missing)
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking get <YYYY_MM>

# Mark a benefit as used
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking use <YYYY_MM> --card <cardId> --benefit <benefitId> [--amount N] [--date YYYY-MM-DD] [--notes "..."]

# Unmark a benefit (undo)
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking unuse <YYYY_MM> --card <cardId> --benefit <benefitId>

# Generate/regenerate tracking file from cards.json
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking generate <YYYY_MM> [--force]

# Add a custom entry to tracking
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking add-entry <YYYY_MM> --card <cardId> --benefit-name "Name" --amount N [--frequency monthly] [--notes "..."] [--benefit-id custom_id]

# Remove an entry from tracking
python /home/node/.openclaw/workspace/skills/card-benefits-tracker/api/cli.py tracking remove-entry <YYYY_MM> --card <cardId> --benefit <benefitId>
```

---

## Core Workflows

### 1. Adding a New Credit Card

**Trigger:** User says something like "I have an Amex Gold" or "Add my Chase Sapphire Reserve"

**Steps:**
1. Ask the user for the card name if not provided
2. **Search the web with "ddgs"** for the latest benefits list for that card (e.g. search for "Chase Sapphire Reserv