flight-booking-ai skill | PlugMCP

Airport lookup (/skill/flight/v1/search_airports) is public. Flight search allows an omitted token; authenticate before offer verification, booking creation, order query, payment creation, or payment query.
Resolve and validate the complete search request before searching: departure and arrival cities or airports, every travel date, cabin, flight preference, and adult/child/infant counts. If a departure or arrival is only a country, do not use the country as an airport-lookup or flight-search location; ask the user for the actual city or airport first. Before every flight-search request, obtain the current date in the user's timezone and validate every leg's departure date locally; do not send invalid dates to the API to discover the error. If the user's timezone cannot be determined reliably, ask for it before resolving or validating dates; do not substitute the server/system timezone. Resolve relative dates in that timezone and disclose their YYYY-MM-DD values before searching. Accept valid calendar dates from today through one calendar year after today, inclusive (today <= departure_date <= latest_date). Today's flights are allowed: compare calendar dates, not a date's midnight against the current clock time. Reject dates before today, dates after the upper boundary, invalid calendar dates, and decreasing leg dates before calling flight search. If any leg fails, stop the whole search, identify the offending leg/date and the allowed date range in natural language, and ask for a corrected date; do not silently move it to today, next year, or another date. Revalidate when dates change and before each new search, including across local midnight. Use airport lookup for city names, airport names, or ambiguous codes. Obtain search_airports data before presenting or using a route endpoint: city and airport options, names, and codes must come from that endpoint's returned data. Without returned data, ask only whether the user accepts any airport or wants a specified airport; do not infer or list options, names, or codes from memory. If the user accepts any airport in a city, use that result's city_code in the flight-search leg; if the user specifies an airport, use that airport's airport_code. Never guess a materially ambiguous airport; present the choices. Explicitly confirm the adults, children, and infants—even when a count is zero—before the first search.
Search flights live; never cache or reuse a flight-search response for a later search. Set flight_type from the user's preference: direct for direct-only, transfer for transfer-only, or all when the user has no preference. Record the current search definition and the time the successful response was received. If the user changes any route, airport, travel date, cabin, flight preference, or passenger count, immediately discard all prior quotation-number mappings, offers, and verified sessions. A passenger-count change also invalidates verification and booking because all later passenger counts and types must remain identical to the confirmed search. Obtain the user's explicit instruction before running the required new search. An empty offers list or zero quotations is a normal successful result: use the no-offers variant in the flight-offer results template and do not automatically retry or adjust criteria. Any repeat search after an empty result requires the user's approval.

The API returns matching offers by total price ascending; preserve that order. Show the first 10 by default and continue in that order on request. Use the flight-offer results template with exactly these canonical columns in this order: Offer | Flight | Departure–arrival (airport local time) | Departure terminal | Cabin | Checked baggage | Total. Translate the user-facing labels. Use a visible sequential quotation number so the user can select an offer, while retaining its offer_id only internally. Never display offer_id or any non-public supplier payload or internal identifier.

Keep the local-time explanation in the departure–arrival column header. Do not append a separate local-time reminder after the table, including on later pages.

Every displayed offer, including the initial results and later pages, must include each segment's returned departure time, arrival time, and cabin class. Match these values to the flight number from the same segments item; never combine one segment's times with another segment's cabin, omit them for brevity, or defer them until the user selects a quotation.

Use one row per offer and these cell contracts:
- Flight: for every segment, show the marketing airline's full official name followed by the complete marketing flight number, for example Vietnam Airlines (VN595). Never use a colloquial or shortened airline name. Build the flight number from airline plus flight_no when flight_no does not already include the carrier code; do not duplicate the code. If the full official airline name cannot be resolved reliably, omit the name and retain the returned carrier code and flight number rather than inventing or using an abbreviation.
- Departure–arrival (airport local time): for every segment, show departure_time, departure airport three-letter code and airport name, followed by arrival_time, arrival airport three-letter code and airport name from that same segment. Preserve returned dates for overnight or cross-date travel so the arrival day is clear; preserve any returned timezone information and do not invent a timezone or date that the response does not establish. Prefer the airport name matching the user's language. Use airport names returned by search_airports; resolve every unique segment airport code, including transfer airports, before rendering. If airport lookup returns no matching name, omit the name while retaining any returned time and airport code.
- Departure terminal: show only the segment's DepTerminal (departure_terminal). Do not show ArrTerminal (arrival_terminal) in this column. If the departure terminal is blank, leave this cell or the corresponding segment line empty.
- Cabin: display each segment's own returned CabinClass (cabin_class) as a translated cabin-class name. Do not substitute the requested search cabin for the returned cabin; mixed-cabin itineraries must show the actual cabin for every segment. Map Y to Economy, C to Business, and F to First, then translate those labels into the response language. Do not display CabinCode (cabin_code) or the raw CabinClass code. If CabinClass is blank, leave this cell or the corresponding segment line empty.
- Checked baggage: summarize only returned checked-baggage rules; distinguish passenger types or segments when their allowances differ. If no checked-baggage rule is returned, leave this cell empty; do not interpret missing data as no baggage allowance.
- Total: show the returned total price and currency together.
For any search-table value that is not returned or cannot be resolved reliably, leave the corresponding cell or segment portion empty. Do not insert placeholders such as Not returned, -, Unknown, or None. When an itinerary has a transfer, put each segment on its own line inside the flight, departure–arrival, departure-terminal, and cabin cells using <br>, and keep segment order aligned across those cells. Label every journey consistently: use Outbound and Return for a round trip, and Trip 1, Trip 2, and so on for a multi-city itinerary, then translate those labels. Prefix every segment line with its journey label so transfers remain unambiguous. Do not add table columns; provide extra details only after the user selects an offer or explicitly asks for them.
A quotation is valid for verification only during the 20 minutes immediately after its successful search response. Before verification, first apply the token-change check and refresh-and-reselection flow above; only a quotation selected from the current credential generation is eligible. Then confirm that the selected quotation belongs to the unchanged current search, is less than 20 minutes old, and uses exactly the confirmed adult, child, and infant counts and passenger types. At 20 minutes or later, do not verify it: discard the expired quotations and any related session, explain that a new search is required, and obtain the user's approval before searching again. When a valid quotation is selected, verify it with the identical counts. The returned offer, price, currency, and session are authoritative. Use the offer verification result template and report only whether the price changed using price_changed, together with the verified total and currency. Ignore rule_changed entirely. Selection authorizes verification, not booking.
Before collecting booking data, read passenger details and confirmation, then use the passenger and contact collection template. Require type, first_name, last_name, birthday, sex, nationality, and all four document fields (card_type, card_no, card_expired, card_issue_place) even when support_no_card=true. That flag is an API capability, not permission to omit documents in this Skill's booking flow. Check age against the travel date: adult is 12 years or older, child is 2 to under 12 years, infant is 14 days to under 2 years. Compare actual passenger counts and types with the search and verification before proceeding. On a mismatch, invalidate old quotations, sessions, and confirmation and use the passenger-composition requotation template. Never change a child or infant into an adult, omit a passenger, or invent an accompanying adult to reuse a price. If any required passenger or contact value is absent or invalid, do not call booking; request the missing or corrected fields together. Do not collect or send ancillary items.
After passenger data is complete, use the booking confirmation template to present the verified itinerary, verified total and currency, price-change notice, and complete booking review. Show every passenger's first_name and last_name separately as First name (given name) and Last name (surname); a combined name alone is insufficient. Show the other required passenger, document, and contact fields in full as defined by the template. Do not include rule-change notices or fare-rule details. Require explicit confirmation immediately before creating a booking. Any passenger or contact correction cancels the prior confirmation and requires the complete updated template and a new explicit confirmation.
Call booking once with the verified session. Only on a successful response, use the booking creation result template with the returned order_no, status, total_price, currency, price_changed, and final offer. Report status exactly as returned; do not infer payment or ticket issuance. On a failed or ambiguous response, use the failure templates instead of a success summary.
When the user provides or has just created an order_no, query the order before offering payment methods or creating a payment. Use the order query result template and report returned fields and statuses exactly. Do not create payment from a guessed, transformed, or unqueried order number.

Apply a strict payable-order allowlist to that successful, immediately preceding order query. Continue only when status is exactly booking_successful, paid_at and ticketed_at are absent, tickets is empty, and any returned payment_deadline is reliably interpretable and strictly later than the current time. An absent deadline alone does not block payment. Every other status is nonpayable, including pending_confirmation, payment_successful, ticketing, payment_failed, ticket_issued, ticketing_failed, cancelled, creation_failed, and unknown. Any populated paid/ticketed evidence overrides an otherwise payable status. A returned deadline that has passed, equals the current time, or cannot be interpreted reliably also blocks payment. In every blocked case, use the payment-unavailable template; do not offer a payment method, request payment confirmation, or call payment creation. Never infer that a failed or unfamiliar status is retryable. When a customer with an existing order asks about next steps, ticket issuance, or when tickets will be issued, use a current successful order query to determine the next action. If the order is booking_successful and remains payable, explain that payment is the next step before ticketing and actively guide the customer into the payment-method selection/review flow below. Use the payment-before-ticketing notice, then follow payment guidance for ticketing questions. Do not treat this informational question as an unsupported ticketing action or merely refer the customer to support. Already-paid or ticketed evidence, a nonpayable status, or an expired/invalid deadline requires status guidance instead of another payment request. The question alone does not authorize payment creation.
For an eligible order, use the payment-method selection template and show only public payment names. Stripe is available for any valid returned currency. WeChat Pay, Alipay, and Online Banking are available only when the returned order currency is exactly CNY; otherwise offer only Stripe and explain the currency constraint. Map the selected public name to the documented request-only API value internally. Never show the API value, a payment-provider implementation name, or a numeric upstream code to the user. Do not ask the user for a payment return URL or send one; the service supplies it.

Whenever Stripe is offered, place the complete processing-fee reminder from the payment-method selection template directly below the payment-method list, including after a newly created order. It must disclose the 3.5% rate, that the fee is non-refundable on refund or cancellation, and that the returned fee and payable total will be shown after payment initiation.

When Stripe is selected, calculate the fee from the latest queried flight order total using decimal arithmetic: processing_fee = round_half_up(total_price * 0.035, 2); payable_total = total_price + processing_fee. Display the order total, numeric fee, and numeric payable total in the order currency with exactly two decimal places before requesting payment confirmation. Follow the fee calculation rules, including authoritative-breakdown precedence. Identify local figures as a pre-payment calculation. The separate Stripe processing fee is non-refundable once charged, including on refund or cancellation. It applies only to Stripe. Do not send these calculated amounts to the API or add the fee again to a returned payment amount.

After the method is selected, use the payment confirmation template. Present every segment's flight number and departure/arrival times, route/dates/transfer relationships, complete passenger names/types/counts, selected payment method, exact flight order total/currency, and the returned payment deadline. For Stripe, also render the template's Stripe fee-acknowledgement block. Base order/itinerary/payment facts on the immediately preceding order query. Show available sensitive passenger/document/contact values in full without masking so the customer can check them; passenger details defines how to use previously confirmed data for this same order when the query omits it. Never guess missing values.

Require an explicit second confirmation of the complete payment review immediately before creating the payment. This payment confirmation is separate from and cannot be satisfied by the earlier booking confirmation, the payment-method selection, or a request to act quickly. When Stripe is selected, the confirmation must explicitly acknowledge the 3.5% processing fee, its numeric amount, the numeric payable total, and its non-refundable nature. If the reviewed order, payment method, flight order total, calculated or returned Stripe fee/payable amounts, or available passenger/contact information changes, show the complete updated tables and obtain a new confirmation. Switching to or from Stripe always invalidates the prior confirmation. Passenger corrections for an existing order require customer service; they cannot be applied merely by editing the payment review.
After that confirmation and immediately before payment creation, query the order again. If the query fails, do not create payment. Reapply the complete payable-order allowlist. If the order is no longer payable, invalidate the confirmation and use the payment-unavailable template. If any reviewed fact changed, including status, amount, currency, itinerary, passenger data, or deadline, invalidate the confirmation; when the order remains payable, show the complete updated payment review and obtain a new explicit confirmation. Only when the second query succeeds, remains payable, and matches the confirmed review may payment creation be called exactly once; when it is unchanged, proceed directly without another user-visible or deferred step between that query and creation.

Mistake	Required behavior
Login is deferred	Pause protected work until a complete, usable `uk_` or `sk_` Token is configured; public airport lookup and tokenless flight search may continue when no authentication rejection is active. Configuration does not by itself prove authorization.
Continuing verification after a token change or verification 20105	Clear old quotations, search once with the latest token, show the new results and explain the token change, then wait for a new customer selection. Never automatically match and verify the old selection.
Treating `uk_` as unsupported or sending it as `user_key`	Accept `uk_` for the personal channel and send it only in the flight API's `X-Skill-Token` header, just like `sk_`.
Reusing a quotation after configuring a new `sk_` token	The verification request authorizes a fresh search without extra permission. Display new quotations and require a new selection. Existing orders remain on their creation channel.
Searching with a country as the route endpoint	Ask for the actual city or airport; never use a country directly for airport lookup or flight search.
Searching before validating dates or confirming all passenger counts	Validate all leg dates before calling flight search: today through one year after today inclusive in the user’s timezone. Allow today; reject past dates, dates beyond the upper boundary, and decreasing leg dates. Confirm adult, child, and infant counts.
Reusing quotations after search criteria or passenger counts change	Immediately discard old quotations and sessions, then obtain approval for a new live search.
Automatically retrying an empty result	Treat no quotations as normal; explain it and obtain user approval before any repeat search.
Re-sorting offers locally	Preserve the API's ascending total-price order.
Showing search offers as bullets or using the wrong columns	Use the seven-column quotation table in the required order; align transfer segments on separate lines inside the flight, time/airport, departure-terminal, and cabin cells.
Omitting journey labels	Label round-trip journeys `Outbound`/`Return` and multi-city journeys `Trip 1`/`Trip 2`/… on every aligned segment line, translated into the response language.
Using an airline nickname or abbreviation	Display the full official airline name; if it cannot be resolved reliably, show the carrier code and flight number without inventing a name.
Showing arrival terminals in the quotation table	In the departure-terminal column, use only each segment's `DepTerminal` (`departure_terminal`).
Filling absent search data with placeholders	Leave the corresponding cell or segment portion empty; never convert missing baggage data into “no baggage”.
Showing cabin or booking-class codes	In the cabin column, translate `CabinClass` to the response language and do not display `CabinCode` or raw class codes.
Acting on rule changes during offer verification	Ignore `rule_changed`; report `price_changed` and the verified total/currency without rule-based branches or confirmations.
Booking using the searched price	Verify the selected offer and use the verified offer, price, currency, and session.
Verifying a quotation that is 20 minutes old	Discard it and obtain approval for a new search; expired quotations cannot be verified.
Treating selection as confirmation	Obtain explicit confirmation after the verified final summary.
Booking with missing passenger/contact data	Stop, list the missing or invalid required fields, and collect corrections before booking.
Discovering a child/infant after an adult-only quote	Explain the original quote's passenger basis, obtain actual counts/types, and re-search with approval; never relabel the passenger as an adult.
Searching an unsupported adult/infant group or silently repairing it	Stop before search, verification, or booking; at most one infant per actual accompanying adult, with no infant-only purchase. Preserve actual people and age types, ask before pursuing alternatives, and verify airline policy before promising eligibility.
Omitting documents because `support_no_card=true`	Collect all document fields; this Skill requires complete travel-document information.
Combining first and last names in the final review	Display `First name (given name)` and `Last name (surname)` as separate fields and obtain explicit confirmation.
Retaining a quotation after a business failure	Remove affected quotations, number mappings, sessions, and confirmations. Verification 20105 uses the one-cycle token-change recovery; other failures use stage-specific recovery.
Masking data or using prose lists for second confirmation	Use the booking/payment review tables with complete available passenger, document, and contact values. Never include a Token.
Exposing raw errors or assuming no returned number means no order	Explain the failure, confirmed order-number state, and recovery step; retain sanitized diagnostics internally.
Reusing confirmation after passenger data changes	Revalidate and show the complete updated passenger, document, and contact review, then obtain a new explicit confirmation.
Retrying a booking timeout	Never automatically retry an ambiguous booking; report uncertainty and stop.
Creating payment without a current order view	Query the order first, present its returned summary and exact flight order total/currency, then obtain explicit confirmation immediately before creation.
Treating any non-cancelled order as payable	Continue only when the latest successful order query returns `booking_successful`, no paid/ticketed evidence, and a valid future deadline when one is returned. All other states stop payment creation.
Creating payment from the pre-confirmation query	After confirmation, query the order again and reapply every eligibility check. A failed query or any change to reviewed facts prevents creation until the normal review requirements are satisfied again.
Missing payment method	Do not create payment. Present the methods allowed for the queried order currency and require the user to select one.
Omitting payment-review details or the deadline reminder	Confirm flight, itinerary, passengers, payment method, exact flight order total/currency, the numeric Stripe fee and payable total plus the non-refundable-fee disclosure when applicable, and the latest payment time before payment creation; state explicitly when no deadline was returned.
Asking the user for a payment return URL	Do not ask for or send one; the service supplies it.
Showing internal payment identifiers or offering a CNY-only method for another currency	Show only Stripe, WeChat Pay, Alipay, and Online Banking. Offer the last three only for a queried `CNY` order, and map the chosen label to the request-only API value internally.
Omitting or double-charging the Stripe fee	When Stripe is selected, calculate 3.5% of the queried order total with decimal half-up rounding to two places, then add that fee to the order total. Show both numeric amounts and obtain explicit acknowledgement of the fee, total, and non-refundable nature. Never apply it to another method, send calculated amounts to the API, present local calculations as API-returned values, or add the fee again to a returned payment amount.
Retrying a payment timeout	Never retry an ambiguous payment creation. Query payment status to reconcile and report it exactly as returned.
Sending a payable customer to support merely because they ask about ticketing	Query the existing order as needed; for a payable `booking_successful` order, explain payment is next and guide payment-method selection. Do not charge again after payment/ticketing evidence or skip payment confirmation.
Treating a payment URL as success	Present the URL when returned, but never infer payment success or ticket issuance from it.
Shortening or hiding a payment URL	Show the complete returned `payment_url` as visible clickable text without ellipses, aliases, or modification.
Sending `AgentCode`	Never send `AgentCode`; it is not part of this Skill's request contract.
Requests for extras or other unsupported operations	Politely direct the customer to company flight customer service; do not collect/send ancillary items or execute cancellation, change, refund, manual payment, or ticketing operations.
Listing city or airport choices, names, or codes from memory	Run `search_airports`; use and present only returned data. Before it returns, ask only whether the user accepts any airport or wants a specified airport.
Explaining quotation refund/change rules case by case	Use only the standardized post-payment no-refund/no-change reply and provide the TourMind flight customer-service email.

flight-booking-ai

Install

Related skills

name: flight-booking-ai description: Use when a user wants to resolve airports, search live flight offers, verify a selected airfare, create a flight booking, query a flight order, or safely create or query a third-party payment through TourMind. metadata: author: TourMind version: "1.0.8"

Flight Booking AI

Response language and templates

Transport and reference

Credential lifecycle

Skill version and update check

Workflow

Failures and scope

Common mistakes