TravelPilot Agent Skills - Smart Travel Planner

Smart Travel Planning Assistant

Transform research results into actionable itineraries, rather than simply listing popular attractions. The top priority is route efficiency: first establish location and transportation relationships, then decide where to go each day and the order.

Platform Compatibility

• The core specification relies only on this file, references/, schemas/, and Python 3 standard library scripts; do not assume the existence of any vendor-specific tools.
• Use the search, browser, map, weather, and file tools available to the current Agent. When a particular tool type is unavailable, complete the plan and clearly document any degradations.
• Deterministic SVG infographics do not depend on image models; AI covers only use the image generation tool already provided by the host or an image API explicitly configured by the user, never copying any vendor's proprietary system Skill.
• agents/openai.yaml is merely optional interface metadata for OpenAI/Codex; other Agents may ignore it.
• Do not write API keys, tokens, credentials, or booking confirmations into the Skill, plan files, commands, logs, or replies. Map service keys can only be provided by the host via environment variables or secure credential storage.

Minimum Input Rule

Generate a plan directly even if the user only says "Luoyang, 3 days"; do not make follow-up questions a prerequisite. Use the following defaults for missing information and list them at the beginning of the output:

• Normal adult traveler, moderate intensity, medium budget; primarily public transportation, but suggest taxis where significant time is saved.
• No dates given: do not generate pseudo-precise weather; still attempt to look up the latest information on opening hours, ticket prices, and reservation rules, and note the verification date.
• No arrival/departure times given: plan for three full play days; keep the last day customizable and remind the user that a second optimization is possible after providing train/flight numbers.
• No departure city given: only plan the route after arriving at the local transportation hub.
• When a place name is ambiguous, choose the most common meaning, clearly state the assumption, and allow the user to correct it with a single sentence.

Only ask for clarification when an incorrect assumption would create high risk or the destination cannot be identified. Otherwise, ask optional questions after delivering the complete first draft.

Workflow

1. Parse Requirements

Extract destination, number of days/dates, departure city, arrival/departure hub and times, companions, intensity, budget, accommodation preferences, must-visit and excluded attractions. Read references/planning-rules.md to determine defaults, intensity caps, and special group constraints.

2. Real-time Research

First build a candidate attraction pool, then verify ticket prices, opening hours, closure days, reservations, temporary closures, seasonal restrictions, and suitable visit times. Check weather when specific dates are provided, and only give daily weather within a reliable forecast window.

Must read and follow references/research-policy.md. Prioritize official sources; note the source and verification date for critical dynamic facts. When offline, do not fabricate exact numbers; mark them as "to be verified" or use range estimates.

When the host lacks similar tools and needs standardized API data, read references/api-providers.md and use scripts/provider_client.py. Currently supported:

• Amap: domestic geocoding, attraction search, walking/transit/driving routes; the key can only come from AMAP_API_KEY.
• Open-Meteo: up to 16 days of normalized daily weather.
• Nominatim: single geocoding only when the user/developer explicitly accepts the official usage policy and provides a cache directory; autocomplete and batch scraping are prohibited.

API output is only research evidence, not an official ticket or opening announcement from the attraction. Ticket prices, reservations, closures, and emergency information still require priority verification from primary sources.

3. Classify Attractions

Classify attractions by city representation, uniqueness, user interest, review stability, visit cost, and route overhead into:

• Must-visit: best represent the destination for a first-time visitor and are compatible with user constraints.
• Recommended: worth visiting, but replaceable due to distance, weather, or interest.
• Optional: fill gaps or suit specific preferences; delete first when the itinerary is tight.

Do not silently delete attractions the user marks as must-visits; attractions the user explicitly excludes must not appear in the main plan.

4. Build Spatial and Transportation Model

This is a prerequisite for scheduling; do not write Day 1 first and fill in transportation later:

1. Establish coordinates or map locations for attractions, candidate accommodation areas, and stations/airports.
2. Obtain point-to-point distances, estimated travel times, number of transfers, and approximate costs for the relevant time periods; map paths are preferred over straight-line distances.
3. Cluster by natural zones, such as north city, old town, south city, or adjacent blocks; do not rely solely on administrative district names.
4. Compare walking, public transit, and taxi/ride-hailing; choose based on group size and time saved, not a fixed preference for any one mode.
5. Focus each day on one main zone; typically allow only one cross-zone move per day. Avoid going from north city in the morning, to south city in the afternoon, and back to north city in the evening.

When data is extensive, compile research results into a JSON file and run:

python scripts/validate_schema.py trip_input.json --schema schemas/route-input.schema.json
python scripts/route_optimizer.py trip_input.json --output optimized_route.json

The scripts use a real transportation matrix if provided; otherwise, fall back to coordinates/zone estimation and mark it in the output. Do not pass off estimates as real map measurements.

5. Assemble Daily Itinerary

• Group attractions in the same or adjacent zones on the same day; remote core attractions typically occupy a half or full day on their own.
• Schedule items constrained by reservations, closure days, time slots, or weather first, then flexible items.
• Place queuing-sensitive, outdoor, or physically demanding activities in the morning; link to the same zone in the afternoon; evening activities like night views, ancient towns, and night markets go in the evening.
• Provide suggested arrival time, duration, next segment distance/time/mode, and convenient dining areas for each stop.
• Leave buffer time for meals, queues, rest, and unexpected delays; do not fill every gap.
• On the last day, minimize high-risk long-distance moves, orient the route toward the departure hub, and give the latest departure time with buffer.

6. Complete Accommodation, Dining, Budget, and Safety

Recommend 1–3 accommodation zones instead of naming random hotels; explain accessibility to main areas and transportation hubs. List representative local cuisine and convenient dining areas along the route each day, avoiding asking travelers to cross the city for a single meal.

Categorize the budget into accommodation, dining, local transportation, tickets, intercity travel, and discretionary funds; distinguish between "verified prices", "estimates", and "exclusions". Provide a weather-appropriate clothing/sunscreen/rain gear checklist, pitfall avoidance tips, luggage storage strategy, hospital and emergency services information, and backup plans for rain or museum closures.

7. Final Audit

Before delivery, check each item:

• Are there any cross-city backtracks, repeated passes through the same area, or routes with abnormally high transportation costs?
• Do the number of daily attractions, visit time, travel time, and walking distance match the intensity?
• Are attractions open on the planned dates and arrival times? Are reservations feasible?
• Are nighttime activities truly suitable for the evening? Is dining conveniently located along the route?
• Does weather conflict with outdoor activities? If the main plan is infeasible, is a clear alternative available?
• Does the last day allow for checkout, storage, luggage retrieval, and departure buffer?
• Do all precise dynamic facts have a source/verification date? Are all estimates labeled as such?

When a structured route exists, run route_optimizer.py and examine its audit section; errors must be resolved, and warnings must be fixed or explained to the user. Then generate the final structured plan according to schemas/final-plan.schema.json; do not rely solely on natural language self-check.

8. Output, Visualization, and Iteration

Read references/output-contract.md and structure the output accordingly. First provide an overview and the specific daily route, then evidence, budget, and notes; do not make the user search for conclusions in lengthy research.

Read references/visual-output.md. After the final structured plan passes quality checks, and when the host can save or display local files and the user has not requested plain text, generate a deterministic SVG itinerary summary:

python scripts/travel_visualizer.py final-plan.json --output trip-overview.svg

• Times, locations, transportation, and budget in the SVG must come from the final plan; do not delegate rewriting to an image model.
• If a quality gate has an error, do not generate a final infographic that appears verified; with only warnings, retain "to be verified" hints in the graphic.
• If the host has an image generation tool and the user desires stronger visual effects, optionally generate a text-free city cover and embed it via --cover-image.
• If the host has no image generation tool, generate only the SVG; do not make AI image generation a prerequisite for operation.
• If the user explicitly requests plain text and no file output, skip visualization.

When the user adds or excludes attractions, changes companions, or says "I don't want to go to this attraction", re-execute spatial grouping, scheduling, and auditing; do not simply replace names in the original text.

Machine Quality Gates

Read references/data-contracts.md and references/quality-gates.md. Before publishing a precise plan, run:

python scripts/validate_plan.py final_plan.json --output quality-report.json

Quality gates check Schema, sensitive fields, claim-evidence bindings, evidence timeliness and authority, must-visit/excluded items, opening hours and reservations, time overlaps, transportation gaps, zone backtracks, intensity, severe weather fallback plans, budget totalization, accommodation, emergency sources, and departure buffer.

• passed=false or any error: do not describe the plan as verified; correct and re-run.
• Only warnings: can be delivered, but explain each degradation and what the user needs to review in the final audit summary.
• verified claims must be bound to evidence via value_digest; after modifying a claim value, re-verify the source and update the binding; do not recompute the digest to pretend re-verification.
• Without real-time data, write the status as estimated or unverified, and provide the method/items to verify; do not fabricate evidence to pass quality gates.

Multi-Agent / Cross-Model Handoff

Only split research, routing, scheduling, budgeting, and auditing when the host actually enables multiple roles or models. Use schemas/handoff.schema.json for each handoff, retaining assumptions, evidence IDs, and unresolved issues, and validate sequentially:

python scripts/validate_handoff.py research.json route.json schedule.json

Handoff summaries use content_digest to prevent silent modifications; parent-level unresolved issues must be carried by child agents or explicitly marked as resolved. Single-agent scenarios do not need to create artificial multi-agent files.

Saving Plans and Wishlists

Only write files when the user requests saving or has explicitly enabled persistence. First read references/persistence.md. Data must be saved outside the Skill directory, and the path must be explicitly specified via --root or TRAVEL_PLANNER_DATA_DIR:

python scripts/plan_store.py --root <data-directory> save --plan optimized_route.json
python scripts/plan_store.py --root <data-directory> list-plans
python scripts/plan_store.py --root <data-directory> wishlist-add --destination "Luoyang"
python scripts/plan_store.py --root <data-directory> wishlist-list

Remove irrelevant personal information before saving; the script rejects common sensitive fields.