---

name: quiz description: Indefinite one-at-a-time Q&A quizzing on a user-chosen topic, with on-the-spot teaching when wrong, persistent sessions, and spaced repetition that tracks progress over time. Use when the user wants to be quizzed, tested, drilled, or to study/revise a topic. allowed-tools: Bash(uv run:*)

Quiz

Quiz the user on a topic, one question at a time, forever (until they say stop). Sessions persist to disk with spaced repetition so they can be resumed later.

Do NOT hand-edit the session JSON. A helper script (quiz.py) owns all file IO, Leitner-box math, date arithmetic, stats and logging. Your job is to ask questions, grade answers, teach, and call the script. Sessions live in ~/.claude/quiz-sessions/<topic-slug>.json — the script manages the path.

The helper script

Run from the skill dir; uv handles the (zero) dependencies. All commands print JSON.

cd ~/.claude/skills/quiz

# Create or resume a session (bumps the session counter on resume).
# Returns stats, accuracy %, today's date, and the questions due for review.
uv run quiz.py start "<topic>"

# Grade a NEW question (the common case). --answer/--notes optional but recommended.
uv run quiz.py record "<topic>" --result correct|partial|incorrect \
  --question "the question text" --answer "canonical answer" --notes "one-line key point"

# Grade a RE-ASKED existing question (spaced repetition) — pass its id, no --question needed.
uv run quiz.py record "<topic>" --result correct|partial|incorrect --qid q3

# Read-only views:
uv run quiz.py due "<topic>"      # questions due today, sorted (lowest box, oldest first)
uv run quiz.py status "<topic>"   # full stats, per-question accuracy, weakest 5, due count
uv run quiz.py list               # all topics on disk

The script computes box, nextReview, timesAsked/Correct, stats, the log entry and updated for you. It also slugifies the topic, so always pass the same human-readable topic string and it resolves to the same file.

--result meaning: correct = fully right; partial = right idea but missing nuance or partly wrong; incorrect = wrong, "I don't know", or blank.

Spaced repetition (handled by the script)

Each question has a Leitner box 1–5. After grading: correct → box+1 (max 5), partial → unchanged, incorrect → reset to 1. nextReview = today + interval, intervals (days) {1:1, 2:2, 3:4, 4:8, 5:16}. A question is due when nextReview <= today. You don't compute any of this — record does.

Starting / resuming a session

1. Ask for the topic if not given.
2. Run uv run quiz.py start "<topic>".
   • resumed: true → greet with one line of progress from the output: total asked, accuracyPct, and dueCount due for review today. The due array gives you the questions (and notes) to re-ask first.
   • resumed: false → brand new; just start asking.
3. Tell the user they can say "stop", "done", or "quit" any time to end and save.

The quiz loop

Repeat until the user stops:

1. Pick the next question.
   • If there are due questions (from start/due) → re-ask one first (the array is already sorted lowest-box / oldest-first). Mix in ~1 in 4 brand-new questions to keep it fresh.
   • Otherwise → generate a NEW question on the topic at an appropriate difficulty.
   • Don't repeat a question already asked this session unless it's a deliberate spaced-repetition re-ask.
2. Ask exactly one question. No multi-part dumps. Wait for the answer.
3. Grade the answer against the intended answer → correct/partial/incorrect.
4. Respond:
   • correct → brief affirmation (one line), optionally a small extra fact.
   • partial → name what was right, fill the gap in 1–2 sentences.
   • incorrect → teach: 1–2 paragraphs explaining the answer with the reasoning/context so they actually learn it.
5. Record it with quiz.py record (use --qid for a re-ask, else --question for a new one). This persists immediately, so an abrupt stop never loses progress.
6. Ask the next question.

Keep your prose tight — the user wants to be quizzed, not lectured (except the 1–2 teaching paragraphs on a wrong answer).

Ending a session

When the user stops, run uv run quiz.py status "<topic>" and give a short recap: questions this session, accuracy, the weakest areas, and when the next review is due. Confirm the session file path.

Notes

• The script stamps dates itself (date.today()); never pass or guess dates.
• Difficulty is yours to adapt: harder after a streak of correct, easier after incorrect.
• "Show my progress" without quizzing → run status and summarise.
• If uv is unavailable, python3 quiz.py ... also works (stdlib only).