---
name: car-finder
description: Search for any used or new car near a given zip code using the Auto.dev listings API. Filter by make, model, year, price, mileage, fuel type, and radius. Score and rank results. Activate when the user asks to find a car, search listings, look up vehicles, or check what cars are available near them.
license: MIT
metadata:
  author: Jonathan Ibrahim
  version: "1.0"
  homepage: https://github.com/CreateJonathanIbrahim/openclaw-car-finder-skill
requires:
  env:
    - AUTODEV_API_KEY
---

# Car Finder Skill

Search any US car listing database for vehicles matching the
user's criteria. Works for any make, model, year, fuel type,
price range, or condition. Returns a scored, ranked list of
the best matches near the user's location.

## When to Use This Skill

Activate when the user says any of:
- "find me a car"
- "search for a [make/model]"
- "what cars are available near me"
- "look up used [vehicle type] near [location]"
- "car finder"
- "run a car search"
- "show me listings for [vehicle]"

## Step 1: Gather Parameters

Before searching, ask the user for any missing information:

- **Zip code** (required — no default)
- **Search radius** (default: 50 miles)
- **Make** (optional — leave blank for all makes)
- **Model** (optional — leave blank for all models)
- **Year range** (optional — example: 2018-2024)
- **Max price** (optional — example: 20000)
- **Max mileage** (optional — example: 80000)
- **Fuel type** (optional — gas, hybrid, electric, diesel)
- **New or used** (default: used)
- **Condition** (optional — excellent, good, fair)

If the user has already provided some or all of these in their
request, do not ask again. Use what they gave you and proceed.

## Step 2: Build the API Call

Base URL: https://api.auto.dev/listings

Auth header: Authorization: Bearer $AUTODEV_API_KEY

Build query parameters from what the user provided:
retailListing.zip = [user zip]
retailListing.radius = [radius, default 50]
retailListing.price = 1-[max price] (omit if not specified)
retailListing.mileage.max = [max mileage] (omit if not specified)
retailListing.isNew = false (set to true if user wants new cars)
vehicle.make = [make] (omit if not specified)
vehicle.model = [model] (omit if not specified)
vehicle.year = [year range] (omit if not specified)
vehicle.fuel = [fuel type] (omit if not specified)

Example curl for a used Honda Civic under $15,000 within
75 miles of Austin TX:

```bash
curl -s -X GET \
  "https://api.auto.dev/listings?retailListing.zip=78701&retailListing.radius=75&retailListing.isNew=false&vehicle.make=Honda&vehicle.model=Civic&retailListing.price=1-15000" \
  -H "Authorization: Bearer $AUTODEV_API_KEY"
```

Example curl for any car near a zip code with no filters:

```bash
curl -s -X GET \
  "https://api.auto.dev/listings?retailListing.zip=USER_ZIP&retailListing.radius=50&retailListing.isNew=false" \
  -H "Authorization: Bearer $AUTODEV_API_KEY"
```

Run the curl command with the parameters the user provided.
If the result set is empty, broaden one parameter at a time
and try again. First expand radius, then relax price or mileage.

## Step 3: Score Each Result

Score every listing returned out of 100 points total.
Scoring adapts based on what the user told you they care about.
If the user mentioned a specific priority (low mileage, low price,
specific brand), weight that category more heavily in your summary.

### Year (25 pts)
- Current year or last year: 25
- 2-3 years old: 20
- 4-5 years old: 15
- 6-8 years old: 10
- Older than 8 years: 5

### Mileage (25 pts)
- Under 20,000: 25
- 20,000-40,000: 20
- 40,000-60,000: 15
- 60,000-80,000: 10
- 80,000-100,000: 5
- Over 100,000: 0

### Price vs Market (25 pts)
Compare the listing price against similar vehicles in the results.
- Priced more than 15% below average: 25
- Priced 5-15% below average: 20
- Priced within 5% of average: 15
- Priced 5-15% above average: 8
- Priced more than 15% above average: 3

### Listed Condition (15 pts)
- Excellent: 15
- Good: 11
- Fair: 6
- Not listed or unknown: 3

### Deal Rating from API (10 pts)
If Auto.dev returns a deal rating field, use it:
- Great Deal: 10
- Good Deal: 7
- Fair Deal: 4
- No rating: 2

## Step 4: Output

Present the top 10 results ranked by score as a table:

| Rank | Score | Year/Make/Model | Price | Mileage | Distance | Link |
|------|-------|-----------------|-------|---------|----------|------|

After the table write 3 lines:
1. Recommend the top pick and why it scored highest
2. Flag any result that looks unusually cheap for its mileage
   and year (potential deal worth investigating further)
3. If no results were returned, tell the user which parameter
   to relax first and offer to run the search again

## Notes

- Always show the listing URL so the user can click directly
  to the listing
- If the API returns more than 10 results, score all of them
  and show only the top 10
- If the user asks to refine (lower price, different make, etc.)
  rebuild the parameters and run a new search immediately
- Never make up listings. Only show what the API returns.