How to Use k-skill to Book SRT Tickets with an AI Agent

The k-skill SRT booking module layers the SRTrain Python library under a unified CLI, enabling AI agents to search, inspect seats, reserve, and cancel tickets through a side-effect-free workflow until explicit user authorization.

The NomaDamas/k-skill repository provides a self-contained skill that transforms the open-source SRTrain library into an AI-agent-compatible interface for Korean high-speed rail reservations. By following the declarative workflow defined in instruction.md, agents can automate SRT bookings while maintaining strict safety boundaries. This guide explains exactly how to use k-skill to book SRT tickets with an AI agent using the command-line tools and Python helper scripts.

Architecture of the SRT Booking Skill

The skill implements a three-layer architecture that separates definition, instruction, and execution:

• Skill definition (srt-booking/skill.json): Registers the skill, declares required profiles (vault, browser, action:booking), and bundles the helper scripts into the package.
• Instruction markdown (srt-booking/instruction.md): Provides the agent with a human-readable workflow guide covering prerequisites, credential handling, environment variables, and failure modes.
• Python helper scripts (scripts/srt_booking.py and scripts/srt_seats.py): Implement concrete operations by wrapping the SRTrain client, parsing HTML seat tables from SRT_SEAT_ENDPOINT, and generating stable train IDs.

The Eight-Phase Booking Workflow

When processing a request like "Find an SRT seat from 수서 to 부산 tomorrow morning," the agent executes a structured sequence:

1. Dependency installation: Ensures SRTrain is available via python3 -m pip install SRTrain.
2. Credential loading: Retrieves KSKILL_SRT_ID and KSKILL_SRT_PASSWORD from the Dolshoi secure vault using vault-run, or from the host environment/~/.config/k-skill/secrets.env.
3. Train search: Executes the search sub-command, which calls SRT.search_train to retrieve candidate trains.
4. User summary: Presents departure/arrival times, seat class availability, and estimated fare before any side-effect occurs.
5. Seat inspection: If requested, the seats sub-command fetches the seat-selection page and parses HTML via srt_seats.py.
6. Reservation: Upon user confirmation, invokes the SRTrain client to create the booking using the reserve method.
7. Payment handling: In Dolshoi mode, pauses for a clarify step showing reservation details, then hands control to the official SRT payment UI via CloakBrowser.
8. Cancellation: If needed, the cancel flow re-identifies the reservation via SRT.cancel_reservation and requests confirmation before proceeding.

Installation and Prerequisites

Before executing commands, install the SRTrain dependency:

python3 -m pip install SRTrain

Configure credentials using one of two supported modes:

• Dolshoi (secure): The agent calls vault-run to inject KSKILL_SRT_ID and KSKILL_SRT_PASSWORD at runtime without exposing them in the context.
• Standard: Export variables in the host environment or store them in ~/.config/k-skill/secrets.env.

Command-Line Operations for AI Agents

All operations use the k-skill CLI wrapper around scripts/srt_booking.py to ensure consistent JSON output and error handling.

Search for Available Trains

npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py \
  -- search 수서 부산 20260328 080000 --time-limit 120000 --limit 5

This returns JSON with up to 5 matching trains, each assigned a stable train_id for downstream operations.

Inspect Seat Availability

npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py \
  -- seats 수서 부산 20260328 080000 \
  --train-id <train_id> \
  --car-no 5 --available-only \
  --car-priority center --seat-priority forward-window --limit 20

The srt_seats.py parser extracts HTML tables from the SRT website, returning available seats with direction flags (forward/window) and specific seat numbers (e.g., 11A).

Create a Reservation

Once a train is selected, execute the reservation logic directly via Python:

import os
from SRT import Adult, SRT, SeatType

srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
trains = srt.search_train("수서", "부산", "20260328", "080000")
reservation = srt.reserve(
    trains[0],
    passengers=[Adult(1)],
    special_seat=SeatType.GENERAL_FIRST,
)
print(reservation)  # Outputs reservation number, fare, and purchase deadline

Cancel Existing Bookings

npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py \
  -- cancel --reservation-id <reservation_number>

The cancellation command follows the same safety protocol as reservation, requiring explicit confirmation before invoking the SRTrain API.

Safety Mechanisms and Side-Effect Control

The workflow enforces side-effect-free operations until explicit user authorization. According to the source code in instruction.md, the agent cannot charge payment cards or finalize reservations without a clarify confirmation step. In Dolshoi mode, sensitive credentials remain in the secure vault until the moment of API invocation, ensuring they never leak into the agent's operational context.

Summary

• The k-skill SRT booking skill wraps the SRTrain library in scripts/srt_booking.py and scripts/srt_seats.py for AI-agent consumption.
• Credential management supports both Dolshoi secure vaults and standard environment variables (KSKILL_SRT_ID, KSKILL_SRT_PASSWORD).
• The eight-phase workflow separates search, inspection, and reservation steps to prevent accidental bookings.
• Seat inspection parses live HTML from the SRT website to provide real-time availability data for specific cars and seat preferences.
• All reservation actions require explicit user confirmation before executing SRT.reserve or payment handoff to CloakBrowser.

Frequently Asked Questions

What are the requirements for using k-skill to book SRT tickets?

You need Python 3 with the SRTrain package installed, valid SRT credentials stored in KSKILL_SRT_ID and KSKILL_SRT_PASSWORD, and the k-skill CLI available via npx. The skill supports both standard environment configuration and Dolshoi secure vault mode for credential management.

How does the AI agent prevent accidental ticket purchases?

The workflow defined in instruction.md mandates side-effect-free operations until the clarify step. The agent presents a summary of train details, passenger count, and total cost before invoking SRT.reserve or handing off to the CloakBrowser payment UI, ensuring explicit user authorization precedes any financial transaction.

Can the agent select specific seats or car numbers?

Yes. The seats sub-command in scripts/srt_booking.py accepts --car-no, --car-priority, and --seat-priority flags. The srt_seats.py parser analyzes the HTML seat-selection page to identify specific available seats (e.g., 11A) and their characteristics (forward-facing, window, etc.).

Is it possible to cancel reservations through the AI agent?

Yes. The agent can execute the cancel sub-command by providing the --reservation-id parameter. Following the safety protocol, the agent first re-identifies the reservation details and requests confirmation before calling SRT.cancel_reservation to process the cancellation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}