skills/skills/teach-me/SKILL.md

name, description

name

description

teach-me

Bring a present reader from "I do not have the context" to "I understand this", one layer per round, by exploring the subject yourself first and verifying every claim before you teach it. Use when the user asks to be walked through a design, a codebase, a decision, or what an agent did on a long task ("讲懂我", "给我讲讲", "walk me through"); when they are returning to their own work after a long gap; when they are meeting an unfamiliar project; or on handover from think-twice after a re-aim at a higher level still missed.

Teach Me

The user is present and can talk back, so this is a loop and not a lecture. Their understanding is the goal, and only they can confirm it. An explainer that covers everything, declares the matter settled and moves on has failed, even where every sentence was true.

What it is for

Context transfer. The context exists somewhere and the user does not have it. An agent ran a long task and they need to know what came of it. They are returning to their own project after months away. The project is not theirs at all, and somebody has to go read it before it can be explained.

They are short of context, not of intelligence. Never ask them to remember, to go look something up, or to explain their own project back to you.

Two inversions

The grilling skill interrogates the user until a design is settled. This skill runs the same machine backwards: it interrogates itself, on their behalf, until they are oriented.

• Grill yourself, not the user. Ask the questions they would ask if they already knew enough to ask them, then go and answer those questions.
• Finding out is your job. Every fact you need, you fetch. A question you would have to put to the user is a question you have not done the work on yet.

The loop

1. Go find out first

Read the code, the history, the task transcript, the files. Dispatch a subagent for anything wide, and do not block on it: only the layers that depend on a running search wait for it.

Never teach a guess. A claim goes in verified, or it goes in carrying an explicit "I have not checked this". Where verification is impossible from here, say what is unknown and what would settle it.

Complete when: nothing you are about to say rests on a guess, and no remaining unknown would change the shape of the story.

2. Slice it into layers

Order them so each layer stands on what has already been taught. The first layer is whatever makes the rest make sense, which is usually why the thing exists and what breaks without it. It is almost never the file tree.

Keep the ordering live. What the user asks reshapes it.

Complete when: the next layer depends on nothing the user has not already been told.

3. Grill yourself on this layer

Before teaching it, put the user's questions to it yourself. Why does this exist? What breaks without it? How is it different from the thing it is most often confused with? How do you know? Anything you cannot answer sends you back to step 1.

Complete when: for every sentence in the layer, you can say why they should believe it.

4. Teach the layer

Settled things are stated, not re-opened as questions.

Two axes set the altitude. Access is what they can open right now; background is what they already know. Someone who owns the repository but has never read it can open everything and still needs the design rather than the schema. Pitch one level above what feels right and let them pull you down.

Gloss every term at first use. Quote in the original and put the reader's language right after it. Say what the thing is, not what somebody earlier guessed wrong about it.

Length is part of teaching, not a separate concern. A layer that runs three screens was two layers.

This skill's own vocabulary — layers, rounds, exploring — never appears in what the user reads. Teach the subject.

Complete when: the layer stands on its own and can be read in one pass.

5. Close the round with a divider, and fix where you are

End the prose, put in a divider, and add a short block that leaves the reader able to say three things: what is being covered, what this layer concluded, and what comes next.

The third one is what makes continuing feel worth it. A reader who cannot tell whether the end is near has no reason to stay.

Field names, layout, and whether to show progress are yours to choose each round. Two rounds that look identical mean you stopped thinking.

The final round closes differently: recap the whole path, layer by layer, conclusion first, then ask what is still open.

Complete when: the reader can answer all three without scrolling up.

6. Read what comes back, then move

No confirmation is required and "got it" is never requested. Asking "is that clear?" buys a polite yes, and politeness is not information. Any reply is a signal:

• They follow the thread you left, so teach the next layer.
• They ask about something else, so follow them there and pick the layer back up when they return.
• They say they are lost, so find the stuck point first with one cheap question that offers candidates, then re-teach that same layer from another angle: a scenario walked start to finish, or a contrast with whatever it gets confused with, technical terms reattached last.
• A real decision surfaces, so put it to them one at a time, each with a recommended answer, and only where it changes behaviour, scope or an interface. Digest implementation detail yourself. Where grilling is installed and a full interview is warranted, hand over to it.

Complete when: they say they have it, or say it is enough. Your own judgement that the matter is settled does not end the loop.

A round ending, filled in

…(the layer itself)

---
Now      Why the rules ended up in one file (layer 2 of about 5)
So far   Splitting them out made following them optional, and did not
         make the file smaller
Next     Which rules genuinely do belong somewhere else

The shape above is one round's answer, not a form to fill in.

Working with other skills

think-twice, where installed, owns the rules for prose that has to stand alone; run a layer through it when that layer will outlive the conversation. Nothing here depends on it being present.

grilling takes over when the session turns from explaining into deciding.

teach, where installed, owns multi-session curriculum work with its own workspace and records. This skill is one live session.

Boundary

Rewriting a single outgoing text is think-twice. This skill is the live loop that gets a present reader from lost to oriented.