ckb/.agents/skills/ckb-teach-me/SKILL.md

---
name: ckb-teach-me
description: Turn the wiki knowledge base into a personalised teaching curriculum — plan a single session or a spaced series (duration, frequency, optional calendar .ics reminders), teach one portion per session using varied techniques (Socratic questioning, analogies, worked examples, teach-back, mini knowledge checks), and track progress against the plan across calls, re-teaching weak spots before moving on. Use when the user asks to "teach me the wiki", "teach me about X", "run a teaching session", "continue my lessons", or wants a structured course built from the knowledge base rather than a one-off quiz (for that, use the `quiz` skill instead).
---

# Teach me (wiki curriculum) skill

## Purpose

Turn the wiki into a taught course, not just a lookup table or a one-off
quiz. This skill has two modes that always run in this order for a given
topic:

1. **Plan mode** (first call for a topic) — scope the material, ask
   scheduling questions, chunk the knowledge into session-sized portions,
   present the plan, save it once accepted.
2. **Teach mode** (every later call for that topic) — compare the saved
   plan against saved progress, teach the next portion using a technique
   different from last time, spot-check retention of earlier sessions, and
   update progress.

The wiki stays authoritative and read-only from this skill's point of
view — it never writes back to `wiki/`. Curricula, plans, and progress live
under `outputs/teaching/`, one subfolder per topic.

## Trigger phrases

- "teach me the wiki" / "teach me everything in the wiki"
- "teach me about X" / "I want to learn X" / "run me a course on X"
- "run a teaching session" / "continue my lessons" / "next lesson"
- "where am I up to in my lessons on X"

Do **not** use this skill for a one-off knowledge test with no curriculum
or progress tracking — that's the `quiz` skill.

---

## How to run this skill

### Step 0 — Resolve topic and existing state

1. Determine the topic from the user's phrasing. "Teach me about X" scopes
   to X; a bare "teach me the wiki" scopes to the whole KB — confirm this
   is really what they want given it may be large, and offer to narrow it
   first (e.g. "the whole wiki is quite broad — want me to scope this to a
   part of it, or build a multi-session course covering all of it?").
2. Slugify the topic (kebab-case) and look for
   `outputs/teaching/<slug>/plan.md`.
   - **Exists** → this is a **Teach mode** call. Skip to Step 5.
   - **Doesn't exist** → this is a **Plan mode** call. Continue to Step 1.
   - **Several folders look like plausible matches** for a vague topic
     (e.g. user says "continue my lessons" with more than one curriculum
     in progress) → list them (topic, sessions done / total) and ask which
     one to continue.

### Step 1 — Scheduling questions (Plan mode only)

Ask one at a time, waiting for each answer:

**Q1 — Single session or a series?**

> "Do you want this as one session, or a series of shorter sessions spread
> over time?"

**Q2 — Duration and frequency**

- If single session: "How long should the session be? (e.g. 20, 45, 60
  minutes)"
- If series: "How long should each session be, and how often would you
  like them? (e.g. '20 minutes, twice a week' or '30 minutes every
  weekday')" Also ask for a start date if they want the calendar file
  (Q3) — otherwise it's optional and can default to "starting next
  session request."

**Q3 — Calendar reminders**

> "Would you like a calendar file (.ics) you can import to get reminders
> for these sessions?"

If yes and it's a series, also ask for a preferred time of day and start
date if not already given, so events can be scheduled concretely. If it's
a single session, offer a one-off reminder event instead.

### Step 2 — Gather the material

1. Read `wiki/index.md` (and `wiki/entities/index.md`,
   `wiki/graph/index.md` if present) to find every page in scope. For a
   narrow topic, use the cascade (local `wiki/` first, then `linked/`,
   then `libs/`) same as any query. For "whole wiki", scope is every page
   under `wiki/` plus its graph.
2. Read each in-scope page in full (`tldr` first — skip the body only if
   the page turns out irrelevant on inspection).
3. **Optional web supplement** — if the wiki is thin on a subtopic that's
   clearly needed for a coherent course, you may search the web to fill
   the gap. Mark any such material distinctly as *external, supplementary*
   in the plan and during teaching — it does not carry the wiki's
   cascade authority. If the gap is substantial enough to be worth
   keeping permanently, tell the user afterwards it would be a good
   candidate for `raw/inbox/` and a proper Ingest (per the Demand-Driven
   Context rule in `CLAUDE.md`) rather than silently folding it into the
   wiki yourself.
4. Use `wiki/graph/edges.json` (or link-following if edges are sparse — same
   fallback as the onboarding-tour skill) to work out dependency order:
   foundations (`depends_on`/`uses` targets) before the concepts that build
   on them.

### Step 3 — Chunk into sessions

Order the material pedagogically (foundations → core → things that build
on it, same logic as a guided tour), then cut it into session-sized
portions against the duration from Step 1.

- Rule of thumb: roughly one wiki page or tightly-scoped subtopic per
  10-15 minutes of session time, adjusted for how dense the material
  actually is (a short stub page is quick; a long entity page with many
  facts takes longer).
- **When in doubt, add a session rather than overfill one.** A session
  that runs long or crams two unrelated topics together teaches worse than
  two clean, focused sessions. Never let a single session's plan exceed
  its stated duration on paper.
- Each session should have one clear theme/title, not a grab-bag.
- Reserve implicit room in later sessions for retention spot-checks (Step
  6) — don't plan every minute as new material.

### Step 4 — Present the plan and get acceptance

Show the session breakdown before saving anything:

```markdown
## Proposed course: [Topic]

**Format:** [N session(s) of ~M minutes] [ · every X, starting YYYY-MM-DD if series]
**Calendar file:** [Yes — will generate reminders.ics / No]

1. **Session 1 — [title]** — [1-line: what it covers, sourced from which pages]
2. **Session 2 — [title]** — ...
   ...

Sound good, or would you like the sessions rebalanced (more/fewer,
different split)?
```

Wait for explicit acceptance before writing anything. If the user wants
changes, adjust and re-present — don't save a rejected plan.

### Step 5 — Save the plan (Plan mode only, after acceptance)

Create `outputs/teaching/<slug>/plan.md`:

```markdown
---
type: teaching-plan
topic: <topic as stated>
scope: <"whole wiki" | narrower description>
session_mode: single | series
session_duration_minutes: <M>
frequency: <e.g. "twice a week" | null for single>
calendar_file: outputs/teaching/<slug>/reminders.ics | null
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
---

# Teaching plan: <topic>

## Overview
[2-3 sentences: what this course covers and why the sessions are ordered
this way.]

## Sessions

### Session 1 — <title>
- **Covers:** [pages/subtopics, as links, e.g. `wiki/entities/foo.md`]
- **Learning goals:** [what the user should be able to explain/do after]
- **External supplements:** [none | list, marked as such]

### Session 2 — <title>
...
```

Create `outputs/teaching/<slug>/progress.md` alongside it, empty of
sessions so far:

```markdown
---
type: teaching-progress
topic: <topic as stated>
plan_file: outputs/teaching/<slug>/plan.md
last_updated: YYYY-MM-DD
---

# Teaching progress: <topic>

## Session log

_No sessions taught yet._

## Next up

Session 1 — <title>.
```

If a calendar file was requested, generate
`outputs/teaching/<slug>/reminders.ics` (see Calendar file generation
below). Report the paths written and that the course is ready to start
whenever the user says so — do not start teaching Session 1 automatically
in this same turn unless the user asks for it explicitly.

### Step 6 — Teach mode: pick up where progress left off

1. Read `plan.md` and `progress.md` for the resolved topic.
2. Determine the next unit of work:
   - If the previous session's knowledge check (see below) showed weak
     spots, open this session with a short, targeted recap of just those
     weak points before moving on — don't re-teach the whole prior
     session.
   - If the previous check was very poor (roughly under half recalled),
     dedicate this whole session to reinforcing that material instead of
     advancing the plan, and note this as an inserted repetition session
     in `progress.md` (it doesn't consume a slot from the numbered plan).
   - Otherwise, teach the next not-yet-completed session from `plan.md`.
3. Pick a teaching technique **different from the one used last session**
   (rotate through the list below) so the course doesn't feel repetitive.
4. Teach the portion: pull the actual facts from the relevant wiki pages
   (plus any marked external supplements), and deliver them via the
   chosen technique. Keep it interactive — this is a taught session, not
   a wall of text.
5. Close the session with a short, informal knowledge check (2-4
   questions, open or quick-recall style) on **today's** material only.
   Judge generously, same spirit as the `quiz` skill: if the core fact
   came through even imperfectly, count it as understood.
6. Update `progress.md`: append a dated entry for this session (technique
   used, brief note on what was taught, knowledge-check result, any weak
   spots flagged for next time), update `Next up`, bump `last_updated` on
   both `progress.md` and — only if the plan's own shape changed (e.g. an
   inserted repetition session) — `plan.md`.
7. If this was the final session in the plan, say so, give a short
   overall verdict, and offer either a full-course review (can point at
   the `quiz` skill for a proper scored test) or planning a new topic.

**Teaching technique rotation** (pick one not used last time; introduce
variety, don't always default to plain explanation):
- **Socratic questioning** — lead the user to the fact via guided
  questions rather than stating it outright.
- **Analogy / storytelling** — frame the concept through a relatable
  comparison or short narrative.
- **Worked example / case walkthrough** — walk through a concrete instance
  from the wiki step by step.
- **Compare-and-contrast** — teach a concept against something it's
  commonly confused with.
- **Teach-back** — give the user the raw facts, then ask them to explain
  the concept back in their own words; correct gently.
- **Mnemonic / memory device** — for lists or sequences, build a memory
  aid together with the user.
- **Real-world scenario / role-play** — apply the concept to a
  hypothetical situation the user reasons through.

---

## Calendar file generation

Only when requested. Write a standard RFC 5545 `.ics` file to
`outputs/teaching/<slug>/reminders.ics`:

```
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Cascade KB//Teach Me//EN
BEGIN:VEVENT
UID:<slug>-session-1@ckb-teach-me
DTSTART:<YYYYMMDDTHHMMSS>
DTEND:<start + session_duration_minutes>
RRULE:<only if series, e.g. FREQ=WEEKLY;BYDAY=TU,TH>
SUMMARY:Lesson: <topic> — Session 1
DESCRIPTION:<title of session 1>
BEGIN:VALARM
TRIGGER:-PT30M
ACTION:DISPLAY
DESCRIPTION:Lesson reminder
END:VALARM
END:VEVENT
...one VEVENT per session (or a single RRULE'd VEVENT if the sessions are
   evenly spaced and identical in duration)...
END:VCALENDAR
```

- For a series with a regular cadence, prefer one recurring `VEVENT` with
  an `RRULE` (and a `COUNT=<N>` matching the number of sessions) over N
  separate events — simpler for the user's calendar app to manage.
- For a single session or irregular cadence, emit one `VEVENT` per
  session with explicit dates.
- Use the date/time the user gave in Step 1; if no time of day was given,
  ask before generating rather than guessing.
- Tell the user the file path and that importing it is a manual step in
  their own calendar app — this skill only produces the file.

---

## Edge cases

- **No wiki content in scope.** Tell the user the topic isn't covered
  yet, same as the `quiz` skill would — suggest a narrower topic or an
  Ingest first. Don't fabricate a curriculum from nothing.
- **Topic scope changes between Plan and Teach calls** (user asks to
  teach something broader/narrower than the saved plan). Treat this as a
  new topic — create a new `outputs/teaching/<new-slug>/` rather than
  overwriting the existing plan, since the old one may still be in
  progress.
- **User wants to abandon or restart a course.** Ask for confirmation,
  then either delete the folder (only with explicit confirmation — this
  is a destructive action) or archive `progress.md` with a note and start
  a fresh `plan.md` if they want to redo the scoping.
- **Plan and progress disagree** (e.g. plan.md was hand-edited, or a
  session number in progress.md doesn't exist in plan.md). Point it out
  to the user and ask how to reconcile rather than silently guessing.
- **Course fully completed and user asks to "teach me" again on the same
  topic.** Don't silently restart — tell them the course is complete and
  ask whether they want a fresh, deeper course, a review/quiz pass, or a
  different topic.
- **Very long-running series** (many sessions already logged) — no need
  to re-read every past `progress.md` entry in full each time; the `Next
  up` line and the most recent 1-2 session entries are enough context to
  continue. Older entries are history, not required reading.

---

*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*