mechanic

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

{
  "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
• Cross-reference with enthusiast forums for real-world advice
• Factor in the duty level from step 2

5. Build the Schedule File

Create <workspace>/data/mechanic/<key>-schedule.json:

{
  "vehicle": {
    "year": 2021,
    "make": "Ford",
    "model": "F-350",
    "type": "truck",
    "engine": "6.7L Power Stroke V8 Turbo Diesel",
    "transmission": "10R140 10-Speed Automatic",
    "duty": "severe",
    "notes": "Tows fifth wheel RV"
  },
  "services": [
    {
      "id": "oil_filter",
      "name": "Engine Oil & Filter Change",
      "interval_miles": 7500,
      "interval_months": 6,
      "details": "Specific oil type, filter part number, capacity, and any special instructions.",
      "priority": "critical",
      "cost_diy": "$XX-XX",
      "cost_shop": "$XX-XX",
      "cost_dealer": "$XX-XX",
      "cost_note": "Optional note about related expensive repairs"
    }
  ]
}

Required for every service item:

• id — unique snake_case identifier
• name — human-readable name
• At least one interval: `i

---

Content truncated.