---
name: sudokumax-worksheets
description: >
  Create printable Sudoku worksheets, PDF puzzle packs with answer sheets, and Sudoku Online playable links using Sudokumax. Use for classroom handouts, free Sudoku puzzles, and printable Sudoku requests, including exporting existing 9x9 grids. Website: https://sudokumax.com
license: MIT
metadata:
  compatibility: Requires network access and a free Sudokumax API key. Use an MCP client supporting Streamable HTTP with a Bearer header, or an HTTP-capable agent with private environment variables. No GitHub account, npm package, or local puzzle engine is required.
  author: Sudokumax Team
  version: "1.0.0"
  homepage: https://sudokumax.com/developers/skills
  support: hello@sudokumax.com
---

# Printable Sudoku Worksheet Creator - Sudokumax

Create verified 9x9 Sudoku worksheets with the hosted Sudokumax service, then return the actual PDF and playable links. Website: https://sudokumax.com.

## Connect

Use the configured Sudokumax MCP server at `https://sudokumax.com/api/mcp`. It requires `Authorization: Bearer YOUR_API_KEY` on each request. Obtain a free key at https://sudokumax.com/developers/keys and configure it in the client's private settings; do not ask the user to paste it into chat or embed it in shared files.

If the tools are unavailable, explain the missing connection and point to https://sudokumax.com/developers/mcp. An agent with direct HTTP access may instead use the REST workflow in [references/api.md](references/api.md), with a key supplied through its private environment. Skill installation alone does not configure MCP or create an API key. Do not claim an output was created when the service was not called successfully.

## Choose the worksheet workflow

- For new puzzles, call `create_worksheet_pack`. Preserve any specified count, difficulty, paper size, and answer-sheet preference. When unspecified, use 5 puzzles, `beginner`, `a4`, and `includeAnswers: true`, and briefly state these defaults.
- For supplied grids, call `export_worksheets` with the original puzzles instead of generating replacements. Each grid has 81 cells; use digits 1-9 for clues and 0, a period, or a hyphen for blanks. Keep row order and givens intact. Ask about an ambiguous transcription before exporting it.
- Each call accepts 1-20 puzzles. For a larger requested set, split it into batches of at most 20 and return separate PDFs. Do not promise one combined PDF unless a PDF tool is actually available and used. Distinctness is guaranteed within a generated batch, not across calls.
- Supported paper sizes are `a4` and `letter`. Output has one puzzle per page plus a separate answer page per puzzle when answers are enabled. Custom grid sizes, multiple puzzles per page, and arbitrary page layouts are not supported by these tools.

Example request: "Make 10 beginner Sudoku worksheets on A4 with answers and online play links."

```json
{"count":10,"difficulty":"beginner","includeAnswers":true,"paper":"a4"}
```

Call `create_worksheet_pack` with that input. For two existing puzzles without answers on US Letter, use `export_worksheets` with `puzzles` containing their two actual 81-cell strings, `includeAnswers: false`, and `paper: "letter"`.

## Difficulty and privacy

Available generation labels are `beginner`, `easy`, `medium`, `hard`, and `expert`. Beginner puzzles are verified solvable using naked and hidden singles. Other labels are generator settings, not calibrated human difficulty ratings. Report the returned analysis honestly; do not claim a hard or expert human rating from a beyond-singles result.

Worksheet tools also return public playable links encoding the puzzle grids. They have no access control or recall operation. For a request that explicitly requires confidential puzzles or forbids public links, explain this limitation before calling the worksheet tools. Do not silently publish confidential input.

## Check and deliver the result

1. Check HTTP status and the MCP `isError` flag. Use `structuredContent`, or parse the JSON in the text content if needed.
2. Verify that `puzzles` has the requested count and that `pdfUrl`, `collectionUrl`, `paper`, `includeAnswers`, and attribution are present. If the client can fetch files, download the PDF promptly and confirm it is a PDF before attaching it.
3. Return the PDF link or saved file first, then the collection link. Include individual `puzzles[].playableUrl` links when requested. Quote `pdfExpiresAt` when returned. Download links expire after 24 hours and can stop working if the originating key or account is revoked. A saved PDF does not share that expiry.
4. Preserve the printed credit on every puzzle and answer sheet. Every published online output must include a visible clickable https://sudokumax.com link; offline output must print `sudokumax.com`. The API is free with attribution under https://sudokumax.com/developers/terms. This requirement also applies to modified or commercially distributed outputs.

For 10 puzzles with answers, expect 20 pages. Never invent a download URL, replace a failed generation with unverified made-up grids, or describe an expired link as working.

## Recover without changing the user's puzzles

- Missing or revoked credentials: stop and direct the user to key setup. Never display the key.
- Invalid or non-unique input: explain the error and ask for a corrected grid. Do not change givens to force acceptance.
- HTTP 429: honor `Retry-After` and make at most two delayed retries.
- Timeout or uncertain result: report the uncertain outcome before retrying generation. The pack endpoint has no idempotency key; another request generates another set.
- Expired PDF with a saved successful response: call `export_worksheets` using those same `puzzles[].puzzle` strings and the same print settings. Do not regenerate a different set.

The skill files are MIT licensed. The hosted API and generated outputs retain their separate service and attribution terms. Support: hello@sudokumax.com.