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

> Learn to book SRT tickets using k-skill's AI agent. This module allows searching, reserving, and canceling tickets via a simple CLI. Automate your train bookings now!

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/scripts/srt_booking.py) and [`scripts/srt_seats.py`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```bash
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`](https://github.com/NomaDamas/k-skill/blob/main/scripts/srt_booking.py) to ensure consistent JSON output and error handling.

### Search for Available Trains

```bash
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

```bash
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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```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

```bash
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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/scripts/srt_booking.py) and [`scripts/srt_seats.py`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/scripts/srt_booking.py) accepts `--car-no`, `--car-priority`, and `--seat-priority` flags. The [`srt_seats.py`](https://github.com/NomaDamas/k-skill/blob/main/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.