Skip to content
Developer documentation ⌄
DevelopersAgent skill

Printable Sudoku Worksheet Creator

Ask your assistant for a set of printable Sudoku worksheets. Get verified puzzles, separate answer sheets and Sudoku Online play links with one reusable skill.

Free downloadVersion 1.0.1MIT skill license
On this page

Read and copy the skill

The complete SKILL.md is below. Copy it to your assistant or read through the instructions here. The ZIP also includes the supporting API reference and license.

---
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: [email protected]
---

# 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: [email protected].

Download the skill

Give your assistant a worksheet workflow for classroom handouts, puzzle clubs and personal practice. The skill uses the free Sudokumax MCP server, with a REST API fallback for assistants that can make HTTP requests.

Download skill ZIP

Download .skill package · Read SKILL.md · Files and checksum

Both downloads contain the same skill folder. No GitHub account or local puzzle engine is needed.

Set up your assistant

  1. Install the skill.

    Unzip the download and place the sudokumax-worksheets folder in your assistant's supported skills directory, or upload the archive if your assistant supports skill imports. Keep SKILL.md and its references folder together.

  2. Create a free API key.

    Create your key and keep it in your assistant's private settings. The skill does not contain credentials.

  3. Connect Sudokumax.

    Follow the MCP setup guide. Your client needs Streamable HTTP and a custom Bearer header. For direct HTTP use, the package includes an API guide using a private environment variable.

  4. Request a worksheet pack.

    Use one of the examples below. Installation alone does not establish a working MCP connection.

Try a worksheet request

Use Sudokumax to create 10 beginner Sudoku worksheets on A4 paper with separate answer sheets. Give me the PDF and a collection link for online play.
Make 5 beginner Sudoku puzzles on US Letter paper without answer sheets. Keep the Sudokumax credit and give me a playable link for each puzzle.

Ten puzzles with answers produce a 20-page PDF. You can also supply your own 81-cell Sudoku grids and ask the skill to export them without changing the givens.

View a sample worksheet and answer PDF

What is included

  • SKILL.md: worksheet workflow, examples, result checks and service limits.
  • references/api.md: direct HTTP setup and an example using a private API key.
  • LICENSE.txt: MIT permission for the skill files.

Free Sudoku puzzles, with attribution

API calls are free. Keep the Sudokumax credit on every printable worksheet and answer sheet. Online publications must include a visible link to sudokumax.com. The skill license and API service terms are separate.

Know the limits

Each request supports up to 20 puzzles in A4 or US Letter format. Difficulty follows a measured technique ladder: naked singles, hidden singles, locked candidates, naked pairs, and expert when further techniques are needed. Generated PDF download links expire after 24 hours; download a copy to keep it. The sample file above is a permanent example.

Worksheet requests also create public, shareable puzzle links. Avoid confidential grids. The package contains instructions, not an automatically installed connector, and needs an assistant with the capabilities described above.

Website: https://sudokumax.com · Support: [email protected]