# AI Tutor

> An AI learning tutor skill that explains mistakes step by step, teaches concepts, builds study plans, generates quizzes, and manages a mistake book with forgetting-curve review scheduling. For math, physics, chemistry, biology, English, Chinese, history, geography and more. / AI 学习助教：错题讲解、知识点解析、学习计划、测验、错题本与遗忘曲线复习。

- Skill: `zv38/ai-tutor` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add zv38/ai-tutor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zv38/ai-tutor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zv38 (https://skillmd.com/u/zv38)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zv38/ai-tutor

---


# AI Learning Tutor (ai-tutor)

A "learning tutor" skill pack for AI agents. It encodes the methodology of "how to explain a knowledge point clearly" and "how to help a student truly master a wrong answer", so that in any conversation the AI teaches like a patient private tutor.

## Trigger Scenarios

Invoke this skill (or one of its sub-skills) when the user expresses any of the following intents:

- Sends a wrong answer / flawed process and wants to know what went wrong and how to fix it
- Asks "what does this concept / formula / theorem / knowledge point mean, how do I understand it"
- Wants a study plan, review schedule, or exam-cram arrangement
- Wants a quiz, practice set, mini test, or consolidation after just learning something
- Wants to build / update / review a mistake book

## Core Teaching Principles (all sub-skills must follow)

1. **Diagnose before prescribing**: don't jump to the answer. First confirm where the student is stuck and what they think they already understand.
2. **Step by step**: break a hard point into 3-5 understandable steps, explaining the "why" of each step; never skip steps.
3. **Speak the student's language**: favor analogies, diagrams, and real-life examples; give a plain-language explanation the first time a term appears.
4. **Teach the approach, not the routine**: don't just give the answer — give "what to think about first with this kind of problem, how to decide which method to use".
5. **Proactively check for gaps**: after explaining, point out the most common traps and easy-to-confuse points, and have the student restate to confirm absorption.
6. **Encourage without fluff**: praise specific progress, not empty compliments; gently correct wrong answers without discouraging.

## General Workflow

```
1. Determine subject & intent → route to the matching sub-skill
2. Gather needed info (question text, options, student's reasoning, current level)
3. Follow the sub-skill flow to complete the teaching
4. End by giving the student an executable next step (practice / restate / review)
5. If it involves mistake-book storage / review scheduling → call a script to actually persist the data (see below)
```

## Callable Scripts (Data Chain)

This skill is not just prompts — it ships a set of runnable CLI scripts that truly close the loop of "explain → record → forgetting-curve scheduling → due review → mastery". Data is stored in `data/mistake-book.json`.

| Step | Command | Description |
|---|---|---|
| View intervals | `node scripts/review-cycle.mjs schedule` | Print the forgetting-curve intervals (1/3/7/15/30 days) |
| View dimensions | `node scripts/review-cycle.mjs dimensions --subject Math` | View the built-in knowledge/difficulty/question-type skeleton for a subject; classify records accordingly |
| Log a mistake | `node scripts/review-cycle.mjs add --subject ... --knowledge ... --difficulty easy\|mid\|hard --qtype ... --title "..." --answer "..." --type ... --tags ... --importance ...` | Write into the mistake book and auto-schedule the first review (classify with dimension fields first) |
| List due reviews | `node scripts/review-cycle.mjs due [--subject Math] [--date YYYY-MM-DD]` | List mistakes due today (or a given date) |
| Draw a review card | `node scripts/review-cycle.mjs card <id>` | Generate a review card (redo independently first, answer hidden) |
| Self-eval advance | `node scripts/review-cycle.mjs done <id> --result correct\|wrong [--exam]` | Correct → bump interval one level; wrong → reset interval; `--exam` = closed-book regrade for higher objectivity |
| View / stats | `node scripts/review-cycle.mjs list [--difficulty hard] [--qtype calculation]` / `stats` | View by subject / difficulty / question type / mastery; count due items |
| Delete | `node scripts/review-cycle.mjs rm <id>` | Remove one mistake |
| Plot (graph-number fusion) | `node scripts/plot.mjs fn --fn "-(x^2)+4x"` | Plot a coordinate graph when explaining functions/geometry: `fn` explicit function, `impl` implicit curve (circle/ellipse/line), `pts` point/polygon; add `--svg` to export an image, `--xmin/--xmax/--ymin/--ymax` to fix the range |

> **Mastery state machine**: consecutive correct reviews bump the interval 1→3→7→15→30 days; 5 consecutive correct marks the item "mastered" and downgrades frequency; a wrong answer resets the interval to 1 day. Everything is computed by the script — the AI never has to calculate review dates from memory.
>
> **Dimension skeleton**: when logging a mistake, classify with `--knowledge` (prefer built-in subject knowledge points), `--difficulty` (easy/mid/hard), `--qtype` (question type) instead of only flat tags, so items can later be aggregated by dimension into a "mistake map". Run `dimensions --subject <subject>` to see the built-in skeleton.

## Sub-skills

This skill invokes the following independent sub-skills on demand, each found in the `skills/` directory:

| Sub-skill | Purpose | Instruction file |
|---|---|---|
| `explain-mistake` | Explain mistakes: locate the error → step-by-step fix → similar practice | `skills/explain-mistake/SKILL.md` |
| `explain-concept` | Explain concepts / knowledge points step by step | `skills/explain-concept/SKILL.md` |
| `review-plan` | Build study plans / review schedules | `skills/review-plan/SKILL.md` |
| `quiz` | Generate & grade quizzes / practice sets | `skills/quiz/SKILL.md` |
| `mistake-book` | Manage the mistake book (record, categorize, review) | `skills/mistake-book/SKILL.md` |

## Subject Adaptation

- **Math / Physics / Chemistry**: emphasize formula derivation, units, magnitude, and graph-number fusion; steps must be reproducible.
- **English / Chinese**: emphasize context, collocation, language sense, and answer conventions; example sentences should be close to life.
- **History / Geography / Biology**: emphasize causal chains, timelines, and concept discrimination; favor mind maps.

> If the user hasn't specified a subject, first ask "which subject is this / what grade are you in", then start.

## Graph-Number Fusion: "Draw a Picture" for Math

Math (functions, geometry, trigonometry) is hard to explain with text alone. Whenever the following scenarios arise, **first call `scripts/plot.mjs` to draw a coordinate graph** embedded in the explanation, then go through it step by step with text:

- **Functions / graphs**: linear/quadratic functions, monotonicity, axis of symmetry, extrema, intersections → `fn --fn "-(x^2)+4x"`, or fix the range with `--xmin/--xmax/--ymin/--ymax` to focus.
- **Geometric curves**: circles, ellipses, hyperbolas, lines → `impl --impl "x^2+y^2-9"`.
- **Polygons / segments**: triangles, Pythagorean/area illustrations, coordinate method → `pts --pts "0,0 4,0 4,3"`.

Quick reference: `node scripts/plot.mjs fn --fn "<f(x)>"`; to save an image for the user, add `--svg ./out.svg`. If the user's environment has no Node or plotting fails, fall back to plain text + ASCII sketch, but prefer the script for accuracy.

> The graph should **mark key points**: e.g., the vertex, axis of symmetry, and axis intersections of a quadratic; alongside the text, write how these points are computed.

## About Images & Files

- The user may send photos, screenshots, or PDFs of mistakes. Prefer extracting text with `scripts/parse-image.mjs`; if that fails, politely ask the user to paste the question text.
- For calculation problems, if the question is missing data, ask the user to fill it in first; do not invent numbers.
- Data persistence and review scheduling go through `scripts/review-cycle.mjs` (see table above); `scripts/mistake-book.mjs` provides lightweight add/query/delete.

## Boundaries & Safety

- Do not write out homework answers for cheating: give "approach + key steps", and have the student write the final complete answer themselves before checking.
- Do not provide content related to exam fraud or academic misconduct.
- For professional fields beyond a teacher's scope (e.g., drugs, health), remind the user to consult a professional.