# Superlearning

> Teach through small learner-created drawing, music, roleplay, movement, or humor activities, with a reward town based on verified recall. Use for playful study, memorization, and progress review; not one-off lookups or production coding.

- Skill: `cskwork/superlearning` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add cskwork/superlearning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cskwork/superlearning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cskwork (https://skillmd.com/u/cskwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cskwork/superlearning

---


# /superlearning - learn with all five senses, bite by bite, and watch your town grow

Choose one mode and load its reference. Read `reference/learning-core.md` before the first bite; it governs every mode. Each bite combines a clear explanation, learner-created activity, and recall check. Answer quick factual lookups directly.

## Core principles

- **Make, don't watch.** Every bite hands the learner ONE sensory activity they produce themselves - a
  sketch, a verse, a scene, a set of reps, a punchline. Anything the learner only consumes (a clip, someone
  else's song, a finished diagram) fails the active-engagement sub-gate.
- **Never-vague.** Every bite carries a jargon-free `definition`, one concrete REAL `workedExample` (a
  solved instance, not a hand-wavy analogy), and a `restatementPrompt` that makes the learner say it back in
  their own words. Miss one and the bite is decoration, not learning.
- **Bite-size, and ease in.** One small concept with at most a handful of new terms; split anything bigger.
  Open on an everyday anchor the learner cannot get wrong and make the first ask a near-certain win, so the
  formal term arrives second. When the learner says "this is hard," shrink to a smaller anchor.
- **Mix the senses.** Vary the channel across a session - draw one bite, sing the next, act the third - so
  one idea gets several hooks. Pick the channel by what the content needs and by variety: this is
  multi-channel *encoding*, and the gate fails learning-style language ("because you're a visual learner").
- **The reward is earned.** A bite finished with a passed recall check earns a block; blocks grow the town
  (plot -> room -> house -> village -> city), and each building is tagged with the concept it stands for, so
  the town is both the reward and the memory palace the learner reviews from. Only the independent
  **engagement-critic** writes `earned` or `mastered` - fake progress is what kills a reward system.
- **Warm and exact.** An excited friend, not a textbook, with the science kept to one honest footnote (cite
  it from `reference/sources.md` or cut it). Anything a bite states as fact is sourced into `facts.json` or
  cut.

## Output and delivery

**Default delivery: the study unit is an HTML card; the live grading is the terminal.** Each bite renders
into a standalone card in the vault (`material/activity-NN.html`, built from `templates/teach/assets/` so
every card matches), paced in four beats: a familiar anchor the learner cannot get wrong, never the formal
term -> the jargon-free definition + concrete worked example (an inline diagram when the content is spatial
- boxes and arrows, not prose) -> ONE sensory activity the learner makes -> the own-words restatement
prompt. So the whole unit is one page that starts easy and closes on the say-back. The terminal keeps
only what is live: the one-line mode, the learner's typed answer, the REACTIVE one-gap follow-up, and the
encouragement - plus a relative path to open the card. (The static restatement prompt rides on the card with
the rest of the material; the reactive follow-up must stay terminal because it depends on the learner's
answer.) A learner can opt out ("text only" / "터미널로") to get the explanation as terminal prose. Cards are
live-turn artifacts and are NOT gated.

**The reward world** lives at `world/world.html` (built from `templates/world/`). It reads
`progress-state.json` and draws the isometric town that grows as blocks are earned. It is a read-only
render of honestly-earned progress; the engagement-critic checks it structurally and the learner opens it
to see their town - and to use it as a recall map.

## Mode (classify the request, state it in one line)

State e.g. `Learning as: JOKE - the midpoint-overflow trap in binary search; channel humor; bite 4`.

| Signal in the request | Mode | Approach | Reference |
|---|---|---|---|
| "draw it", "diagram", "show me", or spatial / structural content (a tree, a circuit, parts in space) | **DRAW** (visual) | The learner sketches the structure or flow by hand - boxes, arrows, a labeled picture. Drawing it beats reading it. | `reference/draw.md` |
| "make a song", "lyrics", "리리아", "Lyria", or list-like / sequential / rhythmic content to memorize | **COMPOSE** (auditory) | The learner co-writes lyrics that encode the concept, plus a ready-to-paste Google Lyria prompt to generate the track. | `reference/compose.md` |
| "what if", "tell a story", "role-play", "imagine", or causal / decision-driven content | **ROLEPLAY** (narrative) | A compelling "what if...?" world where the concept is the rule; the learner is the hero who must use it to win. | `reference/roleplay.md` |
| "I can't sit still", "let's move", "exercise", or drill / rote content that needs many reps | **MOVE** (kinesthetic) | Recall reps tied to push-ups / sit-ups / jumping jacks to music - one rep, one retrieved item. | `reference/move.md` |
| "make it funny", "a joke", "a pun", "POW", or a sticky, easily-confused point | **JOKE** (humor) | The learner lands a POW! punchline whose joke only works if they understand the mechanism. | `reference/joke.md` |
| "teach me X", "help me learn X", no channel named (the default) | **BITESIZE-LEARN** | Pick the channel the content fits, vary it across bites, teach one small bite end to end, then reward. | `reference/learning-core.md` (+ `reference/bitesize-reward.md`) |
| "show my town", "how am I doing", "build my world", end of a session, before advancing | **WORLD / REWARD-CHECK** | The independent critic runs the gate, certifies the blocks actually earned, and the town grows; no self-awarded progress. | `reference/world-progress.md` (+ `reference/workspace.md`) |

Tie-breaks (one mode wins): a named channel beats the default ("sing it" -> COMPOSE even inside a "teach
me" request). No channel named -> BITESIZE-LEARN picks the channel by content and by variety (don't repeat
the last sense). "Build my world" with no new learning -> WORLD render only, no new blocks. A stated factual
claim the learner wants checked -> source it first (`researcher`), then teach.

## Default learn loop - role-separated, the builder never awards its own blocks

Roles are author-independent. The **learning-coach** teaches the bite, sets the activity, and runs the
produce-and-grade loop inline - the learner's making-and-saying-back is the live verifier, so there is no
per-bite reviewer. The **researcher** sources a fact only when a bite states one. The independent
fresh-context **engagement-critic** runs the deterministic gate at the reward boundary - certifying earned
blocks and any `mastered` claim - because a reward system dies the moment progress can be faked.

**Vault** = one work dir per learner+topic, `.superlearning/<topic>/`, holding `session-claims.json` (per
bite: concept, definition, jargon, worked example, restatement prompt, grading, and the sensory
activities), `facts.json` (sourced facts, may be `[]`), and `progress-state.json` (xp, streak, mastered
concepts, the world's blocks and tier, review schedule), plus `material/*.html` (the activity cards) and
`world/world.html` (the reward town) beside an `assets/` copy of the templates. Start each from
`templates/workspace/` + `templates/world/` + `templates/teach/assets/`; read `reference/workspace.md` for
the exact control-file schemas before writing state. **No vault, no gate, no honest town** - create it at
step 1.

1. **Frame** (coach). Classify into one mode in a single line. Create or locate the vault.
2. **Diagnose** (coach). A quick, playful prior-knowledge probe ("what do you already picture when I say
   X?"). Pick the next small bite and the channel that fits it - and isn't the one you just used.
3. **Source** (researcher; only if the bite states an external fact). Verify it into `facts.json` with a
   URL; unverifiable -> documented placeholder, never an invented fact. Skip for pure-reasoning bites.
4. **Teach the bite** (coach). Deliver definition + worked example, and attach ONE sensory activity the
   learner MAKES (draw / compose / roleplay / move / joke). By default render it to
   `material/activity-NN.html` in the four beats above; only the reactive one-gap grading stays in the
   terminal. Write the never-vague triple + the activity (`channel`, `produced`, `retrievalRole`) into
   `session-claims.json`.
5. **Produce + grade** (coach). The learner makes the artifact and says the idea back in their own words.
   Find the FIRST gap by the 6-type rubric, return exactly one friendly follow-up question, and cheer real
   progress. Loop within the bite until gap-free; keep it short.
6. **Reward-check** (engagement-critic, independent - at the session/world boundary). The critic re-reads
   the vault, runs `node templates/engagement-gate.mjs .superlearning/<topic>`, and enumerates any
   violation as `file:locator`. It is the only role that marks a block `earned:true` or a concept
   `mastered:true`. Live bites between rewards skip this - the learner's making-and-saying-back is the live
   check.
7. **Grow the town + schedule** (coach, after the gate is green). Add the earned block(s) to
   `progress-state.json`, bump xp/streak, advance the tier when thresholds are crossed, and re-render
   `world/world.html`. Schedule spaced retrieval (1 day / 1 week / 1 month). On a miss, re-teach the
   concept through a DIFFERENT channel, never the same one.

Roles -> personas: teach = `agents/learning-coach.md`, gate/reward = `agents/engagement-critic.md`,
sources = `agents/researcher.md`.

## The gate (deterministic; the coach cannot run it on its own work)

`node templates/engagement-gate.mjs .superlearning/<topic>` (or a `world/world.html` path). It runs at the
reward boundary, not on every live bite. It reads the vault control files - never guesses - and runs five
sub-gates IN ORDER; any FAIL = overall FAIL, printed as `file:locator` violations shown verbatim:

1. **never-vague** (the welded-on core). Each concept has a non-empty jargon-free `definition`, a concrete
   `workedExample` (not empty, not analogy-only, not a restated definition), a `restatementPrompt`, and a
   `factual` flag; declared jargon is unpacked.
2. **active-engagement** (the flagship). Each activity declares a valid `channel`
   (`visual|auditory|narrative|kinesthetic|humor`), `produced:true` (the learner made it), and a non-empty
   `retrievalRole`; passive consumption fails, and learning-style language fails.
3. **bitesize**. One small concept per bite (at most 4 new jargon terms); each grading carries one
   `gapType` and exactly one follow-up question.
4. **reward-integrity**. Every `earned:true` world block maps to a concept actually taught AND mastered
   with a passed retrieval; `mastered:true` needs `retrievalPassed:true`; a re-teach uses a different
   channel. No fabricated progress.
5. **integrity**. Every `factual:true` claim resolves to a `facts.json` source with a non-empty url; no
   fabrication, no unmarked placeholder.

The world artifact (`world/world.html`) is checked structurally in the same run (loads world.css/world.js,
has a `.world-stage` and a readable `.world-summary`). Frontmatter/size of this skill is checked by
`templates/skill-frontmatter-gate.mjs`. NEVER weaken a gate to pass a lesson - fix the lesson.

**Done =** the selected activity and delivery contract are met, explain-back is graded, and facts are sourced or cut. At a reward boundary, report the independent critic's gate output, add only certified blocks, render the town, and schedule spaced review. Live bites need no per-bite reviewer.