Vehicle Expense Tracker

Track vehicle expenses (gas, maintenance, parts) in Google Sheets and save related photos. Handles mileage, cost, category, and photo organization.

Security Scan

The skill's code and instructions are consistent with a vehicle expense tracker that writes to Google Sheets or local Excel and saves photos; no hidden network endpoints or unrelated credential requests were found.

Purpose & Capability

The name/description describe tracking vehicle expenses and the code implements that: parsing args, saving photos, appending rows to Google Sheets (via google auth) or writing local Excel files. The features requested in SKILL.md match the code behavior.

Instruction Scope

Runtime instructions are limited to running the provided Python script with appropriate flags. The script reads/writes only its config, locale files, user-supplied photo paths, and target spreadsheets/local Excel files — all expected for the stated functionality.

Install Mechanism

No install specification is provided (instruction-only with an included Python script). Nothing is downloaded or executed from external arbitrary URLs; risk is limited to running the included script locally.

Credentials

The skill declares no required env vars or credentials, which matches the package. It does, however, attempt to reuse a 'google-workspace' skill by appending ../google-workspace to sys.path and importing google_auth.get_service for Google Sheets access. That cross-skill dependency is referenced in SKILL.md but is not enforced in metadata — Google credentials would come from the separate google-workspace skill (proportionate to Sheets integration) and are not requested directly here.

Persistence & Privilege

always is false and the skill does not request persistent elevated privileges. It writes its own config (skills/vehicle-tracker/config.json) and user files under ~/vehicle_tracker (or custom paths) as expected; it does not modify other skills' configs or system-wide settings.

Assessment

This skill appears to do what it says: it writes expense rows to Google Sheets or local Excel and copies any photo file paths you pass to it into a photos folder (default ~/vehicle_tracker). Before installing/running: (1) Be aware it will copy files from paths you provide — only pass trusted photo paths. (2) For Google Sheets mode it reuses a 'google-workspace' skill (google_auth.get_service) — ensure you trust and have configured that skill/service-account credentials; the dependency is referenced in SKILL.md but not declared in metadata. (3) Local Excel mode requires openpyxl; if you don't want cloud access, omit spreadsheet IDs and use local mode. (4) If you want extra assurance, review the tracker.py source (it is included) and the google-workspace code it imports before use.

A multi-language vehicle expense tracking tool that supports Google Sheets and local Excel files.

Features

• i18n Support: Multiple languages via locale files (locales/*.json)
• Google Sheets Integration: Write directly to Google Sheets via API
• Local Excel Fallback: Saves to local .xlsx files if no Spreadsheet ID configured
• Metric/Imperial Units: Configurable unit system (km/L vs mi/gal)
• Photo Management: Auto-saves and renames photos with timestamps
• Aliases: Support vehicle aliases (e.g., "my car" → "Toyota Camry 2020")
• Defaults: Auto-fill quantity and unit based on category

---

🚀 Initialization (First-Time Setup)

Step 1: Choose Your Locale

Available locales:

• zh-TW - 繁體中文 (Taiwan)
• en-US - English (US)
• ja-JP - 日本語

Step 2: Create config.json

Copy the template below and save as skills/vehicle-tracker/config.json:

{
  "locale": "en-US",
  "unit_system": "metric",
  "vehicles": {},
  "aliases": {},
  "default_vehicle": null,
  "category_defaults": {}
}

Step 3: Copy Category Defaults from Locale

Based on your chosen locale and unit system, copy the appropriate category defaults.

For English (metric):

{
  "category_defaults": {
    "Gas": { "unit": "liter" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  }
}

For English (imperial):

{
  "category_defaults": {
    "Gas": { "unit": "gallon" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  }
}

For 繁體中文 (metric):

{
  "category_defaults": {
    "加油": { "unit": "公升" },
    "周邊": { "unit": "個", "quantity": 1 },
    "維修": { "unit": "件", "quantity": 1 },
    "保養": { "unit": "次", "quantity": 1 },
    "買車": { "unit": "輛", "quantity": 1 }
  }
}

For 日本語 (metric):

{
  "category_defaults": {
    "給油": { "unit": "リットル" },
    "アクセサリー": { "unit": "個", "quantity": 1 },
    "修理": { "unit": "件", "quantity": 1 },
    "メンテナンス": { "unit": "回", "quantity": 1 },
    "購入": { "unit": "台", "quantity": 1 }
  }
}

Step 4: Add Your Vehicle

Option A: Google Sheets (recommended for cloud sync)

1. Create a Google Spreadsheet
2. Share it with a Google Service Account (see google-workspace skill)
3. Add the Spreadsheet ID to config:

{
  "vehicles": {
    "My Car 2020": "1ABC123...xyz"
  },
  "default_vehicle": "My Car 2020"
}

Option B: Local Excel (no setup required)

Just add the vehicle name without an ID:

{
  "vehicles": {
    "My Car 2020": null
  },
  "default_vehicle": "My Car 2020"
}

Files will be saved to ~/vehicle_tracker/My_Car_2020.xlsx.

Step 5: Add Aliases (Optional)

{
  "aliases": {
    "car": "My Car 2020",
    "toyota": "My Car 2020"
  }
}

Step 6: Custom Paths (Optional)

Override default directories:

{
  "photo_base_dir": "/path/to/photos",
  "local_excel_dir": "/path/to/excel/files",
  "sheet_name": "Expenses"
}

Default paths: ~/vehicle_tracker

---

Complete config.json Example

{
  "locale": "en-US",
  "unit_system": "imperial",
  "vehicles": {
    "Toyota Camry 2020": "1ABC123...spreadsheet_id",
    "Honda Civic 2018": null
  },
  "aliases": {
    "camry": "Toyota Camry 2020",
    "civic": "Honda Civic 2018",
    "car": "Toyota Camry 2020"
  },
  "default_vehicle": "Toyota Camry 2020",
  "category_defaults": {
    "Gas": { "unit": "gallon" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  },
  "photo_base_dir": "~/vehicle_tracker",
  "local_excel_dir": "~/vehicle_tracker"
}

---

Usage

Preview (Dry Run) - Always do this first!

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15000 \
  --category "Gas" \
  --cost 45.50 \
  --quantity 12.5 \
  --dry-run

Execute (After user confirms)

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15000 \
  --category "Gas" \
  --cost 45.50 \
  --quantity 12.5

With Photos

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15200 \
  --category "Maintenance" \
  --cost 89.99 \
  --description "Oil change" \
  --photos "/path/to/receipt.jpg" \
  --dry-run

---

Arguments

Argument	Required	Description
--vehicle	Optional	Vehicle name or alias. Uses default if omitted.
--mileage	Required	Current odometer reading
--category	Required	Expense category
--cost	Required	Expense amount (currency symbols auto-removed)
--quantity	Optional	Quantity (uses default if available)
--unit	Optional	Unit (uses category mapping if available)
--date	Optional	Date YYYY-MM-DD (defaults to today)
--description	Optional	Additional notes
--photos	Optional	Photo file paths to save
--dry-run	Flag	Preview only, no write

---

Adding a New Locale

Create locales/{code}.json based on existing locale files. Required fields:

• language_name
• sheet_name
• columns_metric / columns_imperial
• photo_prefix
• messages
• units_metric / units_imperial
• default_units_metric / default_units_imperial

---

Supported Locales

Code	Language	Unit Systems
zh-TW	繁體中文	metric, imperial
en-US	English (US)	metric, imperial
ja-JP	日本語	metric, imperial