12306 — Claude Code skill: China Railway tickets and timetables
This skill pulls train schedules, seat availability and station lists from the official 12306 API. Handy when you plan a trip across China without leaving the chat.
npx skills add kirorab/12306-skill --skill 12306 -a claude-codeWhat 12306 does
Two Node.js scripts do the work. query.mjs takes a departure and arrival point and returns trains with type, departure and arrival times, duration and seat counts per class. stations.mjs lists which stations belong to a city. That second step matters: a city-name query returns trains for every station in that city, so 武汉 covers 武汉站, 汉口站, 武昌站 and 武汉东站, not one central terminal.
Output format is a flag. The default writes an HTML file and prints its path; -f md prints a table straight to the chat. You can narrow results by train type (-t G), departure or arrival window, maximum travel time, bookable trains only, and seat class. --json dumps the raw response, which is the reliable way to confirm exact station names for a transfer.
No API key is involved — the data comes from 12306 directly. Node.js has to be installed. Station data is cached for 7 days in {baseDir}/data/stations.json. When you plan a connection, keep both legs at the same station: two different terminals in one city mean extra travel, not a quick change.
What it helps with
- check which trains run from Beijing to Shanghai on a given date
- narrow the list to morning high-speed departures under two hours
- see whether second-class seats are still available
- find out which stations a city actually has before routing
- confirm both legs of a transfer use the same station
Example prompts for the agent
- Show me trains from 北京 to 上海 tomorrow, G only, as a table
- Which stations are in 武汉?
- Find 深圳 → 长沙 departures before noon with seats available
How to install 12306
1Skills CLI (Vercel)
npx skills add kirorab/12306-skill --skill 12306 -a claude-code2Manually: put the files in place
~/.claude/skills/12306/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/12306/
1Skills CLI (Vercel)
npx skills add kirorab/12306-skill --skill 12306 -a codex2Manually: put the files in place
.agents/skills/12306/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add kirorab/12306-skill --skill 12306 -a cursor2Manually: put the files in place
.cursor/skills/12306/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install kirorab/12306-skill 123062Manually: put the files in place
.github/skills/12306/SKILL.md1Skills CLI (Vercel)
npx skills add kirorab/12306-skill --skill 12306 -a gemini-cli2Platform CLI
gemini skills install https://github.com/kirorab/12306-skillManually: put the files in place
.devin/skills/12306/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add kirorab/12306-skill --skill 12306 -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 12306
How do I install 12306 in Claude Code?
Run npx skills add kirorab/12306-skill --skill 12306 -a claude-code. The skill lands at ~/.claude/skills/12306/SKILL.md.
What does the 12306 skill do?
It queries the official 12306 API for train schedules, remaining tickets and station info. It covers G, D, Z, T and K train types.
Do I need an API key?
No. Data is fetched from 12306 directly, and the scripts need Node.js to run.
