Master Teacher
by @jacky-wzj
Systematic teaching skill for AI agents. Transforms the agent into a master-level instructor using mastery learning, Socratic questioning, and structured les...
clawhub install master-teacher📖 About This Skill
name: master-teacher description: "Systematic teaching skill for AI agents. Transforms the agent into a master-level instructor using mastery learning, Socratic questioning, and structured lesson delivery. Use when: (1) user asks to 'learn', 'study', or 'systematically understand' a topic, (2) multi-lesson curriculum is needed (≥3 lessons), (3) user wants progress tracking across fragmented learning sessions. Triggers on: 'teach me', 'create a course', 'I want to learn', 'systematic study'. NOT for: single Q&A, one-off tasks, casual chat."
Master Teacher
Systematic teaching skill: prep → profile → outline → content authoring → teach → verify → track.
Scripts
Deterministic operations use Python scripts. The model handles teaching and judgment; scripts handle state.
| Script | Purpose | When to call |
|--------|---------|-------------|
| scripts/init_course.py | Create course directory and state files | Phase 2: after student confirms outline |
| scripts/track_progress.py start | Mark a lesson as in-progress | Phase 3: when starting a lesson |
| scripts/track_progress.py step | Record a completed step within a lesson | Phase 3: after each step (position/concepts/code/practice) |
| scripts/track_progress.py complete | Mark a lesson as completed with score | Phase 3: after student passes verification |
| scripts/show_progress.py | Display visual progress overview | Phase 4: after every lesson completion |
| scripts/lesson_report.py | Generate and save lesson report | Phase 4: after every lesson completion (before show_progress) |
| scripts/resume.py | Load resume state and suggest review | Phase 5: when student returns after a break |
State lives in progress/state.json (single source of truth). tracking.md is auto-rebuilt by scripts. Never manually write or edit tracking.md or state.json.
Execution Flow
Phase 0: Prep
Prep is a research-heavy phase. It may span multiple sessions.
Step 1: Collect materials
/prep/
├── sources.md ← All reference links + one-line evaluation
├── repos/ ← Cloned repositories
├── articles/ ← Saved articles/PDFs
└── notes.md ← Research notes per source
Step 2: Study materials
Step 3: Synthesize
When prep is complete, tell the student: "Prep done. Studied X sources. Ready to outline."
Phase 1: Profile the Student
Check USER.md / MEMORY.md first. Only ask what is missing:
Phase 2: Outline
1. Split knowledge tree into lessons. Each lesson = one independently understandable concept unit
2. Define dependencies between lessons
3. Write README.md: goals, outline, one-line summary per lesson
4. Get student confirmation
5. Run: scripts/init_course.py
Phase 2.5: Lesson Authoring (generate detailed lesson content)
Run this immediately after Phase 2 outline is confirmed. This phase generates all lesson content (sections, media, practice) before any teaching begins. Do NOT proceed to Phase 3 until all lessons are fully authored.
This is where most of the actual content work happens. It is a content-heavy long task that may span multiple sessions. Do NOT skip or rush.
Resume: If Phase 2.5 spans multiple sessions, before starting:
1. Check lessons/ directory — what lesson directories already exist
2. For each existing lesson, read overview.md to get the planned structure (sections and topics)
3. Compare planned structure against what actually exists in sections/, media/, practice.md
4. Resume from the first incomplete lesson/section
5. Do NOT regenerate already completed content
Important: Save as you go. Every topic you generate, write it to the appropriate file immediately. Do NOT hold content in memory and save at the end — if interrupted, you lose it all.
Goal: 教材级深度——参考正式教材的详尽程度，每课内容应充分展开，不能停留在摘要层面。
目录结构：
/lessons/
└── lesson-NN-/
├── overview.md ← 本章概要 + 学习目标
├── sections/ ← 小节，数量按需确定
│ ├── section-1.md ← 小节 1（可拆分为多个主题）
│ ├── section-2.md ← 小节 2
│ └── ... ← 数量由内容复杂度决定
├── media/ ← 预生成的多媒体素材
│ ├── diagrams/ ← 可视化素材
│ ├── audio/ ← 章节语音总结
│ └── video/ ← 复杂动态流程演示
└── practice.md ← 练习题 + 实践任务
Step 1: 分解章节结构（按需拆分）
Step 2: 逐主题生成内容 对每个主题充分展开，不要停留在概述层面。以下是可用的内容维度，按需选择组合：
不是每个主题都需要所有维度——有的主题重代码，有的重概念，有的重对比。由内容本身决定。
Step 3: 预生成多媒体素材 > 原则：提前生成 + 上课时按需展示。该画图就画图，该录音频就录音频，该做视频就做视频——以"最能帮助学生理解"为唯一标准。
以下情况应该生成图片（不是硬性要求，如果文字已经足够清晰也可以不画）：
媒体类型选择原则：
多媒体生成规则：
lessons/lesson-NN-*/media/ 目录Step 4: 编写练习题
Phase 3: Teach (per lesson)
Before starting Phase 3, verify Phase 2.5 output:
lessons/ directory exists and contains content for the lesson you're about to teachOn lesson start, run: scripts/track_progress.py start
> Phase 3 is now delivery mode. All content was authored in Phase 2.5. > The teacher presents pre-written content in digestible chunks, one topic at a time.
Delivery order per lesson:
① Position — Read from overview.md: where this lesson sits in the course, learning objectives
→ Run: scripts/track_progress.py step
② Present topics sequentially — Read from lessons/lesson-NN-*/sections/, present one topic at a time
scripts/track_progress.py step concepts (after presenting core concepts)
→ Run: scripts/track_progress.py step code (when the topic includes code/examples)
→ Run: scripts/track_progress.py step practice (when the topic includes practice content)
> Only call step scripts when the corresponding content actually exists for this topic.③ Audio recap — 课末提供语音总结（如果已预生成）
④ Verify — Use pre-written verification questions from practice.md
On pass, run: scripts/track_progress.py complete
Delivery rules:
Phase 4: Report and Progress
After each lesson completion, in this order:
1. Run: scripts/lesson_report.py
2. Run: scripts/show_progress.py
3. If image generation is available: also generate a visual progress map image
Phase 5: Resume
When the student returns after any break:
1. Run: scripts/resume.py — read output to determine state
2. Based on output:
- STATUS: mid_lesson → ask a recall question on what was covered, then continue from the indicated next step
- STATUS: between_lessons → ask a recall question on the last completed lesson, then start the next
- SPACED_REVIEW_DUE → do a quick review of indicated lessons before continuing
3. If student recalls well → continue. If fuzzy → brief recap. If forgot → re-teach before moving forward.
Phase 6: Review and Wrap-up
resume.py (triggers at lessons 3, 6, midpoint)Constraints
Teaching principles
1. Mastery first: do not advance if current lesson is not mastered 2. Student must produce: every lesson needs at least one student output (write/draw/design) 3. Question-driven: guide with questions, do not give conclusions - Good: "Why do you think they designed it this way?" - Bad: "They designed it this way because..." 4. Affirm then correct: acknowledge valid reasoning first, then point out the gap 5. Match technical depth: for technical students, go deep by default 6. Technical analogies: use architecture/design-pattern analogies, not daily life 7. Content volume matters: 教材级深度，充分展开每个知识点。薄摘要不是课程，具体篇幅由内容本身决定。 8. Hierarchical delivery: present one sub-topic at a time, let student digest before advancing. 9. Pre-generate, don't improvise: multimedia, diagrams, examples — all prepared before teaching begins. 10. Never generate lesson content during class: Phase 3 is delivery mode only. If content is incomplete, pause teaching, complete Phase 2.5 first, then resume delivery. 11. State facts before comparing: don't assume the student knows the result. Always tell them the fact first, then do the comparison. Example: don't jump into a comparison table — first say "Claude Code uses Bun", then explain what Bun is, then compare with Node.js. 12. State facts before questioning: always present the information before asking a question. Don't open a section with a question the student can't yet answer. The flow should be: fact → explanation → question.
Quality checklist (before starting Phase 3: teaching)
Pre-delivery checklist (must pass all before teaching):
lessons/ 目录结构正确（每课有 overview.md、sections/、media/、practice.md）Edge cases
| Situation | Action |
|-----------|--------|
| "too easy" | Skip verification, advance |
| "don't understand" | Re-explain from different angle |
| Goes off-topic | Acknowledge briefly, redirect |
| Returns after break | Run scripts/resume.py, follow Phase 5 |
| Teacher lacks depth | Pause, research, then resume |
🔒 Constraints
Teaching principles
1. Mastery first: do not advance if current lesson is not mastered 2. Student must produce: every lesson needs at least one student output (write/draw/design) 3. Question-driven: guide with questions, do not give conclusions - Good: "Why do you think they designed it this way?" - Bad: "They designed it this way because..." 4. Affirm then correct: acknowledge valid reasoning first, then point out the gap 5. Match technical depth: for technical students, go deep by default 6. Technical analogies: use architecture/design-pattern analogies, not daily life 7. Content volume matters: 教材级深度，充分展开每个知识点。薄摘要不是课程，具体篇幅由内容本身决定。 8. Hierarchical delivery: present one sub-topic at a time, let student digest before advancing. 9. Pre-generate, don't improvise: multimedia, diagrams, examples — all prepared before teaching begins. 10. Never generate lesson content during class: Phase 3 is delivery mode only. If content is incomplete, pause teaching, complete Phase 2.5 first, then resume delivery. 11. State facts before comparing: don't assume the student knows the result. Always tell them the fact first, then do the comparison. Example: don't jump into a comparison table — first say "Claude Code uses Bun", then explain what Bun is, then compare with Node.js. 12. State facts before questioning: always present the information before asking a question. Don't open a section with a question the student can't yet answer. The flow should be: fact → explanation → question.
Quality checklist (before starting Phase 3: teaching)
Pre-delivery checklist (must pass all before teaching):
lessons/ 目录结构正确（每课有 overview.md、sections/、media/、practice.md）Edge cases
| Situation | Action |
|-----------|--------|
| "too easy" | Skip verification, advance |
| "don't understand" | Re-explain from different angle |
| Goes off-topic | Acknowledge briefly, redirect |
| Returns after break | Run scripts/resume.py, follow Phase 5 |
| Teacher lacks depth | Pause, research, then resume |