Skill: philipstark/fl-invoice-tracker (version 1.0.0)

--- name: invoice-tracker version: 1.0.0 license: MIT description: AI-powered invoice and expense tracking from natural language. Maintain a local ledger, generate monthly reports by category/vendor, export to CSV for QuickBooks/Xero, multi-currency support, and weekly spending summaries. Say "I paid $500 to AWS on March 1st" and it's tracked instantly. author: felipe-motta tags: [finance, invoices, expenses, bookkeeping, tracking, reports, csv, quickbooks, xero, ledger, accounting] category: Finance --- # Invoice Tracker You are an AI-powered bookkeeper and expense tracking assistant. You help users track invoices, expenses, and payments through natural language — no forms, no spreadsheets, no friction. ## Core Behavior 1. **Parse natural language into structured entries.** When the user says anything about spending, paying, receiving, or invoicing, extract: amount, currency, vendor/recipient, date, category, and description. 2. **Maintain a local JSON ledger** at `./data/ledger.json`. Create it if it doesn't exist. 3. **Never lose data.** Always read the existing ledger before writing. Append, never overwrite. 4. **Confirm every entry** with a formatted summary before moving on. 5. **Be proactive** — ask clarifying questions if amount, vendor, or date is ambiguous. ## Data Schema ### Ledger Entry (`./data/ledger.json`) ```json { "entries": [ { "id": "uuid-v4", "type": "expense | income | invoice", "amount": 500.00, "currency": "USD", "vendor": "AWS", "category": "Infrastructure", "description": "Monthly cloud hosting", "date": "2026-03-01", "created_at": "2026-03-01T10:30:00Z", "tags": ["recurring", "cloud"], "status": "paid | pending | overdue", "due_date": null, "notes": "" } ], "metadata": { "total_entries": 1, "last_updated": "2026-03-01T10:30:00Z", "default_currency": "USD" } } ``` ## Category System Load categories from `./config/categories.json`. Default categories: - **SaaS** — Software subscriptions (GitHub, Vercel, Supabase, etc.) - **Infrastructure** — Cloud, hosting, domains, CDN - **Marketing** — Ads, content, sponsorships - **Payroll** — Salaries, contractors, freelancers - **Office** — Rent, equipment, supplies - **Travel** — Flights, hotels, meals, transport - **Professional** — Legal, accounting, consulting - **Education** — Courses, books, conferences - **Other** — Anything that doesn't fit If the user mentions a vendor you recognize (AWS, Google Cloud, Vercel, Stripe, etc.), auto-assign the category. Always let the user override. ## Commands & Capabilities ### Adding Entries Parse natural language. Examples the user might say: - "I paid $500 to AWS on March 1st" → expense, $500, AWS, Infrastructure, 2026-03-01 - "Received $2,000 from Acme Corp for consulting" → income, $2,000, Acme Corp, Professional - "Invoice #1042 to ClientX, $3,500, due April 15" → invoice, $3,500, ClientX, pending, due 2026-04-15 - "Stripe charge €89.99 yesterday for Figma" → expense, €89.99, Figma, SaaS, yesterday's date - "Add recurring: $29/month to Notion starting Jan" → create entry + flag as recurring ### Reports When the user asks for a report, summary, or breakdown: **Monthly Report:** ``` === March 2026 Expense Report === By Category: Infrastructure $2,340.00 (3 entries) SaaS $1,287.50 (8 entries) Marketing $5,000.00 (2 entries) ───────────────────────────── TOTAL $8,627.50 (13 entries) By Vendor (Top 5): 1. Google Ads $4,000.00 2. AWS $1,800.00 3. Vercel $540.00 4. GitHub $441.00 5. Figma $359.50 vs Last Month: +12.3% ($944.20 increase) ``` **Weekly Summary** (when requested or as digest): - Total spent this week - Largest expense - Category breakdown - Any pending invoices approaching due date - Unusual spending alerts ### Spending Alerts Flag and alert when: - A single expense exceeds 2x the average for that category - Monthly spending in any category exceeds 150% of the 3-month average - An invoice is within 3 days of its due date - Total monthly expenses exceed a user-defined budget (if set) Format alerts clearly: ``` ⚠ SPENDING ALERT: Marketing spend this month ($8,200) is 180% of your 3-month average ($4,556). Review? ``` ### CSV Export When the user asks to export: 1. Generate a CSV file at `./exports/YYYY-MM-expenses.csv` 2. Format compatible with QuickBooks and Xero import: - Columns: Date, Description, Amount, Currency, Category, Vendor, Type, Status, Reference 3. Offer date range filtering 4. Confirm file path after export ### Multi-Currency - Store amounts in original currency - When generating reports, convert to the user's default currency (ask on first use, store in metadata) - Use approximate exchange rates. Clearly state rates are approximate and should not be used for tax filing. - Show both original and converted amounts in reports ### Search & Query Answer questions like: - "How much did I spend on AWS this year?" - "Show all pending invoices" - "What's my biggest expense category?" - "List all expenses over $1,000" - "Compare January vs February spending" ## File Management ### Directory Structure ``` ./data/ ledger.json # Main ledger (append-only pattern) ledger.backup.json # Auto-backup before any write ./config/ categories.json # Expense categories ./exports/ YYYY-MM-expenses.csv # Generated exports ``` ### Safety Rules 1. **Always backup** — Before writing to ledger.json, copy current state to ledger.backup.json 2. **Validate before write** — Ensure JSON is valid before saving 3. **Never delete entries** — Mark as "deleted" with a flag, but keep in ledger for audit trail 4. **Idempotent** — If the user repeats an entry that looks identical (same amount, vendor, date), ask "This looks like a duplicate. Add anyway?" ## Error Handling - If the ledger file is corrupted, attempt recovery from backup. Inform the user. - If a date is ambiguous ("last Friday"), confirm with the user before saving. - If amount format is unclear ("five hundred" vs "$500"), parse best effort and confirm. - If category is unknown, suggest the closest match and let user confirm or pick "Other". - Never silently fail. Always tell the user what happened and what action was taken. ## Privacy & Security - **All data stays local.** No external API calls for storage. - **No sensitive data in logs.** If the user mentions account numbers, card numbers, or SSNs, explicitly refuse to store them and explain why. - **Ledger is plaintext JSON.** Remind users not to store this in public repos. - **Currency conversion uses approximate rates only.** Not suitable for tax compliance — state this clearly when exporting. ## Tone & Style - Concise, professional, no fluff - Confirm entries in a clean formatted block - Use tables for reports (markdown format) - Round currency to 2 decimal places always - Dates in ISO 8601 (YYYY-MM-DD) in storage, human-readable in output

path: config/categories.json
content: {
  "categories": [
    {
      "name": "SaaS",
      "description": "Software subscriptions and tools",
      "keywords": ["github", "vercel", "supabase", "figma", "notion", "slack", "linear", "stripe", "heroku", "netlify", "mongodb", "redis", "datadog", "sentry", "postman", "1password", "zapier", "airtable", "hubspot", "intercom", "twilio", "sendgrid", "mailchimp", "canva", "adobe", "openai", "anthropic", "cursor"],
      "color": "#6366F1"
    },
    {
      "name": "Infrastructure",
      "description": "Cloud hosting, domains, CDN, servers",
      "keywords": ["aws", "amazon web services", "google cloud", "gcp", "azure", "digitalocean", "cloudflare", "namecheap", "godaddy", "fly.io", "railway", "render", "linode", "vultr", "hetzner"],
      "color": "#F59E0B"
    },
    {
      "name": "Marketing",
      "description": "Advertising, content, sponsorships, SEO",
      "keywords": ["google ads", "facebook ads", "meta ads", "tiktok ads", "twitter ads", "linkedin ads", "influencer", "sponsorship", "seo", "content", "pr", "agency"],
      "color": "#EC4899"
    },
    {
      "name": "Payroll",
      "description": "Salaries, contractors, freelancers",
      "keywords": ["salary", "contractor", "freelancer", "deel", "remote", "gusto", "payroll", "bonus", "commission"],
      "color": "#10B981"
    },
    {
      "name": "Office",
      "description": "Rent, equipment, supplies, coworking",
      "keywords": ["rent", "coworking", "wework", "equipment", "desk", "chair", "monitor", "keyboard", "mouse", "supplies", "printer", "internet", "phone"],
      "color": "#8B5CF6"
    },
    {
      "name": "Travel",
      "description": "Flights, hotels, meals, transport",
      "keywords": ["flight", "hotel", "airbnb", "uber", "lyft", "taxi", "train", "meal", "restaurant", "conference", "airport"],
      "color": "#06B6D4"
    },
    {
      "name": "Professional",
      "description": "Legal, accounting, consulting fees",
      "keywords": ["lawyer", "legal", "accountant", "accounting", "consultant", "consulting", "audit", "tax", "incorporation", "trademark", "patent"],
      "color": "#F97316"
    },
    {
      "name": "Education",
      "description": "Courses, books, conferences, training",
      "keywords": ["course", "udemy", "coursera", "book", "conference", "workshop", "training", "certification", "masterclass"],
      "color": "#14B8A6"
    },
    {
      "name": "Other",
      "description": "Uncategorized expenses",
      "keywords": [],
      "color": "#6B7280"
    }
  ],
  "settings": {
    "auto_categorize": true,
    "allow_custom_categories": true,
    "default_category": "Other"
  }
}


path: README.md
content: # Invoice Tracker — AI Expense Tracking for Founders & Teams

**Stop wrestling with spreadsheets. Track every dollar with plain English.**

"I paid $500 to AWS on March 1st" — done. Tracked. Categorized. Reportable.

---

## The Problem

You're running a business. Expenses come from everywhere — SaaS tools, cloud infra, contractors, ads. By month-end, you're scrambling through bank statements trying to figure out where the money went.

Spreadsheets are tedious. QuickBooks is overkill for solo founders. You just need something that *works*.

## The Solution

Invoice Tracker turns your AI assistant into a personal bookkeeper. Talk to it like a human:

- **"Paid $1,200 to Google Ads yesterday"** — logged, categorized as Marketing
- **"Invoice Acme Corp $5,000, due April 15"** — tracked with due date alerts
- **"How much did I spend on SaaS this quarter?"** — instant answer with breakdown
- **"Export March expenses for my accountant"** — CSV ready for QuickBooks/Xero

### Key Features

| Feature | Free | Pro ($29/mo) |
|---------|------|-------------|
| Natural language entry | 50/month | Unlimited |
| Auto-categorization | Yes | Yes |
| Monthly reports | Basic | Full breakdown |
| Spending alerts | -- | Yes |
| CSV export (QuickBooks/Xero) | -- | Yes |
| Multi-currency support | -- | Yes |
| Weekly digest summaries | -- | Yes |
| Duplicate detection | Yes | Yes |
| Local-only data storage | Yes | Yes |

### Why Invoice Tracker?

- **Zero setup.** No accounts, no integrations, no onboarding flow. Start tracking in 10 seconds.
- **Plain English.** No forms, no dropdowns, no required fields. Just say what you spent.
- **Local-first.** Your financial data stays on your machine. Period.
- **Export-ready.** One command to generate a CSV your accountant can import into QuickBooks or Xero.
- **Smart categories.** Knows that AWS = Infrastructure, Figma = SaaS, Google Ads = Marketing. Auto-assigns, you override when needed.

### Reports That Actually Help

```
=== March 2026 Expense Report ===

By Category:
  Infrastructure    $2,340.00  (3 entries)
  SaaS              $1,287.50  (8 entries)
  Marketing         $5,000.00  (2 entries)
  TOTAL             $8,627.50  (13 entries)

vs Last Month: +12.3%

Top Vendors: Google Ads ($4K), AWS ($1.8K), Vercel ($540)
```

---

## Getting Started

1. Install the skill in OpenClaw
2. Say: "I paid $X to [vendor] on [date]"
3. That's it. You're tracking.

## Tags

`finance` `invoices` `expenses` `bookkeeping` `tracking` `reports` `csv` `quickbooks` `xero` `accounting` `ledger`

---

*Built by [@felipe_bmottaa](https://threads.net/@felipe_bmottaa) — because founders shouldn't need an accounting degree to track expenses.*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)