play-llm-chess
Play an LLM Chess game through the `chess` CLI: human-vs-LLM with a browser player or CLI-vs-CLI with independent color sessions and a browser spectator. Use to start or continue a game, make moves, h
SKILL.mdchess/src/llm_chess/skills/play-llm-chess/SKILL.md
GitHubPlay LLM Chess
Operate one LLM seat of an LLM Chess game through the installed chess command. In human_vs_llm, the human plays on the browser board. In cli_vs_cli, this session controls one assigned color, a separate LLM session controls the other color, and the browser is a spectator. Keep user-facing commentary in the user's language.
Start or resume
- Run
chess --helpand treat its output as the current command contract. - Query the current game state with
chess status. After identifying a CLI-vs-CLI game and this session's color, usechess --color COLOR statusfor later queries. Status is read-only, including when a color is specified. - If the
chesscommand is unavailable, report that LLM Chess must be installed and stop until the command is available. - If the server is unreachable, start it in a persistent process with
chess start. Keep it running and issue gameplay commands from separate shell calls. The CLI does not start either LLM session. - When the state is
setup, ask the user to configure the game in the browser. The setup offershuman_vs_llm(default) andcli_vs_cli, with optional participant names; there is no CLI game-creation command. Choose a human color forhuman_vs_llm. Incli_vs_cli, use the color assigned to this session. Provide browser assistance only when the user explicitly asks for it. - In
cli_vs_cli, prepend--color COLORbefore the subcommand on every command in this session, includingstatus,wait,move,takeback, andresign. Specify the color independently each time; do not rely on shared or remembered CLI state. Existing commands without--colorremain available inhuman_vs_llm.
The CLI-vs-CLI command forms are:
chess --color COLOR status
chess --color COLOR wait
chess --color COLOR move MOVE [--no-wait]
chess --color COLOR takeback request|accept|reject
chess --color COLOR resign
Play the game
Use each returned snapshot as the current game state:
- Terminal state: Checkmate, draw, and resignation end the loop. Report the result and stop. Resignation events identify which side resigned.
- Game reset: A
game_resetevent may return a nonzero exit code as a normal wake-up signal. Query fresh status, using this session's--colorin CLI-vs-CLI mode, then continue from the new state. - Your turn: Choose a move using your own reasoning and the current snapshot's legal-move list, then submit one of those legal moves with
move. The legal-move list is authoritative. The default move blocks until the opponent responds or another actionable state is returned; use--no-waitonly when an immediate return is requested. - Opponent's turn: Run
waitand handle the returned event before taking another action. - Incoming takeback: A
takeback_requestedevent may wakewaitor a blockingmove. Do not make moves while a takeback is pending. Accept or reject it according to the user's direction and game context, submit exactly one response, and use its returned snapshot. - Outgoing takeback: Requesting a takeback of your latest move blocks until the opponent accepts or rejects it. Continue from the returned snapshot and handle the response before resuming the turn loop.
- Takeback accepted: Use the snapshot as the source of truth. If the requester's move was still the last move, one ply is undone; if the opponent already replied, two plies are undone so the requester moves again.
- Takeback rejected: The position and move history stay unchanged. Re-evaluate the snapshot and continue.
CLI-vs-CLI sessions
- Each LLM session operates only its assigned color. The user runs or connects the two sessions independently; do not launch or invoke the opponent AI.
- Repeat
--color COLORon every command in each session. A color-qualifiedstatusremains read-only. - Keep at most one blocking command active per session. If it returns a process or session identifier, resume that same process until it returns; do not start a duplicate command.
- The browser shows a spectator board with White at the bottom, participant names and colors, current turn, move history, and result. Human move, takeback, and resignation controls are hidden; New game remains available.
- Handle checkmate, draw, or resignation by reporting the final result. Keep the server process available so the user can start another game.
Operating rules
- Re-evaluate the snapshot and legal moves after every opponent move, takeback response, or game reset.
- Handle a pending takeback before issuing another move command.
- Keep the browser setup and game actions human-owned unless the user explicitly asks for browser assistance.
- Choose moves with your own reasoning. Use another model or a chess engine only when the user explicitly asks for one.
- Continue the turn loop until the game ends or the user asks to pause.