Compare FlightsCAUTION

AI-powered travel hacking and search with cash, points, miles, and award flights. Drop-in skills and MCP servers for Claude, Codex, and OpenCode.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: compare-flights
description: Unified flight comparison across cash (Duffel, Ignav), award (seats.aero), and portal (Chase, Amex) sources in parallel. Outputs one table with transfer partner optimization and recommendations.
category: orchestration
summary: Unified flight comparison across ALL sources in parallel. Auto-applies transfer optimization.
api_key: Uses individual skill keys
---

# Compare Flights

Search every available source for a route and present one unified comparison. Combines cash pricing, award availability, portal pay-with-points, and transfer partner optimization into a single table.

**This is an orchestration skill.** It tells the agent which tools to run and how to combine results. No standalone script.

**Companion reference skills.** Load these for deeper context:
- `flight-search-strategy` — full source priority, market selection, source accuracy hierarchy
- `points-valuations` — CPP rules, floor/ceiling, surcharge programs, transfer bonuses
- `partner-awards` — alliance + bilateral partnership reachability
- `lessons-learned` — Seats.aero workflow, Southwest specifics, Companion Pass math
- `fallback-and-resilience` — what to do when a source fails
- `transfer-bonuses` — current active transfer bonuses (live data); changes effective ratios when computing options 4-7 of the comparison table
- `stopovers` — when an itinerary has a long layover or multi-city, check if a stopover-allowing program priced lower than separate one-ways
- `round-the-world` — for 3+ stop multi-region itineraries, RTW products may beat sum-of-parts award pricing
- `award-holds` — many major Western programs (UA, Aeroplan, AS, DL, BA, ANA, Qatar, Korean) no longer offer holds. Some still do: AA (24h online), Lufthansa M&M (5 days), Flying Blue (3 days, $25 phone fee), Cathay (2 days, $39 fee), Turkish (2 days), Virgin Atlantic (1-2 days, free phone), Singapore (agent discretionary). Affects whether the recommended path is "transfer first then ticket" or "ticket immediately"
- `status-match` — when comparing options that include upgrades or elite-only benefits (lounge access, free bags, priority); status changes the real cost of a flight

## When to Use

- "Find me the best way to get from SFO to CDG in August"
- "Should I pay cash or use points for this flight?"
- "Compare all options for SFO to NRT business class"
- Any flight search where the user wants the full picture

## Sources

Run these in parallel where possible. **Never fail silently.** If a source errors, report it in the output so the user knows what's missing.

### Cash Prices (run in parallel)

| Source | Skill | Speed | Notes |
|--------|-------|-------|-------|
| Duffel | `duffel` | ~3s | Primary. Real GDS fares with fare classes. No Southwest. |
| Ignav | `ignav` | ~2s | Fast REST API. Good for price comparison. Booking links. |
| Google Flights | `google-flights` | ~10s | Browser-automated. All airlines including Southwest cash. Good cross-check. |
| Skiplagged | web search | ~5s | Hidden city ticketing. Often finds significantly cheaper fares. Search `skiplagged.com/flights/{origin}/{dest}/{date}`. |
| Kiwi.com | web search | ~5s | Creative routings, self-transfer combos, multi-city. Search `kiwi.com`. |
| Southwest | `southwest` | ~20s | Patchright, Docker only. Points + cash for all 4 fare classes. Only needed when SW flies the route. |

**Skiplagged and Kiwi:** Use web search (tavily or exa) to find their prices. They don't have MCP skills but their URLs are predictable. Always note that Skiplagged fares have restrictions (can't check bags, must use the "missed" connection city as destination).

**Southwest:** Run the `southwest` skill if SW flies the route. Include SW Rapid Rewards points in the comparison table as a separate currency. The `lessons-learned` skill has the full details on SW specifics (fare class requirements, Companion Pass math, GDS gap).

**SerpAPI is optional.** Only use if the user asks for Google Hotels or destination discovery.

### Award Availability

| Source | Skill | Speed | Notes |
|--------|-------|-------|-------|
| Seats.aero | `seats-aero` | ~5s | Cached award availability across 25+ programs. Primary award source. |

### Portal Pay-With-Points (run in parallel, Docker required)

| Source | Skill | Speed | Notes |
|--------|-------|-------|-------|
| Chase UR | `chase-travel` | ~45s | Dynamic Points Boost pricing (~1.5-2.0 cpp on select bookings, not a guaranteed floor). |
| Amex MR | `amex-travel` | ~45s | IAP discount detection on Platinum. |

Portal searches are slower (require browser login). Run them in parallel with each other, but don't block on them. Start cash + award searches first, present those results, then append portal results when ready.

**Only run portal searches if the user has the relevant card or asks for portal pricing.** Don't run Chase if they don't have a Sapphire card.

## Workflow

### Step 1: Gather All Prices

Run searches in parallel. Track which sources succeeded and which failed.

```
PARALLEL GROUP 1 (fast, ~3-5s):
  - Duffel: cash prices with fare classes
  - Ignav: cash prices with booking links
  - Seats.aero: award availability by program
  - Skiplagged: hidden city fares (web search)
  - Kiwi.com: creative routings (web search)

PARALLEL GROUP 2 (browser-automated, ~10-45s, Docker):
  - Google Flights: all airlines including Southwest cash
  - Southwest: points + cash for all fare classes (if SW flies the route)
  - Chase Travel: UR portal pricing + Points Boost
  - Amex Travel: MR portal pricing + IAP discounts
```

For each source, capture:
- Source name
- Status: "ok" | "error: {reason}" | "skipped: {reason}"
- Results count
- Data

### Step 2: Apply Transfer Partner Optimization

For every seats.aero award result, calculate the effective cost in each transferable currency using `data/transfer-partners.json`:

```
For each award (e.g., United business at 88,000 miles):
  1. Look up which currencies transfer to United: Chase UR (1:1), Bi

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills

.claude/skills

.opencode/skills

skills

AGENTS.md

Gates applied: no_behavioural_pass.