code-teacher

A Claude Code skill suite that turns AI-assisted development into active language learning. Instead of passively watching Claude write Rust, Go, or Bash, code-teacher makes sure you actually absorb what's happening — so you can confidently put those languages on your resume and talk about them in interviews.

Skill Suite

The suite is made up of two skills that share a common foundation:

Skill	Purpose
code-teacher	Teach mode (passive annotations) + Quiz mode (on-demand quizzing during development)
code-teacher-review	Review mode (scan existing codebases, placement tests, quiz from real code)

Both skills read from docs/code-teacher/foundation.md for shared tier definitions, scoring rules, and annotation format.

How It Works

Teach Mode (passive)

Part of the code-teacher skill. Activates automatically during development. After writing code, Claude appends a 📚 Code Notes footnote section that explains key decisions — why it chose pattern matching over conditionals, what ownership means in this specific context, or how a Go interface differs from a C# one.

Annotations are:

• Filtered by the heuristic: "Would this trip you up in an interview?"
• Mapped to languages you already know (C#, TypeScript, SQL)
• Tapered over time as concepts repeat — it won't re-explain unwrap() for the 20th time
• Written to per-language notes files (docs/code-teacher/{language}-notes.md) for later review

Quiz Mode (active)

Part of the code-teacher skill. Triggered by saying quiz me or quiz me on [language]. Instead of generic textbook questions, quizzes pull from code actually written in your projects.

• Socratic style — asks, listens, probes deeper based on your response
• Contextual — "What does this Arc<Mutex<T>> do in cs-flythrough?"
• Tracks progress — questions scored 1 (shaky), 2 (okay), or 3 (solid); resurfaces weak areas, suggests level-ups when you're ready

Review Mode (codebase scan)

Part of the code-teacher-review skill. Designed for onboarding to an existing codebase or doing a deep learning pass on code already written. Review mode:

• Scans the codebase and identifies high-value teaching moments across all files
• Builds a work queue (docs/code-teacher/scan-results.md) ranked by learning value
• Runs a placement test on first encounter with a language to set your starting tier
• Quizzes from real code — pulls examples directly from the scanned files instead of fabricating scenarios

Activate review mode by saying review mode, scan this project, or placement test.

Proficiency Levels

Four tiers that control annotation depth and quiz difficulty across both skills:

Level	Annotations	Quiz Style
Beginner	Heavy — maps everything to known languages	Explain to yourself using analogies
Junior	Moderate — idioms and gotchas	Explain to a peer in another language
Mid	Light — advanced patterns only	Explain to a stakeholder AND defend choices
Senior	Rare — cutting-edge only	Teach a beginner, debate an expert

Levels are established by a baseline quiz on first encounter with a language, then float up or down based on quiz performance over time.

Commands

code-teacher (teach + quiz)

Keyword	Action
teach off / heads down / quiet mode	Pause Teach Mode
teach on / teach me / heads up	Resume Teach Mode
quiz me / quiz me on [language]	Start a quiz session
test me / test me on [language]	Start a quiz session
baseline quiz / baseline quiz [language]	Force a baseline assessment (even for known languages)

code-teacher-review (review + scan)

Keyword	Action
review mode / scan this project	Scan codebase and build a learning work queue
placement test / placement test [language]	Run a placement test to set your starting tier
quiz me / quiz from scan	Quiz using examples from the scanned codebase
next item / continue review	Move to the next item in the scan work queue

File Structure

.claude/skills/
├── code-teacher/
│   └── SKILL.md                          # Teach + Quiz skill definition
└── code-teacher-review/
    └── SKILL.md                          # Review + Scan skill definition

docs/code-teacher/                        # Per-repo learning state (shared by both skills)
├── foundation.md                         # Shared tier definitions, scoring rules, format
├── quiz-tracker.md                       # Proficiency levels, gaps, session history
├── scan-results.md                       # Review mode work queue (created at runtime)
└── {language}-notes.md                   # Study notes per language (created at runtime)

Design Principles

• Interview-focused — every annotation answers "why would someone ask about this?"
• Lightweight — max 3 annotations per code block, silent file writes
• Adaptive — annotation depth adjusts to your proficiency level, tapers as you learn
• Scrapable — strict markdown format enables future cross-repo aggregation
• Non-disruptive — works alongside SuperPowers, scope-lock, and other skills

Future

• code-teacher-hub — a separate repo to aggregate notes across all projects into consolidated study guides with a master quiz mode
• depth-check — companion skill for generating tiered code explanations; natural integration point with code-teacher's proficiency tiers

License

MIT

---

Support

☕ Buy me a coffee on Ko-fi

Created by Ktulue | The Water Father 🌊