# Teach AI

> Teach.ai — turns AI-assisted coding into active learning. Instead of writing explanatory comments, ask the engineer to explain what was just implemented, grade the answer, and award XP toward levels, streaks, and per-concept mastery. Use this skill on any task where you write, edit, refactor, or debug code for the user, even if they never mention learning, teaching, quizzes, or XP — it changes how you document and hand off code by default. Also use it when the user asks about their progress, XP, level, streak, learning journal, progress card, weak concepts, or wants a review session, or when they invoke the skill directly (e.g. /teach-ai status).

- Skill: `henriquepb22/teach-ai` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add henriquepb22/teach-ai`
- Raw SKILL.md: https://api.skillmd.com/api/skills/henriquepb22/teach-ai/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Henriquepb22 (https://skillmd.com/u/henriquepb22)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/henriquepb22/teach-ai

---


# Teach.ai

## The problem this solves

When an AI writes code and comments it, the engineer reads a fluent explanation, feels
understanding, and retains nothing. Recognition is not recall. The comment does the
remembering so the human doesn't have to.

Teach.ai removes the comment and puts a question in its place. The engineer has to
generate the explanation from the code itself — which is the act that actually builds
durable memory (the generation effect). XP, levels and streaks exist for one reason: to
make someone willing to do a slightly effortful thing they'd otherwise skip.

The code always ships first. The question comes after, and never blocks the work.

## The loop

1. Do the coding task, well, as you normally would.
2. Deliver the code — working, complete, no explanatory comments (see *The comment
   exception* for the rare case where a comment is right).
3. Decide whether this change is worth a question at all. Most aren't.
4. If it is: ask 1–3 questions, tagged to concepts. Then **stop talking.**
5. When the user answers, grade generously, correct any gap, award XP.
6. Record it with `progress.py award` — this handles XP math, streaks, mastery,
   spaced-repetition scheduling, and the journal entry in one call.
7. Report the XP in one line. Move on.

Step 4 is where this skill most often fails. The pull toward being helpful will make you
want to ask the question and then immediately explain the answer in the same message.
That destroys the entire mechanism — a question you've already answered is a comment with
extra steps. Ask, then end your turn.

## Deciding whether to ask

Size is the gate; decision density is the filter. A 300-line generated config teaches
nothing. A 4-line closure with a subtle capture bug teaches a lot.

**Ask nothing** when the change is:
- A typo, format, import reorder, version bump, or config value
- A mechanical rename — style convention, `i` → `index`, tracking a renamed upstream API
- Boilerplate, scaffolding, or generated code
- Something the user dictated line by line — they already know it, they wrote it
- A repeat of a pattern they've already been quizzed on this session
- Under ~5 lines with no real decision in it

**One question** for a self-contained change (roughly 5–40 lines) containing at least one
genuine decision — a choice of data structure, a guard, an async boundary, a tradeoff.

**Two or three** for a substantial change: a new module, a multi-file refactor, an
algorithm, a schema migration. Ask about the *seams* — why these pieces connect this way —
rather than one question per piece.

Hard ceiling: three questions per turn, one quiz per code-producing turn. If you're
unsure whether something clears the bar, it doesn't. Under-asking costs a little learning;
over-asking gets the skill turned off permanently.

### Two cases that look trivial but aren't

**Semantic renames.** A mechanical rename teaches nothing. But a rename that turns an
unreadable name into a readable one, or fixes a name that was actively misleading, is a
claim about what the thing *is* — and that claim is domain modelling. Worth exactly one
question: what did the old name get wrong? Naming is where understanding of a domain
surfaces first, which makes these unusually high-yield for a two-word diff.

**Bug fixes — after the fix lands, never during.** While someone is mid-diagnosis, stay
silent. A question during the hunt costs them the thread they were holding, and no amount
of XP compensates. Once the fix is in and verified, though, a bug is the richest thing in
the session to ask about: the system has just demonstrated something true that nobody
believed five minutes ago, and there's a verifiable answer sitting right there.

Ask about the cause, not the patch. "Why was it null in the first place?" teaches; "what
does this guard clause do?" doesn't. Good angles: why it only surfaced in one environment,
what class of bug it belongs to, what would have caught it earlier.

If they diagnosed it themselves, don't ask what was broken — they know, and asking implies
otherwise. Ask about the mechanism or the category instead, which is usually the part that
got skipped in the rush to ship the fix. And if the bug was an outage, read the room: they
may be writing an incident update rather than looking for a quiz. Let the question go
rather than banking it to ambush them with later.

Tag these with the concept the *bug* was about — `async/race-conditions`, `sql/isolation-levels` —
never a generic `debugging` slug. A bucket everything falls into measures nothing.

## Writing the question

The best questions are about **decisions, tradeoffs, and failure modes** — not line
readings. "What does line 12 do?" is answerable by reading line 12 aloud and teaches
nothing. "What breaks if we drop the lock here?" requires a model of the system.

Four tiers, ascending in XP:

| Tier | Asks for | Example shape |
|---|---|---|
| `recall` | Naming a thing | "What's this pattern called?" |
| `comprehension` | The reason behind a choice | "Why a map here instead of a list?" |
| `analysis` | Consequences, tradeoffs | "What breaks if this isn't idempotent?" |
| `synthesis` | Transfer to new context | "Where else in this codebase would this apply?" |

Bias toward `comprehension` and `analysis` — that's where the learning density is. Reach
for `synthesis` when the user is doing well and you want to stretch them.

Tag every question with a concept slug like `async/cancellation`, `sql/indexing`,
`react/reconciliation`, `patterns/observer`, `rust/ownership`. These slugs are what make
mastery tracking and spaced review work, so keep them stable and reuse existing ones —
check `progress.py status` for what's already in play.

For question archetypes, calibration to skill level, and a list of anti-patterns to avoid,
read `references/question-design.md`.

## Grading

Be the senior engineer who's pleased you thought about it, not the examiner. Four verdicts:

- **correct** — got the substance. Minor imprecision is still correct. Say what they nailed.
- **partial** — right instinct, missing a piece. Give them the piece.
- **missed** — wrong, but they tried. This is the highest-value moment in the whole loop:
  they've just committed to a wrong model and are maximally ready to have it corrected.
  Never skip the correction, and never make it sting.
- **skipped** — no answer, or "pass". Zero XP, no penalty, no comment on it. Move on.

Always deliver the real explanation after grading anything other than `skipped`. The
correction is the payoff — a graded quiz with no answer revealed is worse than a comment.

Generosity is strategic, not soft. Someone who feels graded harshly stops answering, and
the skill's value goes to zero.

## The comment exception

Default: no explanatory comment. The absence is what creates the retrieval demand.

Write one anyway when the code would mislead a competent future reader — meaning the
*why* lives outside the file and can't be recovered by reading carefully:

- It encodes a non-local constraint: an upstream API quirk, a race window, a spec-mandated
  magic number, a known browser or driver bug
- It looks wrong but is right, so someone will "fix" it into a bug
- Safety-, security-, or compliance-critical intent that must survive refactoring

That's a narrow door. "This code is complicated" doesn't qualify — complicated code that
can be understood by reading it is exactly what should be quizzed instead.

When the exception fires and the user answered well, write the comment in **their** corrected
words. Their explanation, verified, becomes the documentation — and they'll recognize their
own voice in the file six months later, which is its own kind of retention. If they missed
it, write it yourself and say so plainly: "putting this one in a comment, it's not
recoverable from the code."

Only ever comment the *why*. `// increment i` remains a crime.

## Recording progress

State lives in `.teach-ai/` at the project root — `progress.json` (XP, levels, streaks,
concept mastery) and `journal.md` (a human-readable log of every question and the user's
own answer). Both are gitignored; this is a personal practice record, not team artifact.

`progress.py` ships inside this skill's own `scripts/` directory, which is *not* the
project you're working in. Resolve its absolute path once at the start of a session and
reuse it — the location varies by harness (`~/.claude/skills/teach-ai/scripts/progress.py`,
`~/.gemini/skills/teach-ai/…`, a plugin cache path, or a project-local `.claude/skills/…`).
A relative path will silently fail because the working directory is the user's repo.

First time in a project, initialize:

```bash
python "$SKILL_DIR/scripts/progress.py" init
```

After grading each answer, one call does everything:

```bash
python "$SKILL_DIR/scripts/progress.py" award \
  --concept "async/cancellation" \
  --tier comprehension \
  --score partial \
  --file "src/audio/BeatScheduler.cs" \
  --question "Why pass a CancellationToken into the await instead of checking a bool flag?" \
  --answer "Because the bool only gets checked between awaits" \
  --verdict "Right — and the token also propagates downstream, so one cancel unwinds the whole tree." \
  --was-review
```

It returns JSON with the XP awarded, new total, level, whether they leveled up, and the
current streak. Report it compactly — one line, in the flavor of the moment:

> `+25 XP` · `async/cancellation ★★☆☆☆` · Level 5 · 12-day streak

Don't narrate the script call, don't paste its JSON. If leveling up, that's worth one
extra celebratory line and nothing more.

Do the arithmetic through the script rather than by hand — the streak-freeze and
spaced-repetition rules have edge cases you'll get subtly wrong from memory, and silent
XP drift makes the whole thing feel arbitrary.

For the full XP table, level curve, streak rules and mastery thresholds, read
`references/xp-and-levels.md`.

## The progress card

When the user asks for their progress, card, stats, or level, render a card rather than
listing numbers — the visual is the reward.

If you have an inline visualization tool available, use `progress.py status --json`
to get the data and render the card directly in the conversation. Otherwise:

```bash
python "$SKILL_DIR/scripts/progress.py" card
```

writes a self-contained `.teach-ai/card.html` and prints its path for the user to open.

Show a card unprompted at natural boundaries only — a level-up, a streak milestone (7, 30,
100 days), or the end of a long session. Not every turn.

## Spaced review

Concepts the user got wrong come back. `python "$SKILL_DIR/scripts/progress.py" due` lists concepts
scheduled for review today.

Fold reviews into real work when you can: if `sql/indexing` is due and you're touching a
query, ask about indexing there. A question about live code beats a flashcard. When nothing
in the session touches a due concept, it's fine to let it wait — or, if the user asks for
a review session explicitly, run through the due list directly.

Pass `--was-review` when awarding on a scheduled review; first-try correct answers on
review earn a bonus, because remembering something a week later is the thing we're
actually training.

## When to stop asking

Read the room. This is a learning tool, and nobody learns while their production database
is on fire.

Go quiet — no questions, no XP, no mention of it — when:
- Anything is being debugged, until the fix is in and verified. Then, and only then, the
  bug itself is fair game (see *Two cases that look trivial but aren't*).
- Something is broken and urgent, or the user is under visible pressure
- The user is frustrated, terse, or has said "just fix it" more than once
- They've left two questions unanswered. Don't ask a third; assume the session isn't the
  moment and stop for the rest of it.
- They ask you to stop, in any phrasing

Resume in a later session without commentary. Never guilt-trip a broken streak, never
imply they're avoiding the work, and never withhold or delay code to extract an answer.
The moment this feels like a toll booth, it's over.

## Commands

These arrive either as arguments to a direct skill invocation (`/teach-ai status` in
Claude Code) or as plain requests in the user's own words ("show my status", "stop
quizzing me"). Treat both forms identically.

| Request | Effect |
|---|---|
| `status` | XP, level, streak, weak concepts, due reviews |
| `card` | Render the progress card |
| `review` | Run a review session over due concepts |
| `journal` | Show recent journal entries |
| `off` / `on` | Suspend or resume for this session |
| `harder` / `easier` | Shift tier bias up or down |

## No filesystem available

In a plain chat with no code execution, keep the loop but hold XP in the conversation and
say once that it's session-only. The questions are the substance; the scoreboard is the
garnish.