Claude Tutor 🎓

Turn Claude Code into a real teacher. Not a chatbot that answers questions — a teacher that runs full courses on any subject: a personalized syllabus, mastery-gated lessons, quizzes, exams, spaced-repetition review, and progress that persists across sessions.

Türkçe: README.tr.md

Every teaching behavior is grounded in peer-reviewed learning science. Sources with effect sizes: methodology.

See a real session: examples/example-session.md.

What it does

Command	What happens
/teach python	First run: interview, placement diagnostic, a syllabus you approve, then lesson 1 if there's time. Every later run resumes the course.
/teach	Continue where you left off — starts with a retrieval warm-up
/quiz	Unit quiz: mastery check with calibration and remediation
/exam midterm · /exam final	Cumulative, graded, university-style — with a full teaching debrief
/review	Daily spaced-repetition session on your due cards
/progress	Dashboard: mastery map, streak, weak spots, next step

What you end up with. The course leaves artifacts behind, one set per course under ~/.claude/tutor/courses/<course>/:

• a syllabus you approved before anything was written to disk;
• a notebook written from your own end-of-lesson recall, then corrected and extended — the textbook you wrote, in your language;
• a mistakes log recording the diagnosed cause of each error, which the tutor mines when it designs your next practice;
• a card deck that schedules its own reviews.

Each objective moves new → learning → learned → mastered on accumulated evidence, and drops back down when a spaced review shows it didn't stick.

Command names after a plugin install: plugin skills are namespaced, so the commands above become /tutor:teach, /tutor:quiz, /tutor:exam, /tutor:review, /tutor:progress. The bare /teach form also works when no other command claims that name. If you install by cloning or copying the skills (Options 2–3 below) they're just /teach, /quiz, and so on. You can also simply ask — "teach me Python", "quiz me" — and Claude triggers the right skill.

Any subject works: /teach linear algebra, /teach music theory, /teach japanese, /teach ottoman history all run the same loop.

Requirements

Claude Code, with plugin support for Option 1. Nothing else — no runtime to install, no extra API key, no account.

Install

Three alternatives; pick one. Installing the plugin and working inside a clone loads the skills twice.

Option 1 — plugin (recommended): inside Claude Code:

/plugin marketplace add kubilaiswf/claude-tutor
/plugin install tutor@claude-tutor

Option 2 — clone and study inside it: the repo itself is a classroom; Claude is always in teacher mode there:

git clone https://github.com/kubilaiswf/claude-tutor && cd claude-tutor && claude

Option 3 — copy the skills out of a clone to make them personal, available in every project:

# macOS / Linux / Git Bash
mkdir -p ~/.claude/skills
cp -r .claude/skills/* ~/.claude/skills/

# Windows PowerShell
New-Item -ItemType Directory -Force $HOME/.claude/skills
Copy-Item -Recurse .claude/skills/* $HOME/.claude/skills/

What this plugin does on your machine

• It runs code. In a programming course the tutor executes code with the Bash tool — its own examples, before it tells you what they print, and your submissions, before it judges them. That is deliberate: an unverified output of its own becomes your bug. Deny the permission prompt and it falls back to calling outputs unverified predictions.
• It writes files, in one place. ~/.claude/tutor/ — plain JSON and Markdown you can open, edit, and delete. Nothing is written into your own projects.
• No server, no account, nothing uploaded by the plugin. There is no backend behind it.
• The conversation leaves your machine exactly as in any other Claude Code session — your messages go to Claude's API, and when the tutor runs a web search to verify a fact or find documentation, that query goes out too.
• Don't paste secrets into a lesson. notebook.md and mistakes.md store text verbatim, yours included.

Why it teaches the way it does

This tutor will sometimes feel harder than watching videos or asking an AI for answers. That is the design:

• Retrieval before re-reading — practice testing is the best-evidenced study technique there is (g ≈ 0.5–0.6 across meta-analyses; Dunlosky et al. 2013 rate it highest-utility).
• Spaced and interleaved review — distributed practice is the other highest-utility technique; spaced retrieval reaches g ≈ 0.74 (Latimier et al. 2021).
• No advancing past a failed mastery check — Bloom's mastery learning, d ≈ 0.5 across 100+ studies. Diagnose, re-teach differently, re-check on parallel questions.
• No answers to an exercise you are still working on — an RCT (Bastani et al., PNAS 2025; ~1,000 high-schoolers) found unrestricted AI answer-giving lowered final exam scores by 17%, while a guardrailed tutor mode did not. You get a hint ladder instead.
• Feedback on your process, never on you — Hattie & Timperley 2007; Kluger & DeNisi 1996 found ~38% of measured feedback effects made performance worse, mostly the person-focused ones.
• Worked examples first, then faded — cognitive load theory (Sweller); continuing to over-explain once you are competent actively hurts (expertise reversal effect).

Full evidence catalogue with citations: methodology.md.

Does it actually do this?

Those citations prove the techniques work. They say nothing about whether these particular files deliver them — a prompt can cite every paper in the field and still cave the moment a learner says "just tell me".

So the behavioral claims are tested. evals/ runs real multi-turn sessions against a simulated learner and checks what happened: an adversarial student with eight escalating tactics trying to extract an answer, a learner who fails a mastery check, one who is confidently wrong and pushes back, a cold restart that has to resume from disk. State files are asserted mechanically; behavior is graded by a separate judge pass that must quote the line it ruled on.

Results, including failures, are committed in evals/results/SUMMARY.md.

What remains unmeasured: whether a person using this learns more than they would have otherwise. That needs a controlled study with real learners, and this project does not have one. Two different claims — see evals/README.md.

Known limitations

• This is a set of instructions to a language model, not deterministic code. The same lesson run twice will not come out the same, and behavior shifts between model versions.
• The mastery gates are strong defaults, not hard guarantees. They are rules the model is told to follow, not a lock in software. Spend a session pushing for answers and you will probably get some.
• The tutor can be wrong about the subject. It runs code and searches sources to verify what it can, and it is told to say when something is unverified — treat the rest as a claim to check.
• A text tutor cannot certify a physical skill. For an instrument, pronunciation, welding, anything perceptual, it says so during the interview and certifies the knowledge layer only.
• Long sessions drift. The documented failure mode for AI tutors is sliding from tutoring back into answering. Short sessions are better against this, and better for spacing anyway.

Uninstall / where is my data

Remove the plugin from inside Claude Code:

/plugin uninstall tutor@claude-tutor
/plugin marketplace remove claude-tutor

If you copied the skills (Option 3), delete the five directories you copied:

rm -rf ~/.claude/skills/{teach,quiz,exam,review,progress}

'teach','quiz','exam','review','progress' | ForEach-Object { Remove-Item -Recurse -Force "$HOME/.claude/skills/$_" }

Your progress survives all of that. It lives in ~/.claude/tutor/, which belongs to you rather than to the plugin: uninstalling, removing the marketplace, and deleting the clone all leave it untouched. Copy that folder to back it up or to carry it to another machine. Delete it to start over from zero — nothing else holds a copy.

Design inspirations

These products work, and this plugin is grounded in the same learning-science literature they draw on.

• boot.dev — you can't advance without doing; bite-sized concepts, then integrative projects; Socratic AI mentor.
• Execute Program — retention itself gates progression; lessons unlock only after you've reviewed their prerequisites.
• Khan Academy — mastery levels per skill; mixed-skill challenges force spaced, interleaved review.
• Duolingo / Codedex — tiny sessions, streaks as consistency information, delight matters.

FAQ

Which languages? The tutor teaches in whatever language you write to it. The skill files are English; your lessons don't have to be.

Where's my data? In ~/.claude/tutor/, as plain JSON and Markdown. The two sections above cover what leaves your machine and what an uninstall does to it.

Can I have multiple courses? Yes — each gets its own directory under ~/.claude/tutor/courses/.

It refuses to just give me the answer. Bug? Intended. See Bastani et al., PNAS 2025 above. It will walk you through the full solution after you have genuinely attempted it and climbed the hint ladder, and then hand you a fresh problem on the same principle.

License

MIT