agent-teacher

Why

I read AI papers all the time, and the gap between "skimmed it" and "got it" is largest when the concept is dense — group-relative advantage in GRPO, expert routing in MoE, attention tiling in FlashAttention. The default LLM explanation hits one of two failure modes: prose with no code to anchor it, or code buried under 60 lines of model and dataloader setup before the actual algorithm appears.

AgentTeacher gives it a shape: every concept gets the same six-part spine — intuition, example, walkthrough, trap, pointers, test questions — and the example is either a 10-line runnable REPL snippet or PyTorch pseudocode with shape annotations on every line that matters. Once the structure is locked in, the quality of explanations levels up the moment the model stops improvising.

Built primarily for AI/ML concepts: training algorithms (GRPO, PPO, DPO, RLHF), architectures (MoE, FlashAttention, Mamba, attention variants). Works the same on general programming concepts when needed — closures, generators, channels, ownership.

See it

The actual frozen output from running the skill on two AI/ML concepts:

Each answer comes with a lightweight pseudocode file (grpo-pseudocode.py, moe-pseudocode.py) so you can open the code in an editor with syntax highlighting while reading the explanation.

Usage

Claude Code

npx skills add JackyYang258/agent-teacher -a claude-code -g -y

Claude Code plugin marketplace (requires Claude Code v2.1.142+)

/plugin marketplace add JackyYang258/agent-teacher
/plugin install agent-teacher@agent-teacher

Generic agents (Codex, OpenCode, Pi, and other tools that read from ~/.agents/)

npx skills add JackyYang258/agent-teacher -a '*' -g -y

Claude Desktop

Download agent-teacher.zip, open Customize > Skills > "+" > Create skill, and upload the ZIP directly (no need to unzip). The ZIP is ~45KB.

Local development

ln -s /path/to/AgentTeacher ~/.claude/skills/agent-teacher

The skill auto-triggers from natural requests, no slash command needed. Example prompts:

• English: explain GRPO / what is mixture of experts / teach me FlashAttention with code / how does PPO clipping actually work
• 中文: 讲一下 GRPO / MoE 怎么路由 token / 教我 FlashAttention 的 tiling 思路 / Python 的 GIL 到底是什么

The spine

The spine has six parts; each has its own job.

Two example modes:

• Mode A — runnable. Language features, small algorithms, APIs. 5–20 line REPL snippet, prints intermediate state, no external deps.
• Mode B — structured pseudocode. Architectures (Transformer, MoE, Mamba), training algorithms (GRPO, PPO, DPO), kernel concepts (FlashAttention, paged attention). Real PyTorch syntax with scaffolding dropped, shape annotations on every line that matters, the difference from a related concept always visible. File auto-written to /tmp/<concept>-pseudocode.py for editor viewing.

Full per-layer playbook: references/teaching-method.md. Code style rules: references/code-style-for-teaching.md. Concept → language mapping: references/concept-to-language.md.

Design

Not a tutorial generator; a constraint system for technical explanations. Documents should read as composed lessons, not improvised dumps.

Code language is picked per concept: PyTorch pseudocode for architectures / training-algos, Python for general CS and algorithms, Go for channels / goroutines, Rust for ownership / borrowing, C for pointers / memory, JavaScript for DOM / event loop, TypeScript or Haskell for type systems / monads. Full mapping in references/concept-to-language.md.

Eight optional enrichments. When the concept's nature warrants, the spine opts into up to five extras: math tier (canonical formula or Big-O recurrence), state tracking (tensor shapes for DL / participant state for protocols / data trace for algorithms), design rationale ("why √d and not √2d", "why exponential backoff"), cousin matrix (BN vs LN, GRPO vs PPO, TCP vs UDP), prerequisite + variants map, classic misconception list, visualization (heatmaps, state machines, sequence diagrams), and invariants the concept guarantees (heap property, Raft safety properties, BST invariant). Each fires only when the concept warrants. The framework was tuned for DL/ML but several modules apply across CS: data structures, distributed protocols, complex algorithms. Full decision rules and per-module playbook (DL and non-DL examples) in references/enrichments.md.

Support

• If AgentTeacher helped you, give it a star or share it.
• Concept treatments that feel off? Open an issue or PR.

License

MIT License. Worked examples in assets/examples/ are illustrative and may be used or modified freely.