Claude Generates So Much — Here's How I Actually Keep Up

[_Dimitri_]

Claude Generates So Much - Here's How I Actually Keep Up

AI is producing an almost comical amount of output these days. In a single session, Claude can scaffold a feature, write the tests, refactor two files, explain the architecture, and suggest three follow-up improvements — all before you've finished your coffee. It's genuinely impressive. It's also genuinely hard to follow.

I kept running into the same pattern: a long session ends, something real was built, and I broadly understood what it does — but the why behind the design decisions, the trade-offs that were made, the subtle things that matter when the code eventually breaks? Hazy at best. I'd scroll back through the chat, skim a few explanations, tell myself I'd review it properly later. I never reviewed it properly later.

So I built a Claude Code skill that turns any session — or any topic — into a short, focused, interactive learning session. The kind where you actually have to demonstrate understanding before moving on. It's called teach-me.

You run it right after a session while the context is still fresh: /teach-me this PR, /teach-me what we just built, /teach-me the migration pipeline. It works just as well for any concept you want to properly understand — not just things Claude built for you.

---

The problem with asking AI to teach you things

Here's the thing about reading a great explanation: it feels like understanding. The words make sense. The logic tracks. You nod. You say "ah yes, exactly." You close the tab. Two hours later a colleague asks you about it and you stare at them like they just asked you to explain quantum physics in Klingon.

This is not a Claude problem. It's a cognitive load problem. It's the same reason you can read a textbook chapter and feel smart, then fail the exam. Passive reception isn't learning. Your brain files "I saw this" next to "I understand this" - and those are two completely different drawers.

The standard AI tutoring loop goes like this:

1. You ask Claude to explain something
2. Claude writes a wall of text in the chat
3. You scroll through it
4. You say "thanks"
5. You forget 90% of it within the hour

I'm being uncharitable. But only a little. The underlying issue is that nothing in this loop requires you to do anything with the information. And things you don't do anything with don't stick.

The idea: an AI that refuses to move on

I wanted Claude to teach me the way a good engineer onboards a junior: not just explaining, but checking. "Okay, in your own words - what does this component actually do?" And then waiting for the answer. And then filling in exactly the gaps that are missing, not re-explaining everything from scratch.

The teach-me skill turns any topic into a structured three-phase learning session with actual gates you have to pass before moving on.

The three phases are always:

1. The Problem - why does this thing exist? what was hard before it?
2. The Solution - why this specific approach? what were the design decisions?
3. Broader Context - why does it matter? what else does it touch?

Before each phase, Claude asks you to explain your current understanding. It takes what's right and fills in exactly what's missing. Then it generates a styled HTML lesson file that opens in your browser. You read it, take a quiz, and report your score back in chat. Score under 80%? Claude reteaches the specific concepts you missed - and a "Retry quiz" button in the browser resets the quiz without regenerating the whole file. Score over 80%? You advance. No skipping. Not even if you say "I get it, trust me."

"Never advance a phase without passing the gate - not even if the user says 'I get it, move on.'"
- literally a rule in the skill's source code

I built that rule in specifically because I knew I would try to talk my way past it.

What an actual session looks like

I ran a session on the skill itself - very meta, I know - to test the Full mode. I typed:

/teach-me this session

Claude asked which mode: Full mode (HTML lesson in browser) or Simple mode (chat only). I picked Full.

Then came the restate gate. Before generating anything, Claude asked me to explain in my own words why the original chat-only skill fell short. My answer was roughly: "it was not fancy enough, humans learn better with visually appealing materials."

Claude took what was right (visual structure helps) and filled in what I missed: the cognitive load framing (reading prose in chat requires your brain to parse layout and content simultaneously), the AskUserQuestion limitations (4-option cap, modal blocking, no persistence), and the lack of session persistence. Two sentences of targeted gap-fill instead of a five-paragraph re-explanation.

Then it generated phase-1.html and opened it in my browser. The lesson had structured sections, an "Explain it simpler" toggle (ELI5 / ELI14 / ELI Intern), a sidebar tracking which concepts I was covering, and a 4-question quiz at the bottom.

I scored 2/4. Missed Q2 and Q4.

I reported back in chat: "Score: 2/4. Missed: Q2, Q4"

Claude reteached those two concepts in a short paragraph. No HTML regeneration. No waiting for a new file to open. I clicked "Retry quiz" in the already-open browser tab, got fresh questions on the same page, scored 3/4. Passed.

The HTML lesson format

The lesson pages are self-contained HTML files — no server, no build step, no npm. Just a file you can open today and revisit six months from now.

Each page has:

• A header with the topic name, phase label, and a three-dot progress indicator
• A two-column layout: lesson content on the left, a sticky "Concepts this phase" sidebar on the right
• Support for code blocks and inline diagrams
• An "Explain it simpler" accordion with three tabs: ELI5, ELI14, ELI Intern
• A quiz section at the bottom — same column width as the lesson
• A "Retry quiz" button that resets JS quiz state in-browser without reloading the file
• A "Copy score to clipboard" button so you can paste your result straight into chat

Sessions are saved in teach-me-sessions/{slug}-{YYYYMMDD}/ alongside a session.md checklist. If you close Claude Code and come back tomorrow, the skill detects the existing session and asks if you want to resume or start fresh.

How it works under the hood

Claude Code skills are Markdown files with YAML frontmatter. That's it. No SDK, no framework, no deployment. You put a SKILL.md in ~/.claude/skills/teach-me/, and the skill becomes available as /teach-me in any Claude Code session.

The skill file contains:

• A description of the full flow as a Graphviz dot diagram (Claude can read these)
• Explicit rules for quiz generation — never put the correct answer at index 0, vary positions, explain why wrong answers are wrong
• Step-by-step instructions for each phase with exact bash commands to open the HTML
• A "Common Mistakes" table listing things Claude would naturally do wrong — like skipping mode selection or advancing without a passing score

The HTML template lives alongside the skill. Claude reads it as reference and generates the actual lesson file from scratch, filling in real lesson content and quiz data per topic. The quiz engine is about 80 lines of vanilla JS.

The whole thing — skill file plus template — is around 400 lines total. No dependencies.

The reteach loop

When you fail a quiz:

1. Report score and missed questions in chat
2. Claude reteaches those specific concepts — in chat, concisely
3. Click "Retry quiz" in the open browser tab (JS resets state, no file reload)
4. Repeat up to 3 total attempts
5. After 3 attempts without passing: Claude offers to re-explain from scratch, or you move on voluntarily

The 3-attempt cap exists because indefinite retry loops are demoralizing and usually mean the lesson needs restructuring, not more retaking. During my session, Phase 3 hit the cap — I kept missing a question about the "static HTML output pattern." The skill invoked the cap, offered me the choice, I said "move on," and we finished the session. No judgment. The checklist marked it done anyway.

The restate gate

The gate before each phase is the part that feels most like actual learning. You have to say something first. Even if it's wrong. Even if it's "I have no idea." Claude then calibrates the explanation to exactly what you're missing — instead of re-explaining things you already know.

Try it yourself

Some topics it works well on:

• /teach-me <git commit SHA> — understand what a change actually did and why
• /teach-me event-driven architecture — concepts, not just definitions
• /teach-me this PR — onboard yourself to someone else's design decisions
• /teach-me OAuth2 authorization code flow — the kind of thing you look up every six months
• /teach-me why we deprecated the old middleware — organizational context, not just code

Two modes are available. Full mode generates HTML lesson files per phase (the experience described in this post). Simple mode stays entirely in chat — useful when you want a quick review without opening a browser.

No dependencies for teach-me. Unlike some skills in the repo that require MCP servers or external tools, teach-me works with a vanilla Claude Code installation. Clone, symlink, restart.

What I learned building it

The most interesting part wasn't the skill itself — it was running a teach-me session on the skill's own construction as a live test. Watching Claude enforce the gates on content I'd written was both gratifying and slightly humbling (I failed the Phase 3 quiz twice, as documented above).

A few things I'd do differently next time:

The highlighted-section approach for reteaching was the wrong abstraction. My first version regenerated the HTML file after each failed quiz, adding yellow highlights to the sections you missed. This cost ~2000 tokens per regeneration, added latency, and was solving the wrong problem. The real issue is understanding, not visibility. Reteaching in chat is cheaper, faster, and forces Claude to synthesize rather than just redisplay.

Layout bugs in templates are invisible until you actually use the template. I shipped the template with the quiz outside the lesson column, so the quiz was wider than the content. Classic "looks fine in isolation" bug. Running a real session caught it immediately.

The 3-attempt cap is important. Without it, a badly-written quiz question can trap a learner indefinitely. The cap forces a human judgment call — either slow down and restructure, or acknowledge this concept needs more time and come back to it. Both are valid outcomes.