invoice-organizer

# Invoice Organizer

This skill transforms chaotic folders of invoices, receipts, and financial documents into a clean, tax-ready filing system without manual effort.

## When to Use This Skill

- Preparing for tax season and need organized records
- Managing business expenses across multiple vendors
- Organizing receipts from a messy folder or email downloads
- Setting up automated invoice filing for ongoing bookkeeping
- Archiving financial records by year or category
- Reconciling expenses for reimbursement
- Preparing documentation for accountants

## What This Skill Does

1. **Reads Invoice Content**: Extracts information from PDFs, images, and documents:
   - Vendor/company name
   - Invoice number
   - Date
   - Amount
   - Product or service description
   - Payment method

2. **Renames Files Consistently**: Creates standardized filenames:
   - Format: `YYYY-MM-DD Vendor - Invoice - ProductOrService.pdf`
   - Examples: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`

3. **Organizes by Category**: Sorts into logical folders:
   - By vendor
   - By expense category (software, office, travel, etc.)
   - By time period (year, quarter, month)
   - By tax category (deductible, personal, etc.)

4. **Handles Multiple Formats**: Works with:
   - PDF invoices
   - Scanned receipts (JPG, PNG)
   - Email attachments
   - Screenshots
   - Bank statements

5. **Maintains Originals**: Preserves original files while organizing copies

## How to Use

### Basic Usage

Navigate to your messy invoice folder:
```
cd ~/Desktop/receipts-to-sort
```

Then ask Claude Code:
```
Organize these invoices for taxes
```

Or more specifically:
```
Read all invoices in this folder, rename them to 
"YYYY-MM-DD Vendor - Invoice - Product.pdf" format, 
and organize them by vendor
```

### Advanced Organization

```
Organize these invoices:
1. Extract date, vendor, and description from each file
2. Rename to standard format
3. Sort into folders by expense category (Software, Office, Travel, etc.)
4. Create a CSV spreadsheet with all invoice details for my accountant
```

## Instructions

When a user requests invoice organization:

1. **Scan the Folder**
   
   Identify all invoice files:
   ```bash
   # Find all invoice-related files
   find . -type f \( -name "*.pdf" -o -name "*.jpg" -o -name "*.png" \) -print
   ```
   
   Report findings:
   - Total number of files
   - File types
   - Date range (if discernible from names)
   - Current organization (or lack thereof)

2. **Extract Information from Each File**
   
   For each invoice, extract:
   
   **From PDF invoices**:
   - Use text extraction to read invoice content
   - Look for common patterns:
     - "Invoice Date:", "Date:", "Issued:"
     - "Invoice #:", "Invoice Number:"
     - Company name (usually at top)
     - "Amount Due:", "Total:", "Amount:"
     - "Description:", "Service:", "Product:"
   
   **From image receipts**:
   - Read visible text from images
   - Identify vendor name (often at top)
   - Look for date (common formats)
   - Find total amount
   
   **Fallback for unclear files**:
   - Use filename clues
   - Check file creation/modification date
   - Flag for manual review if critical info missing

3. **Determine Organization Strategy**
   
   Ask user preference if not specified:
   
   ```markdown
   I found [X] invoices from [date range].
   
   How would you like them organized?
   
   1. **By Vendor** (Adobe/, Amazon/, Stripe/, etc.)
   2. **By Category** (Software/, Office Supplies/, Travel/, etc.)
   3. **By Date** (2024/Q1/, 2024/Q2/, etc.)
   4. **By Tax Category** (Deductible/, Personal/, etc.)
   5. **Custom** (describe your structure)
   
   Or I can use a default structure: Year/Category/Vendor
   ```

4. **Create Standardized Filename**
   
   For each invoice, create a filename following this pattern:
   
   ```
   YYYY-MM-DD Vendor - Invoice - Description.ext
   ```
   
   Examples:
   - `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
   - `2024-01-10 Amazon - Receipt - Office Supplies.pdf`
   - `2023-12-01 Stripe - Invoice - Monthly Payment Processing.pdf`
   
   **Filename Best Practices**:
   - Remove special characters except hyphens
   - Capitalize vendor names properly
   - Keep descriptions concise but meaningful
   - Use consistent date format (YYYY-MM-DD) for sorting
   - Preserve original file extension

5. **Execute Organization**
   
   Before moving files, show the plan:
   
   ```markdown
   # Organization Plan
   
   ## Proposed Structure
   ```
   Invoices/
   ├── 2023/
   │   ├── Software/
   │   │   ├── Adobe/
   │   │   └── Microsoft/
   │   ├── Services/
   │   └── Office/
   └── 2024/
       ├── Software/
       ├── Services/
       └── Office/
   ```
   
   ## Sample Changes
   
   Before: `invoice_adobe_march.pdf`
   After: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
   Location: `Invoices/2024/Software/Adobe/`
   
   Before: `IMG_2847.jpg`
   After: `2024-02-10 Staples - Receipt - Office Supplies.jpg`
   Location: `Invoices/2024/Office/Staples/`
   
   Process [X] files? (yes/no)
   ```
   
   After approval:
   ```bash
   # Create folder structure
   mkdir -p "Invoices/2024/Software/Adobe"
   
   # Copy (don't move) to preserve originals
   cp "original.pdf" "Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf"
   
   # Or move if user prefers
   mv "original.pdf" "new/path/standardized-name.pdf"
   ```

6. **Generate Summary Report**
   
   Create a CSV file with all invoice details:
   
   ```csv
   Date,Vendor,Invoice Number,Description,Amount,Category,File Path
   2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf
   2024-03-10,Amazon,123-4567890-1234567,Office Supplies,127.45,Office,Invoices/2024/Office/Amazon/2024-03-10 Amazon - Receipt - Office Supplies.pdf
   ...
   ```
   
   This CSV is useful for:
   - Importing into accounting software
   - Sharing with accountants
   - Expense tracking and reporting
   - Tax preparation

7. **Provide Completion Summary**
   
   ```markdown
   # Organization Complete! 📊
   
   ## Summary
   - **Processed**: [X] invoices
   - **Date range**: [earliest] to [latest]
   - **Total amount**: $[sum] (if amounts extracted)
   - **Vendors**: [Y] unique vendors
   
   ## New Structure
   ```
   Invoices/
   ├── 2024/ (45 files)
   │   ├── Software/ (23 files)
   │   ├── Services/ (12 files)
   │   └── Office/ (10 files)
   └── 2023/ (12 files)
   ```
   
   ## Files Created
   - `/Invoices/` - Organized invoices
   - `/Invoices/invoice-summary.csv` - Spreadsheet for accounting
   - `/Invoices/originals/` - Original files (if copied)
   
   ## Files Needing Review
   [List any files where information couldn't be extracted completely]
   
   ## Next Steps
   1. Review the `invoice-summary.csv` file
   2. Check files in "Needs Review" folder
   3. Import CSV into your accounting software
   4. Set up auto-organization for future invoices
   
   Ready for tax season! 🎉
   ```

## Examples

### Example 1: Tax Preparation (From Martin Merschroth)

**User**: "I have a messy folder of invoices for taxes. Sort them and rename properly."

**Process**:
1. Scans folder: finds 147 PDFs and images
2. Reads each invoice to extract:
   - Date
   - Vendor name
   - Invoice number
   - Product/service description
3. Renames all files: `YYYY-MM-DD Vendor - Invoice - Product.pdf`
4. Organizes into: `2024/Software/`, `2024/Travel/`, etc.
5. Creates `invoice-summary.csv` for accountant
6. Result: Tax-ready organized invoices in minutes

### Example 2: Monthly Expense Reconciliation

**User**: "Organize my business receipts from last month by category."

**Output**:
```markdown
# March 2024 Receipts Organized

## By Category
- Software & Tools: $847.32 (12 invoices)
- Office Supplies: $234.18 (8 receipts)
- Travel & Meals: $1,456.90 (15 receipts)
- Professional Services: $2,500.00 (3 invoices)

Total: $5,038.40

All receipts renamed and filed in:
`Business-Receipts/2024/03-March/[Category]/`

CSV export: `march-2024-expenses.csv`
```

### Example 3: Multi-Year Archive

**User**: "I have 3 years of random invoices. Organize them by year, then by vendor."

**Output**: Creates structure:
```
Invoices/
├── 2022/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
├── 2023/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
└── 2024/
    ├── Adobe/
    ├── Amazon/
    └── ...
```

Each file properly renamed with date and description.

### Example 4: Email Downloads Cleanup

**User**: "I download invoices from Gmail. They're all named 'invoice.pdf', 'invoice(1).pdf', etc. Fix this mess."

**Output**:
```markdown
Found 89 files all named "invoice*.pdf"

Reading each file to extract real information...

Renamed examples:
- invoice.pdf → 2024-03-15 Shopify - Invoice - Monthly Subscription.pdf
- invoice(1).pdf → 2024-03-14 Google - Invoice - Workspace.pdf
- invoice(2).pdf → 2024-03-10 Netlify - Invoice - Pro Plan.pdf

All files renamed and organized by vendor.
```

## Common Organization Patterns

### By Vendor (Simple)
```
Invoices/
├── Adobe/
├── Amazon/
├── Google/
└── Microsoft/
```

### By Year and Category (Tax-Friendly)
```
Invoices/
├── 2023/
│   ├── Software/
│   ├── Hardware/
│   ├── Services/
│   └── Travel/
└── 2024/
    └── ...
```

### By Quarter (Detailed Tracking)
```
Invoices/
├── 2024/
│   ├── Q1/
│   │   ├── Software/
│   │   ├── Office/
│   │   └── Travel/
│   └── Q2/
│       └── ...
```

### By Tax Category (Accountant-Ready)
```
Invoices/
├── Deductible/
│   ├── Software/
│   ├── Office/
│   └── Professional-Services/
├── Partially-Deductible/
│   └── Meals-Travel/
└── Personal/
```

## Automation Setup

For ongoing organization:

```
Create a script that watches my ~/Downloads/invoices folder 
and auto-organizes any new invoice files using our standard 
naming and folder structure.
```

This creates a persistent solution that organizes invoices as they arrive.

## Pro Tips

1. **Scan emails to PDF**: Use Preview or similar to save email invoices as PDFs first
2. **Consistent downloads**: Save all invoices to one folder for batch processing
3. **Monthly routine**: Organize invoices monthly, not annually
4. **Backup originals**: Keep original files before reorganizing
5. **Include amounts in CSV**: Useful for budget tracking
6. **Tag by deductibility**: Note which expenses are tax-deductible
7. **Keep receipts 7 years**: Standard audit period

## Handling Special Cases

### Missing Information
If date/vendor can't be extracted:
- Flag file for manual review
- Use file modification date as fallback
- Create "Needs-Review/" folder

### Duplicate Invoices
If same invoice appears multiple times:
- Compare file hashes
- Keep highest quality version
- Note duplicates in summary

### Multi-Page Invoices
For invoices split across files:
- Merge PDFs if needed
- Use consistent naming for parts
- Note in CSV if invoice is split

### Non-Standard Formats
For unusual receipt formats:
- Extract what's possible
- Standardize what you can
- Flag for review if critical info missing

## Related Use Cases

- Creating expense reports for reimbursement
- Organizing bank statements
- Managing vendor contracts
- Archiving old financial records
- Preparing for audits
- Tracking subscription costs over time

{
  "format": "aiskill/v1",
  "skill": {
    "name": "invoice-organizer",
    "slug": "invoice-organizer",
    "version": "1.0.0",
    "description": "Automatically organizes invoices and receipts for tax preparation by reading messy files, extracting key information, renaming them consistently, and sorting them into logical folders. Turns hours of manual bookkeeping into minutes of automated organization.",
    "category": "Productivity",
    "tags": [
      "productivity"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "APACHE-2.0"
  },
  "prompts": {
    "system": "# Invoice Organizer\r\n\r\nThis skill transforms chaotic folders of invoices, receipts, and financial documents into a clean, tax-ready filing system without manual effort.\r\n\r\n## When to Use This Skill\r\n\r\n- Preparing for tax season and need organized records\r\n- Managing business expenses across multiple vendors\r\n- Organizing receipts from a messy folder or email downloads\r\n- Setting up automated invoice filing for ongoing bookkeeping\r\n- Archiving financial records by year or category\r\n- Reconciling expenses for reimbursement\r\n- Preparing documentation for accountants\r\n\r\n## What This Skill Does\r\n\r\n1. **Reads Invoice Content**: Extracts information from PDFs, images, and documents:\r\n   - Vendor/company name\r\n   - Invoice number\r\n   - Date\r\n   - Amount\r\n   - Product or service description\r\n   - Payment method\r\n\r\n2. **Renames Files Consistently**: Creates standardized filenames:\r\n   - Format: `YYYY-MM-DD Vendor - Invoice - ProductOrService.pdf`\r\n   - Examples: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n\r\n3. **Organizes by Category**: Sorts into logical folders:\r\n   - By vendor\r\n   - By expense category (software, office, travel, etc.)\r\n   - By time period (year, quarter, month)\r\n   - By tax category (deductible, personal, etc.)\r\n\r\n4. **Handles Multiple Formats**: Works with:\r\n   - PDF invoices\r\n   - Scanned receipts (JPG, PNG)\r\n   - Email attachments\r\n   - Screenshots\r\n   - Bank statements\r\n\r\n5. **Maintains Originals**: Preserves original files while organizing copies\r\n\r\n## How to Use\r\n\r\n### Basic Usage\r\n\r\nNavigate to your messy invoice folder:\r\n```\r\ncd ~/Desktop/receipts-to-sort\r\n```\r\n\r\nThen ask Claude Code:\r\n```\r\nOrganize these invoices for taxes\r\n```\r\n\r\nOr more specifically:\r\n```\r\nRead all invoices in this folder, rename them to \r\n\"YYYY-MM-DD Vendor - Invoice - Product.pdf\" format, \r\nand organize them by vendor\r\n```\r\n\r\n### Advanced Organization\r\n\r\n```\r\nOrganize these invoices:\r\n1. Extract date, vendor, and description from each file\r\n2. Rename to standard format\r\n3. Sort into folders by expense category (Software, Office, Travel, etc.)\r\n4. Create a CSV spreadsheet with all invoice details for my accountant\r\n```\r\n\r\n## Instructions\r\n\r\nWhen a user requests invoice organization:\r\n\r\n1. **Scan the Folder**\r\n   \r\n   Identify all invoice files:\r\n   ```bash\r\n   # Find all invoice-related files\r\n   find . -type f \\( -name \"*.pdf\" -o -name \"*.jpg\" -o -name \"*.png\" \\) -print\r\n   ```\r\n   \r\n   Report findings:\r\n   - Total number of files\r\n   - File types\r\n   - Date range (if discernible from names)\r\n   - Current organization (or lack thereof)\r\n\r\n2. **Extract Information from Each File**\r\n   \r\n   For each invoice, extract:\r\n   \r\n   **From PDF invoices**:\r\n   - Use text extraction to read invoice content\r\n   - Look for common patterns:\r\n     - \"Invoice Date:\", \"Date:\", \"Issued:\"\r\n     - \"Invoice #:\", \"Invoice Number:\"\r\n     - Company name (usually at top)\r\n     - \"Amount Due:\", \"Total:\", \"Amount:\"\r\n     - \"Description:\", \"Service:\", \"Product:\"\r\n   \r\n   **From image receipts**:\r\n   - Read visible text from images\r\n   - Identify vendor name (often at top)\r\n   - Look for date (common formats)\r\n   - Find total amount\r\n   \r\n   **Fallback for unclear files**:\r\n   - Use filename clues\r\n   - Check file creation/modification date\r\n   - Flag for manual review if critical info missing\r\n\r\n3. **Determine Organization Strategy**\r\n   \r\n   Ask user preference if not specified:\r\n   \r\n   ```markdown\r\n   I found [X] invoices from [date range].\r\n   \r\n   How would you like them organized?\r\n   \r\n   1. **By Vendor** (Adobe/, Amazon/, Stripe/, etc.)\r\n   2. **By Category** (Software/, Office Supplies/, Travel/, etc.)\r\n   3. **By Date** (2024/Q1/, 2024/Q2/, etc.)\r\n   4. **By Tax Category** (Deductible/, Personal/, etc.)\r\n   5. **Custom** (describe your structure)\r\n   \r\n   Or I can use a default structure: Year/Category/Vendor\r\n   ```\r\n\r\n4. **Create Standardized Filename**\r\n   \r\n   For each invoice, create a filename following this pattern:\r\n   \r\n   ```\r\n   YYYY-MM-DD Vendor - Invoice - Description.ext\r\n   ```\r\n   \r\n   Examples:\r\n   - `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n   - `2024-01-10 Amazon - Receipt - Office Supplies.pdf`\r\n   - `2023-12-01 Stripe - Invoice - Monthly Payment Processing.pdf`\r\n   \r\n   **Filename Best Practices**:\r\n   - Remove special characters except hyphens\r\n   - Capitalize vendor names properly\r\n   - Keep descriptions concise but meaningful\r\n   - Use consistent date format (YYYY-MM-DD) for sorting\r\n   - Preserve original file extension\r\n\r\n5. **Execute Organization**\r\n   \r\n   Before moving files, show the plan:\r\n   \r\n   ```markdown\r\n   # Organization Plan\r\n   \r\n   ## Proposed Structure\r\n   ```\r\n   Invoices/\r\n   ├── 2023/\r\n   │   ├── Software/\r\n   │   │   ├── Adobe/\r\n   │   │   └── Microsoft/\r\n   │   ├── Services/\r\n   │   └── Office/\r\n   └── 2024/\r\n       ├── Software/\r\n       ├── Services/\r\n       └── Office/\r\n   ```\r\n   \r\n   ## Sample Changes\r\n   \r\n   Before: `invoice_adobe_march.pdf`\r\n   After: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n   Location: `Invoices/2024/Software/Adobe/`\r\n   \r\n   Before: `IMG_2847.jpg`\r\n   After: `2024-02-10 Staples - Receipt - Office Supplies.jpg`\r\n   Location: `Invoices/2024/Office/Staples/`\r\n   \r\n   Process [X] files? (yes/no)\r\n   ```\r\n   \r\n   After approval:\r\n   ```bash\r\n   # Create folder structure\r\n   mkdir -p \"Invoices/2024/Software/Adobe\"\r\n   \r\n   # Copy (don't move) to preserve originals\r\n   cp \"original.pdf\" \"Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf\"\r\n   \r\n   # Or move if user prefers\r\n   mv \"original.pdf\" \"new/path/standardized-name.pdf\"\r\n   ```\r\n\r\n6. **Generate Summary Report**\r\n   \r\n   Create a CSV file with all invoice details:\r\n   \r\n   ```csv\r\n   Date,Vendor,Invoice Number,Description,Amount,Category,File Path\r\n   2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf\r\n   2024-03-10,Amazon,123-4567890-1234567,Office Supplies,127.45,Office,Invoices/2024/Office/Amazon/2024-03-10 Amazon - Receipt - Office Supplies.pdf\r\n   ...\r\n   ```\r\n   \r\n   This CSV is useful for:\r\n   - Importing into accounting software\r\n   - Sharing with accountants\r\n   - Expense tracking and reporting\r\n   - Tax preparation\r\n\r\n7. **Provide Completion Summary**\r\n   \r\n   ```markdown\r\n   # Organization Complete! 📊\r\n   \r\n   ## Summary\r\n   - **Processed**: [X] invoices\r\n   - **Date range**: [earliest] to [latest]\r\n   - **Total amount**: $[sum] (if amounts extracted)\r\n   - **Vendors**: [Y] unique vendors\r\n   \r\n   ## New Structure\r\n   ```\r\n   Invoices/\r\n   ├── 2024/ (45 files)\r\n   │   ├── Software/ (23 files)\r\n   │   ├── Services/ (12 files)\r\n   │   └── Office/ (10 files)\r\n   └── 2023/ (12 files)\r\n   ```\r\n   \r\n   ## Files Created\r\n   - `/Invoices/` - Organized invoices\r\n   - `/Invoices/invoice-summary.csv` - Spreadsheet for accounting\r\n   - `/Invoices/originals/` - Original files (if copied)\r\n   \r\n   ## Files Needing Review\r\n   [List any files where information couldn't be extracted completely]\r\n   \r\n   ## Next Steps\r\n   1. Review the `invoice-summary.csv` file\r\n   2. Check files in \"Needs Review\" folder\r\n   3. Import CSV into your accounting software\r\n   4. Set up auto-organization for future invoices\r\n   \r\n   Ready for tax season! 🎉\r\n   ```\r\n\r\n## Examples\r\n\r\n### Example 1: Tax Preparation (From Martin Merschroth)\r\n\r\n**User**: \"I have a messy folder of invoices for taxes. Sort them and rename properly.\"\r\n\r\n**Process**:\r\n1. Scans folder: finds 147 PDFs and images\r\n2. Reads each invoice to extract:\r\n   - Date\r\n   - Vendor name\r\n   - Invoice number\r\n   - Product/service description\r\n3. Renames all files: `YYYY-MM-DD Vendor - Invoice - Product.pdf`\r\n4. Organizes into: `2024/Software/`, `2024/Travel/`, etc.\r\n5. Creates `invoice-summary.csv` for accountant\r\n6. Result: Tax-ready organized invoices in minutes\r\n\r\n### Example 2: Monthly Expense Reconciliation\r\n\r\n**User**: \"Organize my business receipts from last month by category.\"\r\n\r\n**Output**:\r\n```markdown\r\n# March 2024 Receipts Organized\r\n\r\n## By Category\r\n- Software & Tools: $847.32 (12 invoices)\r\n- Office Supplies: $234.18 (8 receipts)\r\n- Travel & Meals: $1,456.90 (15 receipts)\r\n- Professional Services: $2,500.00 (3 invoices)\r\n\r\nTotal: $5,038.40\r\n\r\nAll receipts renamed and filed in:\r\n`Business-Receipts/2024/03-March/[Category]/`\r\n\r\nCSV export: `march-2024-expenses.csv`\r\n```\r\n\r\n### Example 3: Multi-Year Archive\r\n\r\n**User**: \"I have 3 years of random invoices. Organize them by year, then by vendor.\"\r\n\r\n**Output**: Creates structure:\r\n```\r\nInvoices/\r\n├── 2022/\r\n│   ├── Adobe/\r\n│   ├── Amazon/\r\n│   └── ...\r\n├── 2023/\r\n│   ├── Adobe/\r\n│   ├── Amazon/\r\n│   └── ...\r\n└── 2024/\r\n    ├── Adobe/\r\n    ├── Amazon/\r\n    └── ...\r\n```\r\n\r\nEach file properly renamed with date and description.\r\n\r\n### Example 4: Email Downloads Cleanup\r\n\r\n**User**: \"I download invoices from Gmail. They're all named 'invoice.pdf', 'invoice(1).pdf', etc. Fix this mess.\"\r\n\r\n**Output**:\r\n```markdown\r\nFound 89 files all named \"invoice*.pdf\"\r\n\r\nReading each file to extract real information...\r\n\r\nRenamed examples:\r\n- invoice.pdf → 2024-03-15 Shopify - Invoice - Monthly Subscription.pdf\r\n- invoice(1).pdf → 2024-03-14 Google - Invoice - Workspace.pdf\r\n- invoice(2).pdf → 2024-03-10 Netlify - Invoice - Pro Plan.pdf\r\n\r\nAll files renamed and organized by vendor.\r\n```\r\n\r\n## Common Organization Patterns\r\n\r\n### By Vendor (Simple)\r\n```\r\nInvoices/\r\n├── Adobe/\r\n├── Amazon/\r\n├── Google/\r\n└── Microsoft/\r\n```\r\n\r\n### By Year and Category (Tax-Friendly)\r\n```\r\nInvoices/\r\n├── 2023/\r\n│   ├── Software/\r\n│   ├── Hardware/\r\n│   ├── Services/\r\n│   └── Travel/\r\n└── 2024/\r\n    └── ...\r\n```\r\n\r\n### By Quarter (Detailed Tracking)\r\n```\r\nInvoices/\r\n├── 2024/\r\n│   ├── Q1/\r\n│   │   ├── Software/\r\n│   │   ├── Office/\r\n│   │   └── Travel/\r\n│   └── Q2/\r\n│       └── ...\r\n```\r\n\r\n### By Tax Category (Accountant-Ready)\r\n```\r\nInvoices/\r\n├── Deductible/\r\n│   ├── Software/\r\n│   ├── Office/\r\n│   └── Professional-Services/\r\n├── Partially-Deductible/\r\n│   └── Meals-Travel/\r\n└── Personal/\r\n```\r\n\r\n## Automation Setup\r\n\r\nFor ongoing organization:\r\n\r\n```\r\nCreate a script that watches my ~/Downloads/invoices folder \r\nand auto-organizes any new invoice files using our standard \r\nnaming and folder structure.\r\n```\r\n\r\nThis creates a persistent solution that organizes invoices as they arrive.\r\n\r\n## Pro Tips\r\n\r\n1. **Scan emails to PDF**: Use Preview or similar to save email invoices as PDFs first\r\n2. **Consistent downloads**: Save all invoices to one folder for batch processing\r\n3. **Monthly routine**: Organize invoices monthly, not annually\r\n4. **Backup originals**: Keep original files before reorganizing\r\n5. **Include amounts in CSV**: Useful for budget tracking\r\n6. **Tag by deductibility**: Note which expenses are tax-deductible\r\n7. **Keep receipts 7 years**: Standard audit period\r\n\r\n## Handling Special Cases\r\n\r\n### Missing Information\r\nIf date/vendor can't be extracted:\r\n- Flag file for manual review\r\n- Use file modification date as fallback\r\n- Create \"Needs-Review/\" folder\r\n\r\n### Duplicate Invoices\r\nIf same invoice appears multiple times:\r\n- Compare file hashes\r\n- Keep highest quality version\r\n- Note duplicates in summary\r\n\r\n### Multi-Page Invoices\r\nFor invoices split across files:\r\n- Merge PDFs if needed\r\n- Use consistent naming for parts\r\n- Note in CSV if invoice is split\r\n\r\n### Non-Standard Formats\r\nFor unusual receipt formats:\r\n- Extract what's possible\r\n- Standardize what you can\r\n- Flag for review if critical info missing\r\n\r\n## Related Use Cases\r\n\r\n- Creating expense reports for reimbursement\r\n- Organizing bank statements\r\n- Managing vendor contracts\r\n- Archiving old financial records\r\n- Preparing for audits\r\n- Tracking subscription costs over time",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The invoice-organizer/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/invoice-organizer",
    "exported_at": "2026-11-03T07:43:59.076Z"
  }
}

format: aiskill/v1
skill:
  name: invoice-organizer
  slug: invoice-organizer
  version: 1.0.0
  description: >-
    Automatically organizes invoices and receipts for tax preparation by reading messy files,
    extracting key information, renaming them consistently, and sorting them into logical folders.
    Turns hours of manual bookkeeping into minutes of automated organization.
  category: Productivity
  tags:
    - productivity
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: APACHE-2.0
prompts:
  system: "# Invoice Organizer\r\n\r\nThis skill transforms chaotic folders of invoices, receipts, and financial documents into a clean, tax-ready filing system without manual effort.\r\n\r\n## When to Use This Skill\r\n\r\n- Preparing for tax season and need organized records\r\n- Managing business expenses across multiple vendors\r\n- Organizing receipts from a messy folder or email downloads\r\n- Setting up automated invoice filing for ongoing bookkeeping\r\n- Archiving financial records by year or category\r\n- Reconciling expenses for reimbursement\r\n- Preparing documentation for accountants\r\n\r\n## What This Skill Does\r\n\r\n1. **Reads Invoice Content**: Extracts information from PDFs, images, and documents:\r\n   - Vendor/company name\r\n   - Invoice number\r\n   - Date\r\n   - Amount\r\n   - Product or service description\r\n   - Payment method\r\n\r\n2. **Renames Files Consistently**: Creates standardized filenames:\r\n   - Format: `YYYY-MM-DD Vendor - Invoice - ProductOrService.pdf`\r\n   - Examples: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n\r\n3. **Organizes by Category**: Sorts into logical folders:\r\n   - By vendor\r\n   - By expense category (software, office, travel, etc.)\r\n   - By time period (year, quarter, month)\r\n   - By tax category (deductible, personal, etc.)\r\n\r\n4. **Handles Multiple Formats**: Works with:\r\n   - PDF invoices\r\n   - Scanned receipts (JPG, PNG)\r\n   - Email attachments\r\n   - Screenshots\r\n   - Bank statements\r\n\r\n5. **Maintains Originals**: Preserves original files while organizing copies\r\n\r\n## How to Use\r\n\r\n### Basic Usage\r\n\r\nNavigate to your messy invoice folder:\r\n```\r\ncd ~/Desktop/receipts-to-sort\r\n```\r\n\r\nThen ask Claude Code:\r\n```\r\nOrganize these invoices for taxes\r\n```\r\n\r\nOr more specifically:\r\n```\r\nRead all invoices in this folder, rename them to \r\n\"YYYY-MM-DD Vendor - Invoice - Product.pdf\" format, \r\nand organize them by vendor\r\n```\r\n\r\n### Advanced Organization\r\n\r\n```\r\nOrganize these invoices:\r\n1. Extract date, vendor, and description from each file\r\n2. Rename to standard format\r\n3. Sort into folders by expense category (Software, Office, Travel, etc.)\r\n4. Create a CSV spreadsheet with all invoice details for my accountant\r\n```\r\n\r\n## Instructions\r\n\r\nWhen a user requests invoice organization:\r\n\r\n1. **Scan the Folder**\r\n   \r\n   Identify all invoice files:\r\n   ```bash\r\n   # Find all invoice-related files\r\n   find . -type f \\( -name \"*.pdf\" -o -name \"*.jpg\" -o -name \"*.png\" \\) -print\r\n   ```\r\n   \r\n   Report findings:\r\n   - Total number of files\r\n   - File types\r\n   - Date range (if discernible from names)\r\n   - Current organization (or lack thereof)\r\n\r\n2. **Extract Information from Each File**\r\n   \r\n   For each invoice, extract:\r\n   \r\n   **From PDF invoices**:\r\n   - Use text extraction to read invoice content\r\n   - Look for common patterns:\r\n     - \"Invoice Date:\", \"Date:\", \"Issued:\"\r\n     - \"Invoice#:\", \"Invoice Number:\"\r\n     - Company name (usually at top)\r\n     - \"Amount Due:\", \"Total:\", \"Amount:\"\r\n     - \"Description:\", \"Service:\", \"Product:\"\r\n   \r\n   **From image receipts**:\r\n   - Read visible text from images\r\n   - Identify vendor name (often at top)\r\n   - Look for date (common formats)\r\n   - Find total amount\r\n   \r\n   **Fallback for unclear files**:\r\n   - Use filename clues\r\n   - Check file creation/modification date\r\n   - Flag for manual review if critical info missing\r\n\r\n3. **Determine Organization Strategy**\r\n   \r\n   Ask user preference if not specified:\r\n   \r\n   ```markdown\r\n   I found [X] invoices from [date range].\r\n   \r\n   How would you like them organized?\r\n   \r\n   1. **By Vendor** (Adobe/, Amazon/, Stripe/, etc.)\r\n   2. **By Category** (Software/, Office Supplies/, Travel/, etc.)\r\n   3. **By Date** (2024/Q1/, 2024/Q2/, etc.)\r\n   4. **By Tax Category** (Deductible/, Personal/, etc.)\r\n   5. **Custom** (describe your structure)\r\n   \r\n   Or I can use a default structure: Year/Category/Vendor\r\n   ```\r\n\r\n4. **Create Standardized Filename**\r\n   \r\n   For each invoice, create a filename following this pattern:\r\n   \r\n   ```\r\n   YYYY-MM-DD Vendor - Invoice - Description.ext\r\n   ```\r\n   \r\n   Examples:\r\n   - `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n   - `2024-01-10 Amazon - Receipt - Office Supplies.pdf`\r\n   - `2023-12-01 Stripe - Invoice - Monthly Payment Processing.pdf`\r\n   \r\n   **Filename Best Practices**:\r\n   - Remove special characters except hyphens\r\n   - Capitalize vendor names properly\r\n   - Keep descriptions concise but meaningful\r\n   - Use consistent date format (YYYY-MM-DD) for sorting\r\n   - Preserve original file extension\r\n\r\n5. **Execute Organization**\r\n   \r\n   Before moving files, show the plan:\r\n   \r\n   ```markdown\r\n   # Organization Plan\r\n   \r\n   ## Proposed Structure\r\n   ```\r\n   Invoices/\r\n   ├── 2023/\r\n   │   ├── Software/\r\n   │   │   ├── Adobe/\r\n   │   │   └── Microsoft/\r\n   │   ├── Services/\r\n   │   └── Office/\r\n   └── 2024/\r\n       ├── Software/\r\n       ├── Services/\r\n       └── Office/\r\n   ```\r\n   \r\n   ## Sample Changes\r\n   \r\n   Before: `invoice_adobe_march.pdf`\r\n   After: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`\r\n   Location: `Invoices/2024/Software/Adobe/`\r\n   \r\n   Before: `IMG_2847.jpg`\r\n   After: `2024-02-10 Staples - Receipt - Office Supplies.jpg`\r\n   Location: `Invoices/2024/Office/Staples/`\r\n   \r\n   Process [X] files? (yes/no)\r\n   ```\r\n   \r\n   After approval:\r\n   ```bash\r\n   # Create folder structure\r\n   mkdir -p \"Invoices/2024/Software/Adobe\"\r\n   \r\n   # Copy (don't move) to preserve originals\r\n   cp \"original.pdf\" \"Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf\"\r\n   \r\n   # Or move if user prefers\r\n   mv \"original.pdf\" \"new/path/standardized-name.pdf\"\r\n   ```\r\n\r\n6. **Generate Summary Report**\r\n   \r\n   Create a CSV file with all invoice details:\r\n   \r\n   ```csv\r\n   Date,Vendor,Invoice Number,Description,Amount,Category,File Path\r\n   2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf\r\n   2024-03-10,Amazon,123-4567890-1234567,Office Supplies,127.45,Office,Invoices/2024/Office/Amazon/2024-03-10 Amazon - Receipt - Office Supplies.pdf\r\n   ...\r\n   ```\r\n   \r\n   This CSV is useful for:\r\n   - Importing into accounting software\r\n   - Sharing with accountants\r\n   - Expense tracking and reporting\r\n   - Tax preparation\r\n\r\n7. **Provide Completion Summary**\r\n   \r\n   ```markdown\r\n   # Organization Complete! 📊\r\n   \r\n   ## Summary\r\n   - **Processed**: [X] invoices\r\n   - **Date range**: [earliest] to [latest]\r\n   - **Total amount**: $[sum] (if amounts extracted)\r\n   - **Vendors**: [Y] unique vendors\r\n   \r\n   ## New Structure\r\n   ```\r\n   Invoices/\r\n   ├── 2024/ (45 files)\r\n   │   ├── Software/ (23 files)\r\n   │   ├── Services/ (12 files)\r\n   │   └── Office/ (10 files)\r\n   └── 2023/ (12 files)\r\n   ```\r\n   \r\n   ## Files Created\r\n   - `/Invoices/` - Organized invoices\r\n   - `/Invoices/invoice-summary.csv` - Spreadsheet for accounting\r\n   - `/Invoices/originals/` - Original files (if copied)\r\n   \r\n   ## Files Needing Review\r\n   [List any files where information couldn't be extracted completely]\r\n   \r\n   ## Next Steps\r\n   1. Review the `invoice-summary.csv` file\r\n   2. Check files in \"Needs Review\" folder\r\n   3. Import CSV into your accounting software\r\n   4. Set up auto-organization for future invoices\r\n   \r\n   Ready for tax season! 🎉\r\n   ```\r\n\r\n## Examples\r\n\r\n### Example 1: Tax Preparation (From Martin Merschroth)\r\n\r\n**User**: \"I have a messy folder of invoices for taxes. Sort them and rename properly.\"\r\n\r\n**Process**:\r\n1. Scans folder: finds 147 PDFs and images\r\n2. Reads each invoice to extract:\r\n   - Date\r\n   - Vendor name\r\n   - Invoice number\r\n   - Product/service description\r\n3. Renames all files: `YYYY-MM-DD Vendor - Invoice - Product.pdf`\r\n4. Organizes into: `2024/Software/`, `2024/Travel/`, etc.\r\n5. Creates `invoice-summary.csv` for accountant\r\n6. Result: Tax-ready organized invoices in minutes\r\n\r\n### Example 2: Monthly Expense Reconciliation\r\n\r\n**User**: \"Organize my business receipts from last month by category.\"\r\n\r\n**Output**:\r\n```markdown\r\n# March 2024 Receipts Organized\r\n\r\n## By Category\r\n- Software & Tools: $847.32 (12 invoices)\r\n- Office Supplies: $234.18 (8 receipts)\r\n- Travel & Meals: $1,456.90 (15 receipts)\r\n- Professional Services: $2,500.00 (3 invoices)\r\n\r\nTotal: $5,038.40\r\n\r\nAll receipts renamed and filed in:\r\n`Business-Receipts/2024/03-March/[Category]/`\r\n\r\nCSV export: `march-2024-expenses.csv`\r\n```\r\n\r\n### Example 3: Multi-Year Archive\r\n\r\n**User**: \"I have 3 years of random invoices. Organize them by year, then by vendor.\"\r\n\r\n**Output**: Creates structure:\r\n```\r\nInvoices/\r\n├── 2022/\r\n│   ├── Adobe/\r\n│   ├── Amazon/\r\n│   └── ...\r\n├── 2023/\r\n│   ├── Adobe/\r\n│   ├── Amazon/\r\n│   └── ...\r\n└── 2024/\r\n    ├── Adobe/\r\n    ├── Amazon/\r\n    └── ...\r\n```\r\n\r\nEach file properly renamed with date and description.\r\n\r\n### Example 4: Email Downloads Cleanup\r\n\r\n**User**: \"I download invoices from Gmail. They're all named 'invoice.pdf', 'invoice(1).pdf', etc. Fix this mess.\"\r\n\r\n**Output**:\r\n```markdown\r\nFound 89 files all named \"invoice*.pdf\"\r\n\r\nReading each file to extract real information...\r\n\r\nRenamed examples:\r\n- invoice.pdf → 2024-03-15 Shopify - Invoice - Monthly Subscription.pdf\r\n- invoice(1).pdf → 2024-03-14 Google - Invoice - Workspace.pdf\r\n- invoice(2).pdf → 2024-03-10 Netlify - Invoice - Pro Plan.pdf\r\n\r\nAll files renamed and organized by vendor.\r\n```\r\n\r\n## Common Organization Patterns\r\n\r\n### By Vendor (Simple)\r\n```\r\nInvoices/\r\n├── Adobe/\r\n├── Amazon/\r\n├── Google/\r\n└── Microsoft/\r\n```\r\n\r\n### By Year and Category (Tax-Friendly)\r\n```\r\nInvoices/\r\n├── 2023/\r\n│   ├── Software/\r\n│   ├── Hardware/\r\n│   ├── Services/\r\n│   └── Travel/\r\n└── 2024/\r\n    └── ...\r\n```\r\n\r\n### By Quarter (Detailed Tracking)\r\n```\r\nInvoices/\r\n├── 2024/\r\n│   ├── Q1/\r\n│   │   ├── Software/\r\n│   │   ├── Office/\r\n│   │   └── Travel/\r\n│   └── Q2/\r\n│       └── ...\r\n```\r\n\r\n### By Tax Category (Accountant-Ready)\r\n```\r\nInvoices/\r\n├── Deductible/\r\n│   ├── Software/\r\n│   ├── Office/\r\n│   └── Professional-Services/\r\n├── Partially-Deductible/\r\n│   └── Meals-Travel/\r\n└── Personal/\r\n```\r\n\r\n## Automation Setup\r\n\r\nFor ongoing organization:\r\n\r\n```\r\nCreate a script that watches my ~/Downloads/invoices folder \r\nand auto-organizes any new invoice files using our standard \r\nnaming and folder structure.\r\n```\r\n\r\nThis creates a persistent solution that organizes invoices as they arrive.\r\n\r\n## Pro Tips\r\n\r\n1. **Scan emails to PDF**: Use Preview or similar to save email invoices as PDFs first\r\n2. **Consistent downloads**: Save all invoices to one folder for batch processing\r\n3. **Monthly routine**: Organize invoices monthly, not annually\r\n4. **Backup originals**: Keep original files before reorganizing\r\n5. **Include amounts in CSV**: Useful for budget tracking\r\n6. **Tag by deductibility**: Note which expenses are tax-deductible\r\n7. **Keep receipts 7 years**: Standard audit period\r\n\r\n## Handling Special Cases\r\n\r\n### Missing Information\r\nIf date/vendor can't be extracted:\r\n- Flag file for manual review\r\n- Use file modification date as fallback\r\n- Create \"Needs-Review/\" folder\r\n\r\n### Duplicate Invoices\r\nIf same invoice appears multiple times:\r\n- Compare file hashes\r\n- Keep highest quality version\r\n- Note duplicates in summary\r\n\r\n### Multi-Page Invoices\r\nFor invoices split across files:\r\n- Merge PDFs if needed\r\n- Use consistent naming for parts\r\n- Note in CSV if invoice is split\r\n\r\n### Non-Standard Formats\r\nFor unusual receipt formats:\r\n- Extract what's possible\r\n- Standardize what you can\r\n- Flag for review if critical info missing\r\n\r\n## Related Use Cases\r\n\r\n- Creating expense reports for reimbursement\r\n- Organizing bank statements\r\n- Managing vendor contracts\r\n- Archiving old financial records\r\n- Preparing for audits\r\n- Tracking subscription costs over time"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The invoice-organizer/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/invoice-organizer
  exported_at: "2026-11-03T07:43:59.076Z"