process-invoice

name	process-invoice
description	Automated invoice processing workflow. Finds invoices from vendors in Downloads, extracts vendor and date information, and uploads to the appropriate vendor folder in Google Drive with proper naming.

Invoice Processing Workflow

This skill automates the invoice management process by finding invoices from vendors in your Downloads folder and organizing them into your Google Drive by vendor.

Configuration

Before using this skill, you MUST have the following configured:

• Google Drive API credentials set up (uses same setup as process-receipt skill)
• Invoices folder ID is stored in config.txt
• Vendor subfolders already exist in the Invoices folder

Important: The Invoices folder ID is: 1wvXrOAlh9J5gmjz5npkuYIg883wiLcWD

This folder contains subfolders for each vendor (e.g., JayMac, Camilo Jaime Gomez, Friendly Design, Studio Hanlon).

Workflow Steps

1. Find Invoice in Downloads Folder

• Check ~/Downloads for the most recent PDF or image file (jpg, jpeg, png)
• Filter for files modified in the last 7 days to avoid old files
• Use command: find ~/Downloads -type f \( -name "*.pdf" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.png" \) -mtime -7 -print0 | xargs -0 ls -t | head -1
• If no invoice found, inform user and exit
• If invoice found, display the filename and path to user

2. Extract Information from Invoice

• Read the invoice file (if PDF, extract text; if image, analyze visually)
• Look for key information on the invoice:
  • Vendor/client name: Who sent this invoice (the business billing you)
  • Invoice date: Date of the invoice
  • Invoice number: Unique invoice identifier
  • Amount: Total amount (optional, for context)
• Important: Focus on the vendor name - this determines which folder to use

3. Confirm Vendor Name

• Use AskUserQuestion tool to confirm the vendor name:
  • Present the extracted vendor name
  • Ask user to confirm or provide the correct vendor name
  • This ensures accurate folder matching even if extraction isn't perfect

4. Find Vendor Folder in Google Drive

• Read the Invoices folder ID from config.txt: 1wvXrOAlh9J5gmjz5npkuYIg883wiLcWD
• List available vendor folders:

  ~/.claude/skills/process-receipt/venv/bin/python3 ~/.claude/skills/process-receipt/gdrive_helper.py list 1wvXrOAlh9J5gmjz5npkuYIg883wiLcWD
  

• Match the confirmed vendor name to existing folders
• If exact match not found:
  • Show user the list of available vendor folders
  • Ask which folder to use, or if they want to create a new one
  • Note: Skill cannot create new folders - user must do this manually if needed

5. Generate Appropriate Filename

• Create filename in format: Invoice-YYYY-MM-DD-VendorName-InvoiceNumber.pdf
• Example formats:
  • Invoice-2025-11-18-JayMac-INV-2024.pdf
  • Invoice-2025-10-15-FriendlyDesign-12345.pdf
  • Invoice-2025-09-01-StudioHanlon-SH-0987.pdf
• If invoice number cannot be extracted, ask user or use a generic format like:
  • Invoice-2025-11-18-VendorName.pdf
• Ensure filename is filesystem-safe (no special characters like /, :, etc.)
• Replace spaces in vendor names with hyphens or remove them

6. Upload Invoice to Google Drive

• Upload the invoice with the generated filename:

  ~/.claude/skills/process-receipt/venv/bin/python3 ~/.claude/skills/process-receipt/gdrive_helper.py upload "<invoice_file_path>" "<vendor_folder_id>" "<generated_filename>"
  

• The script will return:
  • File ID
  • File name
  • View link
• Display the view link to user for verification

7. Confirm and Clean Up

• Inform user that invoice has been successfully uploaded
• Show the final location: "Invoices / / "
• Ask user if they want to delete the invoice from Downloads
• If yes, move the file to trash: trash "<invoice_file_path>"
• If no, leave it in Downloads

Error Handling

• No invoice found: Inform user no recent invoices in Downloads
• Vendor extraction fails: Ask user for vendor name manually
• Vendor folder not found: List available folders and ask user to select or create one
• Upload fails: Display error message and suggest checking:
  • Google Drive credentials (uses same token.pickle as process-receipt)
  • Folder permissions
  • Network connection
• Python dependencies missing: Dependencies are shared with process-receipt skill
  • If process-receipt works, this skill will work too

Important Notes

• This skill is for invoices FROM vendors (bills you receive and pay)
• NOT for invoices you send to clients
• The skill uses the same Google Drive helper and venv as process-receipt
• Vendor folders must be created manually in Google Drive before first use
• Each upload creates a new file (does not overwrite existing files)
• Original file in Downloads is only deleted if user explicitly confirms

Shared Resources

This skill shares resources with process-receipt:

• Python virtual environment: ~/.claude/skills/process-receipt/venv/
• Google Drive helper script: ~/.claude/skills/process-receipt/gdrive_helper.py
• OAuth credentials: ~/.claude/skills/process-receipt/credentials.json
• Auth token: ~/.claude/skills/process-receipt/token.pickle

No additional setup is needed if process-receipt is already configured.