receipt-import

name: receipt-import description: Use when the user asks to "import receipts", "process receipts", "extract PDF receipts", "scan receipts", or any request involving extracting data from PDF receipts and adding to tax ledgers. version: 0.1.0

Receipt PDF Import Skill

Extract line items from PDF receipts using Claude Code's built-in vision and import them into tax reporting ledgers.

Capabilities

1. PDF Vision Extraction - Read PDFs directly using built-in vision
2. Line Item Parsing - Extract date, description, amount, vendor
3. Category Suggestion - Map vendors to IRS schedule categories
4. Date Validation - Skip receipts outside active tax years (2025-2027)
5. Staging Output - Generate org-mode tables for manual review

Receipt Locations

PDFs can be placed in:

• imports/receipts/ - Requires --business farm|consulting flag
• farm/{year}/receipts/ - Auto-detects farm business
• consulting/{year}/receipts/ - Auto-detects consulting business

Workflow

Step 1: Find Pending Receipts

# Check all locations
ls imports/receipts/*.pdf 2>/dev/null
ls farm/*/receipts/*.pdf 2>/dev/null
ls consulting/*/receipts/*.pdf 2>/dev/null

Step 2: Read Each PDF

For each PDF, use Claude Code's built-in Read tool to view the receipt as an image. Extract structured data into this JSON format:

{
  "vendor": "Store name",
  "date": "YYYY-MM-DD",
  "line_items": [
    {"description": "Item description", "amount": 12.99, "quantity": 1}
  ],
  "subtotal": 0.00,
  "tax": 0.00,
  "total": 0.00
}

Step 3: Validate Dates

• Active years: 2025, 2026, 2027
• Receipts with dates outside active years -> log to _skipped.log and skip
• Receipts with valid dates -> include in _import.org

Step 4: Suggest Categories

Map vendor names to IRS schedule categories:

Step 5: Generate Staging File

Create _import.org in the receipts directory with org-mode tables:

#+TITLE: Receipt Import - YYYY-MM-DD
#+STARTUP: showall

* Imported Receipts

** Vendor Name - YYYY-MM-DD
:PROPERTIES:
:SOURCE: original-filename.pdf
:VENDOR: Vendor Name
:DATE: YYYY-MM-DD
:TOTAL: 123.45
:SUGGESTED_CATEGORY: Category Name (Line XX)
:BUSINESS: farm|consulting
:END:

| Date       | Description      | Amount | Notes |
|------------+------------------+--------+-------|
| YYYY-MM-DD | Item description | 12.99  |       |
|------------+------------------+--------+-------|
| *TOTAL*    |                  | 12.99  |       |
#+TBLFM: @>$3=vsum(@2..@-1);%.2f

# ACTION: Copy to {business}/{year}/ledger.org under "{Category} (Line XX)"

Step 6: Report Results

After processing, report:

1. Total PDFs found
2. Successfully extracted (with category breakdown)
3. Skipped (with reasons logged to _skipped.log)
4. Location of staging file

Example output:

Processed 3 receipts from imports/receipts/:
  - 1 extracted (farm)
  - 2 skipped (dates outside 2025-2027)

Staging file: imports/receipts/_import.org
Skipped log: imports/receipts/_skipped.log

Review staging file, then copy entries to appropriate ledger.

Commands

Manual Invocation

# From imports/receipts/ (must specify business)
uv run scripts/receipt_import.py imports/receipts/ --business farm

# From business-specific folder (auto-detects)
uv run scripts/receipt_import.py farm/2026/receipts/

# Dry run (show what would be extracted)
uv run scripts/receipt_import.py imports/receipts/ --business farm --dry-run

Processing Steps for Claude Code

When the user asks to "import receipts" or "process receipts":

1. List PDFs: Find all .pdf files in the specified location
2. Read each PDF: Use the Read tool - it will render PDFs as images
3. Extract JSON: Parse the receipt image and extract structured data
4. Validate dates: Check if date is in 2025-2027, skip if not
5. Suggest category: Match vendor name to category mapping above
6. Format output: Generate org-mode table matching ledger format
7. Write staging file: Save to _import.org
8. Log skipped: Write skipped receipts to _skipped.log
9. Report summary: Show counts and file locations

After Import

1. Review _import.org for accuracy
2. Verify suggested categories are correct
3. Copy verified entries to appropriate ledger.org file
4. Optionally move processed PDFs to _processed/ folder