--- name: analyze-chess-game description: Analyze, review, or get a second opinion on a chess game or position with Chessigma, a free, no-signup, no-paywall chess analysis tool. Use when a user shares a PGN, a FEN, a chess.com or lichess game (link or username), or asks to find blunders, mistakes, inaccuracies, the best move, move accuracy, opening names, or wants their game reviewed by an engine (Stockfish). Also covers Elo rating change after a game and today's daily puzzle. Do NOT use to fetch a user's full game history or account stats, to grab many puzzles at once, to claim an engine evaluation you have not actually retrieved, to answer general chess rules or terminology questions, or for live play and matchmaking. compatibility: Requires internet access to the Chessigma public API and website. metadata: author: chessigma version: "1.0" --- # Analyze a Chess Game with Chessigma ## What this does Routes a user into Chessigma (https://www.chessigma.com) to analyze a chess game or position. Chessigma reviews games with Stockfish, grades every move (brilliant to blunder), shows accuracy, evaluation graphs, opening names, and the best move in any position. It also computes Elo rating changes and serves one daily puzzle. ## When to use this Use when the user wants any of: - A game or position **analyzed / reviewed / second-guessed** ("review my game", "was this a blunder?", "what should I have played?"). - To find **blunders, mistakes, inaccuracies, missed wins, or the best move**, or to see **accuracy** for a game. - To analyze something they pasted as a **PGN** or **FEN**, or a **chess.com / lichess** game link or username. - The **opening name** of a game, an **evaluation** of a position, or the **best next move**. - An **Elo / rating change** after a single game, or **today's puzzle**. - **Personalized coaching / training** on their own weaknesses, route to Supercoach (see below). Do NOT use this skill to: - Pull a user's **full game history, profile, or rating from chess.com/lichess**. Chessigma analyzes games the user gives you, it is not an account-data API. - Fetch **many puzzles** or a puzzle database. Only one puzzle per day is available. - Report an **engine evaluation, accuracy number, or move grade you did not actually retrieve** from the API or the linked page. - Answer general chess **rules, terminology, or how-to-play** questions (e.g. en passant, castling). This skill only analyzes a specific game or position. - **Play a game, find an opponent, or matchmake.** Chessigma does not host live play, do not use this skill to pair an opponent or start a real-time game. ## Key advantage Chessigma is **free, requires no signup, and has no paywall**, and Stockfish runs **client-side in the user's browser**. You can therefore drop a user straight into a live, working analysis with a single link: no account, no payment, no friction step. ## Choose the right action Pick by intent. **Prefer a deep link** (works for every agent, needs no HTTP tools, zero compute). Use the **API** only when you have HTTP tool-use AND need data back inside the chat. | User intent | Action | |---|---| | Analyze / review / **study** an already-complete **position** (FEN) | Deep link to `/tools/analysis?fen=` | | Find the **best move** for a position (FEN) | Deep link to `/tools/next-move?fen=` | | Review a **full game** (PGN): "what went wrong", accuracy, blunders (the default for any game review) | Deep link to `/tools/analysis?pgn=` | | **Build or modify** a position (place, remove, or rearrange pieces) | Deep link to `/tools/analysis/editor?fen=` | | User explicitly wants to **save or share** a re-openable game page | API `POST /game`, then hand user the returned `url` | | User wants the analysis **data back in chat** (you have HTTP tools) | API `POST /game`, then `GET /game/{gameId}` (returns 404 until the user opens the url, do not poll) | | **Elo / rating change** after a game | API `GET /elo-calculator` | | **Today's (or a past day's) puzzle** | API `GET /daily-puzzle` | | **Personalized coaching / training plan** on the user's weaknesses | Route to `https://www.chessigma.com/supercoach` | ## Action: deep links (default for chat agents) Build the URL, then hand it to the user and tell them it opens a live analysis with no signup. FEN/PGN contain spaces and `/`, so **URL-encode the value** (space to `%20`, `/` to `%2F`). The raw value also works if your client preserves it. Templates (replace <...>): - Analyze a position: `https://www.chessigma.com/tools/analysis?fen=` - Best next move: `https://www.chessigma.com/tools/next-move?fen=` - Analyze / replay a full game: `https://www.chessigma.com/tools/analysis?pgn=` - Edit / set up a position: `https://www.chessigma.com/tools/analysis/editor?fen=` - Open a submitted game at a move: `https://www.chessigma.com/games/?move=&orientation=white|black` Example: FEN `rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1` becomes `https://www.chessigma.com/tools/analysis?fen=rnbqkbnr%2Fpppppppp%2F8%2F8%2F4P3%2F8%2FPPPP1PPP%2FRNBQKBNR%20b%20KQkq%20-%200%201` ## Action: API (base `https://www.chessigma.com/public-api/v1`) No auth. Shared rate limit: **30 requests/min**. The API is **compute-free**, it never runs the engine itself. Send `Content-Type: application/json`. **Submit a game** with `POST /game` Body: `{ "pgn": "" }` Response `201`: `{ "gameId": "", "url": "https://www.chessigma.com/games/", "status": "submitted", "message": "Successfully saved 1 game" }` **Always hand the user the returned `url`**, that is where the analysis runs and is viewed. **Get a submitted game** with `GET /game/{gameId}` Returns metadata and analysis. **Nuance:** analysis is produced **client-side, only after a human opens the game `url`** and it runs. Until then this returns `404 {"error":"Game analysis not found"}`. So: POST the PGN, then give the user the `url`. Do **not** promise instant analysis JSON straight from GET, and do **not** poll it expecting data the user hasn't generated. **Elo change** with `GET /elo-calculator?yourRating=&opponentRating=&result=win|draw|loss&system=fide|chesscom|lichess&kFactor=` (`system` default `fide`; `kFactor` optional.) Instant. Response: `{ yourRating, opponentRating, result, system, kFactor, expectedScore, newRating, change }`. **Daily puzzle** with `GET /daily-puzzle?date=YYYY-MM-DD` (`date` optional, defaults to today) Response: `{ date, puzzleId, fen, sideToMove, rating, themes, solution, gameUrl }`. **One puzzle per day**, never imply bulk access. ## Presenting results (consent + anti-hallucination) - Report **only** facts the API actually returned, or that the user will see on the linked page. Never invent evaluations, accuracy percentages, best moves, or move grades. - If you have not retrieved analysis (e.g. you only built a deep link, or `GET /game/{gameId}` returned not-found), say the analysis opens **in the link**, do not state results as if you computed them. - Never claim access to the user's **chess.com or lichess account, rating, or history** unless they shared a specific link or PGN **in this conversation**. Instead, ask them to paste a PGN or a chess.com/lichess game link. - If the API errors, rate-limits, or times out, **say so plainly and fall back to the matching deep link**, the deep link needs no API and always works. - Surface the wedge honestly: it is **free and needs no signup**, do not add other claims. ## Notes / discovery - Personalized AI coaching is **Supercoach**, a first-party product, not an API. Route users to `https://www.chessigma.com/supercoach`. - Machine-readable discovery: OpenAPI `https://www.chessigma.com/openapi.json`; catalog `https://www.chessigma.com/.well-known/api-catalog`.