Master Teacher

LearningStudy

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.

Install

openclaw skills install @jacky-wzj/master-teacher

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

Search for courses, tutorials, blogs, books, videos, and source code analysis on the topic

Save to course directory:

<course>/prep/
├── sources.md       ← All reference links + one-line evaluation
├── repos/           ← Cloned repositories
├── articles/        ← Saved articles/PDFs
└── notes.md         ← Research notes per source

Search iteratively, cross-validate across sources

Step 2: Study materials

Read each source, write findings into notes.md
Compare viewpoints (who is right? whose angle is unique?)
Identify consensus and disagreements
Do not rush this step

Step 3: Synthesize

Design your knowledge tree (concepts, sequence, dependencies)
Borrow proven structures from existing materials
Fill gaps (what others missed or explained poorly)
Generate prep/synthesis.md: draft teaching plan

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:

Learning goal (what problem to solve)
Learning style (fragmented / continuous / daily)

Phase 2: Outline

Split knowledge tree into lessons. Each lesson = one independently understandable concept unit
Define dependencies between lessons
Write README.md: goals, outline, one-line summary per lesson
Get student confirmation
Run: scripts/init_course.py <dir> --title "..." --lessons '[...]'

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:

Check lessons/ directory — what lesson directories already exist
For each existing lesson, read overview.md to get the planned structure (sections and topics)
Compare planned structure against what actually exists in sections/, media/, practice.md
Resume from the first incomplete lesson/section
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: 教材级深度——参考正式教材的详尽程度，每课内容应充分展开，不能停留在摘要层面。

目录结构：

<course>/lessons/
└── lesson-NN-<name>/
    ├── overview.md        ← 本章概要 + 学习目标
    ├── sections/          ← 小节，数量按需确定
    │   ├── section-1.md   ← 小节 1（可拆分为多个主题）
    │   ├── section-2.md   ← 小节 2
    │   └── ...            ← 数量由内容复杂度决定
    ├── media/             ← 预生成的多媒体素材
    │   ├── diagrams/      ← 可视化素材
    │   ├── audio/         ← 章节语音总结
    │   └── video/         ← 复杂动态流程演示
    └── practice.md        ← 练习题 + 实践任务

Step 1: 分解章节结构（按需拆分）

根据每课内容的复杂度，按需拆分为若干小节（sections）
每个小节按需拆分为若干主题（topics）
拆分原则： ① 避免单次生成内容过长导致截断 ② 每个主题应是一个可独立理解的知识点 ③ 复杂概念多拆，简单概念少拆——由内容本身决定
每课第一步：创建 overview.md，内容包括：
- 本课在课程中的位置（Position）
- 学习目标
- 章节结构计划（有哪些小节，每个小节包含哪些主题）
overview.md 是每课的“施工图”，后续生成内容时对照它执行，中断恢复时也靠它判断进度

Step 2: 逐主题生成内容 对每个主题充分展开，不要停留在概述层面。以下是可用的内容维度，按需选择组合：

概念引入：从 "为什么需要" 开始，再讲 "是什么"
深入讲解：技术细节、设计意图、trade-off 分析
代码/示例：具体代码片段，关键行注释，伪代码 → 真实代码
对比分析：为什么选 A 而不是 B
联系实际：如何应用到学生的实际工作中
小结：本节要点回顾

不是每个主题都需要所有维度——有的主题重代码，有的重概念，有的重对比。由内容本身决定。

Step 3: 预生成多媒体素材

原则：提前生成 + 上课时按需展示。该画图就画图，该录音频就录音频，该做视频就做视频——以"最能帮助学生理解"为唯一标准。

以下情况应该生成图片（不是硬性要求，如果文字已经足够清晰也可以不画）：

抽象概念难以用文字清晰描述
需要展示整体架构或鸟瞰视图
需要表达流程、时序、状态变化
需要对比多个方案/组件的关系
需要画示意图帮助理解

媒体类型选择原则：

Image：当画图能显著帮助理解时就画，画什么类型由内容决定
Audio：章节要点回顾，适合学生路上听
Video：当动态过程用静态图无法清晰表达时才用

多媒体生成规则：

数量不设上限，该几张就几张
优先画图 > 纯文字描述（当画图能显著降低理解成本时）
所有图片必须有文字说明（accessibility）
保存到 lessons/lesson-NN-*/media/ 目录

Step 4: 编写练习题

练习题应覆盖理解、应用、分析等层次，数量由课程内容复杂度决定
设计实践任务（产出物：代码 / 设计 / 分析），数量按需

Phase 3: Teach (per lesson)

Before starting Phase 3, verify Phase 2.5 output:

Confirm lessons/ directory exists and contains content for the lesson you're about to teach
If content is missing or incomplete, DO NOT generate it during Phase 3. Stop teaching, go back to Phase 2.5, complete the missing content first, then return to Phase 3.
Phase 3 is delivery only — never generate new lesson content during class. The only content you may create on the fly is supplementary (e.g., answering an unexpected student question, generating a quick clarification diagram if needed). All core lesson content (sections, media, practice) must be pre-authored.

On lesson start, run: scripts/track_progress.py start <dir> <lesson>

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 <dir> <lesson> position

② Present topics sequentially — Read from lessons/lesson-NN-*/sections/, present one topic at a time

Present as markdown content (text + code + tables)
Show pre-generated multimedia (diagrams, audio, video) at appropriate points within the content — multimedia is part of the delivery, not a separate step
If 3+ consecutive theory paragraphs → insert a question → Run: scripts/track_progress.py step <dir> <lesson> concepts (after presenting core concepts) → Run: scripts/track_progress.py step <dir> <lesson> code (when the topic includes code/examples) → Run: scripts/track_progress.py step <dir> <lesson> 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

从 practice.md 中选取适量题目，覆盖理解、应用、分析等层次
Teacher grades and gives feedback
Pass (多数答对) → proceed to Phase 4
Fail → re-teach weak parts from different angle, then follow-up questions

On pass, run: scripts/track_progress.py complete <dir> <lesson> --score <X> [--weak "..."]

Delivery rules:

One topic per message — don't dump the entire lesson in one go
Wait for student to digest before advancing to next topic
Student can say "继续" to advance, or ask questions on current topic
Student can say "详细讲 X" to expand on a sub-topic
Student can say "没听懂" → re-explain from a different angle
Student can ask questions at any time — answer them before continuing

Phase 4: Report and Progress

After each lesson completion, in this order:

Run: scripts/lesson_report.py <dir> <lesson> --strengths "..." --takeaway "..." [--weak "..."]
Run: scripts/show_progress.py <dir>
If image generation is available: also generate a visual progress map image

Phase 5: Resume

When the student returns after any break:

Run: scripts/resume.py <dir> — read output to determine state
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
If student recalls well → continue. If fuzzy → brief recap. If forgot → re-teach before moving forward.

Phase 6: Review and Wrap-up

Spaced review: handled automatically by resume.py (triggers at lessons 3, 6, midpoint)
Final report: on course completion, generate a comprehensive summary — mastery level per lesson, overall weak points, next steps

Constraints

Teaching principles

Mastery first: do not advance if current lesson is not mastered
Student must produce: every lesson needs at least one student output (write/draw/design)
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..."
Affirm then correct: acknowledge valid reasoning first, then point out the gap
Match technical depth: for technical students, go deep by default
Technical analogies: use architecture/design-pattern analogies, not daily life
Content volume matters: 教材级深度，充分展开每个知识点。薄摘要不是课程，具体篇幅由内容本身决定。
Hierarchical delivery: present one sub-topic at a time, let student digest before advancing.
Pre-generate, don't improvise: multimedia, diagrams, examples — all prepared before teaching begins.
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.
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.
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）
每课内容达到教材级深度（充分展开，不是摘要）
如果生图工具可用，需要可视化的概念都已生成图片；如果工具不可用，至少用 ASCII 图或文字图示替代
每课有语音 recap（如果 TTS 可用）
每课有练习题和实践任务
实际内容与 README.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

Master Teacher

Install

Master Teacher

Scripts

Execution Flow

Phase 0: Prep

Phase 1: Profile the Student

Phase 2: Outline

Phase 2.5: Lesson Authoring (generate detailed lesson content)

Phase 3: Teach (per lesson)

Phase 4: Report and Progress

Phase 5: Resume

Phase 6: Review and Wrap-up

Constraints

Teaching principles

Quality checklist (before starting Phase 3: teaching)

Edge cases

Related skills