mechanic

---
name: mechanic
description: "Vehicle maintenance tracker and mechanic advisor. Tracks mileage, service intervals, fuel economy, costs, warranties, and recalls. Researches manufacturer schedules, estimates costs, projects service dates, tracks providers, and proactively reminds about upcoming/overdue services. Supports VIN decode and auto-population of vehicle specs, NHTSA recall monitoring, MPG tracking with anomaly detection, warranty expiration alerts, pre-trip/seasonal checklists, mileage projection, service provider history, tax deduction integration, emergency info cards, and cost-per-mile analysis. Use when discussing vehicle maintenance, oil changes, service intervals, mileage tracking, fuel economy, warranties, recalls, RV maintenance, roof sealing, generator service, slide-outs, winterization, or anything mechanic-related. Supports any vehicle type including trucks, cars, motorcycles, dirt bikes, ATVs, RVs, and boats."
homepage: https://github.com/ScotTFO/mechanic-skill
metadata: {"clawdbot":{"emoji":"🔧"}}
---

# Mechanic — Vehicle Maintenance Tracker

Track mileage and service intervals for any combination of vehicles — trucks, cars, motorcycles, RVs, dirt bikes, ATVs, boats, and more. Decodes VINs to auto-populate vehicle specs, researches manufacturer-recommended maintenance schedules, tracks service history, estimates costs, monitors recalls, tracks fuel economy, manages warranties, and proactively reminds about upcoming and overdue services.

## Data Storage

All user data lives in `<workspace>/data/mechanic/`:

| File | Purpose |
|------|---------|
| `state.json` | All vehicles: current mileage/hours, history, service records, fuel logs, warranties, providers, emergency info |
| `<key>-schedule.json` | Per-vehicle service schedule with intervals and cost estimates |

**Convention:** Skill logic lives in `<skill>/`, user data lives in `<workspace>/data/mechanic/`. This keeps data safe when the skill is updated or reinstalled.

## First-Time Setup

If `<workspace>/data/mechanic/state.json` doesn't exist:
1. Create `<workspace>/data/mechanic/` directory
2. Ask the user what vehicles they want to track
3. For each vehicle, run the **Adding a New Vehicle** workflow (includes choosing check-in frequency per vehicle)
4. Create `state.json` with the vehicle entries
5. Set up the cron job (see **Mileage Check Setup**)

### State File Structure
```json
{
  "settings": {
    "check_in_tz": "America/Phoenix"
  },
  "providers": [
    {
      "id": "jims_diesel",
      "name": "Jim's Diesel Repair",
      "location": "123 Main St, Mesa, AZ",
      "phone": "480-555-1234",
      "specialties": ["diesel", "trucks"],
      "rating": 5,
      "notes": "Great with Power Stroke engines"
    }
  ],
  "vehicles": {
    "f350": {
      "label": "2021 Ford F-350 6.7L Power Stroke",
      "schedule_file": "f350-schedule.json",
      "check_in_frequency": "monthly",
      "current_miles": 61450,
      "last_updated": "2026-01-26",
      "last_check_in": "2026-01-26",
      "vin": "1FT8W3BT0MED12345",
      "vin_data": {
        "decoded": true,
        "decoded_date": "2026-01-26",
        "year": 2021,
        "make": "Ford",
        "model": "F-350",
        "trim": "Lariat",
        "body_class": "Pickup",
        "drive_type": "4WD",
        "engine": "6.7L Power Stroke V8 Turbo Diesel",
        "displacement_l": 6.7,
        "cylinders": 8,
        "fuel_type": "Diesel",
        "transmission": "10-Speed Automatic",
        "doors": 4,
        "gvwr_class": "Class 3",
        "bed_length": "8 ft",
        "wheel_base": "176 in",
        "plant_country": "United States",
        "plant_city": "Louisville",
        "raw_response": {}
      },
      "business_use": false,
      "business_use_percent": 0,
      "mileage_history": [
        {"date": "2026-01-26", "miles": 61450, "source": "user_reported"}
      ],
      "service_history": [
        {
          "service_id": "oil_filter",
          "date": "2025-11-15",
          "miles": 58000,
          "hours": null,
          "notes": "Full synthetic Motorcraft FL-2051S",
          "actual_cost": 125.00,
          "provider": {
            "id": "jims_diesel",
            "name": "Jim's Diesel Repair",
            "parts_warranty_months": 12,
            "labor_warranty_months": 6
          }
        }
      ],
      "fuel_history": [
        {
          "date": "2026-01-20",
          "gallons": 32.5,
          "cost": 108.55,
          "odometer": 61300,
          "mpg": 14.2,
          "notes": "Regular fill-up"
        }
      ],
      "warranties": [
        {
          "type": "factory_powertrain",
          "provider": "Ford",
          "start_date": "2021-03-15",
          "end_date": "2026-03-15",
          "start_miles": 0,
          "end_miles": 60000,
          "coverage_details": "Engine, transmission, drivetrain components",
          "status": "active"
        }
      ],
      "recalls": {
        "last_checked": "2026-01-26",
        "open_recalls": [],
        "completed_recalls": []
      },
      "emergency_info": {
        "vin": "1FT8W3BT0MED12345",
        "insurance_provider": "State Farm",
        "policy_number": "SF-123456789",
        "roadside_assistance_phone": "1-800-555-1234",
        "tire_size_front": "275/70R18",
        "tire_size_rear": "275/70R18",
        "tire_pressure_front_psi": 65,
        "tire_pressure_rear_psi": 80,
        "oil_type": "15W-40 CK-4 Full Synthetic",
        "oil_capacity": "15 quarts",
        "coolant_type": "Motorcraft Orange VC-3DIL-B",
        "def_type": "API certified DEF",
        "tow_rating_lbs": 20000,
        "gvwr_lbs": 14000,
        "gcwr_lbs": 37000,
        "key_fob_battery": "CR2450",
        "fuel_type": "Diesel (Ultra Low Sulfur)",
        "fuel_tank_gallons": 48,
        "notes": ""
      }
    }
  },
  "last_service_review": "2026-01-26"
}
```

**Top-level fields:**
- `settings` — global settings (timezone, etc.)
- `providers` — reusable list of service providers
- `vehicles` — keyed by short slug (e.g., `f350`, `rv`, `crf450`)
- `last_service_review` — date of last full review

**Per-vehicle fields:**
- `label` — human-readable vehicle name
- `schedule_file` — path to the service schedule JSON
- `check_in_frequency` — how often to ask for mileage (weekly/biweekly/monthly/quarterly)
- `current_miles` / `current_hours` — latest known readings
- `last_updated` / `last_check_in` — date tracking
- `vin` — Vehicle Identification Number (for recalls, VIN decode, and emergency info)
- `vin_data` — decoded VIN data from NHTSA VPIC API (specs, engine, transmission, etc.)
- `business_use` — whether vehicle is used for business (boolean)
- `business_use_percent` — percentage of business use (0-100)
- `mileage_history` — chronological array of mileage/hours entries
- `service_history` — chronological array of completed services (with optional `actual_cost` and `provider`)
- `fuel_history` — chronological array of fuel fill-ups
- `warranties` — array of warranty records
- `recalls` — recall monitoring state (last checked, open/completed)
- `emergency_info` — quick-reference vehicle specs and emergency contacts

## Reading State

On skill load, read:
1. `<workspace>/data/mechanic/state.json` — current state for all vehicles
2. The relevant `<key>-schedule.json` file(s) depending on what's being discussed

## Adding a New Vehicle

When the user wants to track a new vehicle:

### 1. Gather Vehicle Info
**Ask for the VIN first.** If the user provides a VIN, run the **VIN Decode** (see below) to auto-populate year, make, model, engine, transmission, drive type, and other specs. This saves the user from answering questions you can look up automatically.

Ask for:
- **VIN** (strongly recommended — auto-populates specs, enables recall monitoring, emergency info)
- **Year, make, model** (only ask if no VIN provided)
- **Engine/trim** (only ask if no VIN or VIN decode was incomplete)
- **Usage pattern** — daily driver, towing, off-road, weekend toy, etc.
- **Current mileage/hours**
- **Business use?** — if yes, what percentage? (enables tax deduction tracking)
- **Warranty info** — any active factory or extended warranties? Expiration date/mileage?
- **Emergency info** — insurance provider, roadside assistance number, tire sizes (can be filled in later)

If the user doesn't have the VIN handy, proceed with manual info and note that VIN can be added later to unlock auto-population and recall monitoring.

### 2. Determine Duty Level
Ask about usage to classify the maintenance schedule:

| Usage | Duty Level | Effect |
|-------|-----------|--------|
| Normal commuting | Normal | Standard intervals |
| Towing, hauling | Severe | Shorter intervals (typically 50-75% of normal) |
| Off-road, dusty conditions | Severe | Shorter intervals, more frequent filter changes |
| Extreme temps (hot desert, harsh cold) | Severe | Shorter intervals, fluid/battery concerns |
| Track/racing | Severe+ | Aggressive intervals, specialized fluids |
| Light use, garage kept | Normal | Standard intervals, but watch time-based items |

Most manufacturers publish both "normal" and "severe/special conditions" schedules. Use the one that matches.

### 3. Choose Check-In Frequency
Ask how often they want to be asked about this vehicle's mileage/hours:

| Frequency | Best for |
|-----------|----------|
| **Weekly** | Dirt bikes, race vehicles, commercial/fleet, high-mileage daily drivers |
| **Every 2 weeks** | Active riders/drivers, vehicles with short service intervals |
| **Monthly** | Most cars and trucks (recommended default) |
| **Quarterly** | Seasonal vehicles, low-mileage, garage queens, stored boats |

Suggest a frequency based on the vehicle type and usage pattern, but let the user override.

### 4. Research the Service Schedule
**Look up manufacturer-recommended maintenance intervals** for that specific year/make/model/engine:
- Use web search to find the official maintenance schedule
- Check the owner's manual intervals
- 

... (truncated)