---
name: maths-worksheets
description: Builds printable maths worksheets, quizzes and tests with answer keys and several shuffled versions using the maths-engine tools. Turns a teacher's request (topic, year level, ACARA codes, number of questions, difficulty mix) into a paper spec, checks the questions by sampling, and writes HTML for students and a separate key. Use when a teacher asks for a worksheet, homework, quiz, test or exam paper, or for different versions to stop copying.
license: MIT
---

# Maths worksheets, quizzes and tests

You turn a teacher's request into a checked paper, then write the files. Questions are generated by the engine, and the same spec and seed always give the same paper, so you can rebuild or reprint any version later.

Use the `maths-skill-finder` skill to choose skills. The spec format is in [references/paper-spec.md](references/paper-spec.md). For Moodle or Canvas use `maths-lms-export`.

## Workflow

### 1. Pin down the request

Get, or sensibly assume and say so: topic or curriculum codes, year level, how many questions, difficulty mix, how many versions, total marks if it matters, and whether it is for print or an LMS. Ask at most one or two questions; offer defaults for the rest.

### 2. Map the request to skills

Use `find_skills` (text, `year`, `code` prefixes such as `AC9M8N`) and read the best candidates with `get_skill`. Prefer skills whose description matches what the class has actually been taught. Note:

- `gradeable` must be true if you want an auto-markable test or LMS export. Rubric skills (proofs, explanations) can go on a printed paper, but a person marks them.
- `years` is often empty, so a year filter may miss skills. Also search by text and code.
- `needs_figure` skills include a diagram. Printable HTML draws it.

### 3. Check by sampling

Before building, call `make_questions(skill_id, count=3, source=..., answers=true)` for each skill and source you intend to use. Read the questions and answers as a teacher would:

- Is the level right for this class? Is the wording clear? Are the numbers sensible?
- Does the difficulty actually step up between `easy`, `medium`, `hard` and `exam`?
- Is the answer form what you want students to give (a surd `a√b`, a fraction, a decimal to a stated precision)?

Swap a skill or source if it does not suit, and tell the teacher why. A different `seed` gives a different sample.

### 4. Write the spec

Build the JSON paper spec (see the reference). Typical choices:

- One section per topic, or per difficulty, with a title.
- Easier items first, then harder; use `source` per item for the mix.
- `versions` of 2 to 4 for tests that need anti-copying. Each version has different numbers.
- `shuffle: true` to vary question order within sections.
- A fixed `seed` so the paper can be rebuilt. Record it.

### 5. Build and review

1. `build_paper(spec, format="json", answers=true)` and read it through. A json paper holds at most 30 questions in total and drops figure drawings unless you pass `include_figures=true`; for a larger paper, review a sample with `make_questions` and build the `html` files. Check the number of questions and marks, and spot-check a few answers against what you would expect. Fix the spec and rebuild if something is off.
2. `build_paper(spec, format="html")` writes the student worksheet. It has a name and date bar and the marks per question. With several versions, every version is in the file with a page break between them.
3. `build_paper(spec, format="html-key")` writes the answer key with working.

Use the same spec and seed for all three so they match. Do not give students the key file.

### 6. Report back

Tell the teacher:

- The paths of the files written (the tool returns them).
- The seed, and the version labels (A, B, ...).
- What is on the paper: skills, sources, number of questions and total marks.
- Anything to watch: rubric skills that need hand marking, figure questions, anything you swapped.
- How to print: open the HTML in a browser and print (A4).

## Keep attribution

A built paper carries an `attribution` list. Any skill whose summary carries an `attribution` field (ACARA senior content) adds the ACARA attribution to the paper. If you share, publish or reuse material from these skills, keep that text with it. The HTML files already include it.

## Limits and cautions

- A paper has at most 400 questions across all versions (a `json` build, at most 30), at most 100 questions per item and at most 10 versions.
- Questions are generated, not written by a person. Always sample and read before handing a paper to a class.
- A paper rebuilt after the library is updated may differ. Keep the spec, the seed and the engine version (from `engine_info`) with the files.
- Do not change a paper's key by hand. Rebuild from the spec.