Claude Code Plugins

Community-maintained marketplace

Feedback

claims

@yjsoon/ynab-claimer
0
0

Process expense claims by matching YNAB transactions with uploaded receipts. Use when the user mentions claims, expenses, reimbursements, receipts, or YNAB TODOs.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name claims
description Process expense claims by matching YNAB transactions with uploaded receipts. Use when the user mentions claims, expenses, reimbursements, receipts, or YNAB TODOs.

Claim Processing Workflow

Process expense claims by matching YNAB transactions with uploaded receipts.

Instructions

You are helping the user process expense claims. Follow this workflow.

Parallelization Strategy: Use sub-agents (Task tool) throughout to maximize speed:

  • Downloading/identifying receipts: Spawn parallel agents to process all receipts concurrently
  • Post-claim cleanup: Run cleanup tasks in background agents while showing next claim
  • This significantly speeds up claim processing, especially with many receipts

1. Load Configuration

Use the Read tool to read .env in the project root. Extract these values:

  • YNAB_API_KEY - API key for YNAB
  • YNAB_BUDGET_ID - Budget ID to query
  • R2_WORKER_URL - URL of the receipt upload worker
  • R2_PASSWORD - Password for receipt worker auth

If .env is missing or incomplete, ask the user to set it up using .env.example as a template.

Important: When using these values in curl commands, substitute them directly into the command (don't rely on shell variable expansion from source .env as it doesn't handle comments well).

2. Fetch YNAB Transactions

Use curl to fetch transactions marked with "TODO" in the memo:

curl -s -H "Authorization: Bearer <YNAB_API_KEY>" \
  "https://api.ynab.com/v1/budgets/<YNAB_BUDGET_ID>/transactions" \
  | jq '[.data.transactions[] | select(.memo) | select(.memo | ascii_downcase | contains("todo"))]'

Note: Filter for amount < 0 (outflows) to avoid duplicate transfer entries.

Parse the response to extract:

  • id - Transaction ID (for updating later)
  • date - Transaction date
  • amount - Amount in milliunits (divide by 1000 for actual amount)
  • payee_name - Merchant/payee
  • memo - Contains "TODO: description"
  • category_name - Category

3. Fetch Pending Receipts

List receipts from R2:

curl -s -H "X-Auth-Token: <R2_PASSWORD>" "<R2_WORKER_URL>/list" | jq '.receipts'

4. Identify All Receipts

Before matching, download and read ALL receipts to identify their contents. Don't rely solely on filenames - many receipts have generic names like "Receipt-1234.pdf" or "unnamed.png".

Use sub-agents for parallel processing: Spawn multiple Task tool agents (subagent_type="general-purpose") to download and identify receipts concurrently. Each agent handles one receipt:

Task 1: "Download receipt [key1] from R2, convert if HEIC, read and extract: merchant, date, amount, invoice#. Return structured summary."
Task 2: "Download receipt [key2] from R2, convert if HEIC, read and extract: merchant, date, amount, invoice#. Return structured summary."
...etc

Launch all agents in a single message (parallel tool calls) for maximum speed.

For each receipt, the agent should:

  1. Download to /tmp/claims/:

    mkdir -p /tmp/claims
curl -s -H "X-Auth-Token: <R2_PASSWORD>" "<R2_WORKER_URL>/receipt/[key]" -o /tmp/claims/[filename]

  2. For HEIC/image files: Convert if needed:

    sips -Z 1500 /tmp/claims/file.heic --out /tmp/claims/file.jpg

  3. Read the receipt using the Read tool to extract:

    • Merchant name
    • Date
    • Amount
    • Any invoice/order number

  4. Return structured data for the manifest.

Collect all agent results and build the receipt manifest for matching.

5. Match Analysis

Compare TODOs against identified receipts and show a summary:

Matching criteria:

  • Date proximity (within 3 days)
  • Amount match (exact or within 10%)

Present the overview:

=== CLAIMS OVERVIEW ===

✅ READY TO PROCESS (X items) - have matching receipts:
   - [date] [description] $[amount]
   ...

❌ MISSING RECEIPTS (Y items) - need to find:
   - 3x Cold Storage (~$40-60 each, Oct-Nov)
   - 2x Grab rides (~$30-40, Nov)
   - 1x GitHub ($133, Nov 4)
   ...

📎 UNMATCHED RECEIPTS (Z items) - uploaded but no matching TODO:
   - [filename] [date]
   ...

Ask the user:

  1. Process ready items now?
  2. Or pause to find missing receipts first?

6. Group and Order Claims

Sorting strategy (maintains claiming momentum by keeping similar items together):

  1. Group by merchant first - All Cold Storage claims together, all Grab claims together, etc.

  2. Within each merchant, sub-group by description similarity - Infer from the TODO description what type of expense it is:

    • e.g., "groceries", "household items", "snacks" might cluster together
    • e.g., "team lunch", "client dinner" might cluster together
    • This lets user stay in the same mental context when filling claim forms

  3. Within sub-groups, sort by date - Chronological order within similar items

Example ordering:

Cold Storage (5 items):
  - Groceries: Oct 1, Oct 8, Oct 15
  - Household: Oct 5, Oct 12
Grab (3 items):
  - Work commute: Oct 2, Oct 9
  - Client meeting: Oct 7
GitHub (1 item):
  - Subscription: Nov 4

Present this grouping to user and confirm the processing order before starting.

7. Process Each Claim

For each TODO transaction:

  1. Show transaction details:

    • Date: [date]
    • Payee: [payee_name]
    • Amount: [amount / 1000] (with currency)
    • Description: [memo without "TODO:" prefix]
    • Category: [category_name]

  2. Find matching receipt(s) by:

    • Date proximity (within 3 days)
    • Amount match (exact or close)
    • Show top matches and let user confirm

  3. Download and open the receipt:

    mkdir -p /tmp/claims
curl -s -H "X-Auth-Token: <R2_PASSWORD>" "<R2_WORKER_URL>/receipt/[key]" -o /tmp/claims/[filename]

    For HEIC files: Convert to JPEG for easier viewing, then delete the HEIC:

    sips -Z 1500 /tmp/claims/file.heic --out /tmp/claims/file.jpg
trash /tmp/claims/file.heic

    Rename for clarity: Rename the local file to a descriptive format: [claim#] - [merchant] [date] [amount].[ext]

    Example: 1 - stratechery-dithering 25-oct 150.pdf

    Then open the renamed file. Also use the Read tool to view and extract details.

    Cleanup: After each claim, delete the processed local file immediately to keep /tmp/claims clean. Only the current claim's receipt should be in the folder.

  4. Extract from receipt:

    • Merchant name
    • Date
    • Total amount
    • Tax breakdown (GST/VAT if visible)
    • Any other relevant details

  5. Present formatted claim summary:

    === CLAIM SUMMARY ===
Date: [date]
Merchant: [merchant]
Description: [description from memo]
Amount: S$[YNAB amount]
       (or for foreign currency: US$[receipt amount] (S$[YNAB amount] at exchange rate of [rate]))
Tax: [tax amount if found, or "included" / "not shown"]
Receipt: file:///tmp/claims/[filename]
Folder:  file:///tmp/claims/

    Copy merchant to clipboard: Run echo -n "[merchant]" | pbcopy so user can paste it easily. Use the registered company name, not the trade name:

    • For Singapore vendors: Look for "Pte Ltd" or "LLP" (e.g., "Kap Kia Pte Ltd" not "Yeast Side")
    • For US vendors: Look for "LLC", "Inc.", "Corp" (e.g., "OpenAI, LLC" not "OpenAI")
    • Use the EXACT name as registered, including punctuation

    Currency discrepancies: If YNAB amount (SGD) differs from receipt amount, assume USD and calculate the exchange rate: YNAB_SGD / Receipt_USD. Display as: US$X (S$Y at exchange rate of Z)

  6. Wait for user confirmation. When user says "done":

    For speed: Show the next claim's details FIRST, then run cleanup via background sub-agent:

    • Present the next claim summary immediately
    • Open the next receipt
    • Spawn a background sub-agent (Task tool with run_in_background: true) to handle cleanup for the completed claim

    Background cleanup agent prompt:

    "Complete claim cleanup for transaction [TRANSACTION_ID]:
1. Update YNAB memo from 'TODO: X' to 'CLAIMED: X' via PUT to transactions API
2. Delete receipt [key] from R2 via DELETE endpoint
3. Delete local file /tmp/claims/[filename] using trash command
Credentials: YNAB_API_KEY=[key], R2_WORKER_URL=[url], R2_PASSWORD=[pwd]"

    This runs cleanup concurrently while user reviews the next claim. No need to wait for cleanup to complete before proceeding.

    Cleanup tasks (for reference):

    • Update YNAB memo from "TODO: X" to "CLAIMED: X":
      curl -s -X PUT -H "Authorization: Bearer <YNAB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"transaction": {"memo": "CLAIMED: [description]"}}' \
  "https://api.ynab.com/v1/budgets/<YNAB_BUDGET_ID>/transactions/<TRANSACTION_ID>"
    • Delete receipt from R2:
      curl -s -X DELETE -H "X-Auth-Token: <R2_PASSWORD>" "<R2_WORKER_URL>/receipt/[key]"
    • Delete local receipt file (keeps /tmp/claims clean for easier uploads):
      trash /tmp/claims/[filename]

  7. Move to the next claim.

8. Handle Edge Cases

  • No matching receipt: Flag for manual review, ask user if they want to skip or mark without receipt
  • Multiple matches: Show all options and let user pick
  • Unmatched receipts: At the end, list any receipts that weren't matched to transactions

9. Summary

When all claims are processed:

  1. Wait for background cleanup agents: Use TaskOutput to verify all background cleanup tasks completed successfully. Report any failures.

  2. Show summary:

    • Number of claims processed
    • Any skipped items
    • Any orphaned receipts remaining
    • Any cleanup failures that need manual attention

Quick Reference

YNAB API: https://api.ynab.com/v1/ Transaction amounts: In milliunits (divide by 1000) Negative amounts: Outflows (expenses) Positive amounts: Inflows

Receipt filename format: YYYY-MM-DD_HHMMSS_originalname.ext