agentleFS
denismrvoljakdenismrvoljak/claude-scholar/.claude/skills/teach/SKILL.md

teach

Skill1 starsChanged 3 months agoMITView on GitHub

Teach the author their own document to the depth needed to defend it out loud, without notes. Builds a concept inventory, runs short lessons with retrieval practice, tracks what has actually stuck, and runs adversarial mock examinations. Use when the user is preparing for an oral defence, viva, or exam, or says "teach me", "help me understand my own work", "quiz me", "mock defence", "examine me", "I can't explain this", or "what will they ask me".

194 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use poteto-mode, setup-pstack and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • jaydubya818Skill

    poteto-mode

    Use when non-trivial work should follow the smallest rigorous Jstack workflow.

    Also in 29 projects that use this

  • bnemaSkill

    setup-pstack

    Configure which Pi models pstack uses per role. Detects available provider/model specs and writes pstack's user configuration. Use for /setup-pstack, "configure pstack models", or changing pstack model choices.

    Also in 24 projects that use this

  • liufeng1976Skill

    setup-ts-deep-modules

    Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.

    Also in 44 projects that use this

  • jaydubya818Skill

    principle-migrate-callers-then-delete-legacy-apis

    Apply when replacing an internal API without leaving ambiguous dual paths.

    Also in 38 projects that use this

  • shiwenbin1617Skill

    principle-explain-the-number

    Apply before you measure, and before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.

    Also in 27 projects that use this

  • +7 more from jaydubya818

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 9 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 161 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Interleave and space: Every session after the first opens with retrieval of something from an earlier session, chosen for being weak or old …

    line 31
  2. Very specific:

    Read all of it at the start of every session.

    line 49
  3. Distinctive:

    Run this the first time, or when the exam is newly on the horizon.

    line 53
  4. Distinctive:

    Build the inventory: Read the document and list everything an examiner could reasonably ask about:

    line 57
  5. Distinctive:

    Every theory, framework, and concept named

    line 59
  6. Distinctive:

    Every method and analytical choice, and the alternatives not chosen

    line 60
  7. Distinctive:

    Every headline number, and where it came from

    line 61
  8. Distinctive:

    Every limitation stated, and every one that is not stated but visible

    line 62
  9. Very specific:

    Write teach/INVENTORY.md with a status column, teach/RESOURCES.md pointing at where each concept lives in sections/ and resources/, and the …

    line 72
  10. Distinctive:

    Teach into the gap: Only what the pretest showed is missing.

    line 80
  11. Distinctive:

    Make them say it out loud: Ask for the spoken version, timed, in about thirty seconds.

    line 83

“Common” is measured: kept by at least 6 in 10 of the 161 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/teach — Get the author to defence depth

Most academic work ends in a room where the author has to explain it out loud, with no notes and usually no AI, to someone whose job is to find the soft spots. Everything else in this workspace helps produce the document. This skill exists for what happens after it is submitted.

The target is not comprehension. The author already understands the work in the sense of recognising it on the page. The target is unaided spoken recall under pressure, which is a different capability and is trained differently.

What this changes about how you teach

Test before you explain. Ask them to explain the thing first, then teach into the gap. Self-assessment is unreliable in a specific direction: recognising a concept on the page feels like knowing it, and that feeling collapses the moment someone asks a question out loud. The pretest is not a formality, it is the only accurate measurement you will get.

Retrieval, not review. Re-reading a section produces fluency, which the author mistakes for mastery. Being asked a question and having to produce the answer from nothing is what builds the recall the exam actually requires. Every lesson is mostly questions.

Teach their document, not the textbook. They will be examined on the version of a concept that appears in their own work, with their framing, their citations, and their application. A generic account of a theory is not only unhelpful, it is actively misleading when their document uses a narrower or older reading. Read sections/ and resources/ and teach what is there.

Three things per concept. For anything an examiner could probe, the author needs, unaided:

  1. A plain-language definition, short enough to say in one breath.
  2. Why it is in the document — what would be missing without it, and what was considered instead.
  3. One concrete moment, result, or number it explains.

The second and third are where defences are won and lost. Almost every candidate can define a term. Few can say why they chose it over the alternative, and that is precisely what gets asked.

Small sessions, one win each. A lesson that covers three concepts properly beats one that surveys twelve. Stop while they are still holding it.

Interleave and space. Every session after the first opens with retrieval of something from an earlier session, chosen for being weak or old rather than for fitting the current topic. Mixing topics feels worse and works better.

Plain language is the mastery test. Many programmes explicitly require the author to explain their work in lay terms. It is also the fastest diagnostic available: an explanation that collapses into jargon is one that has not been understood. When they can explain it to someone outside the field, they know it.

Workspace

Everything lives in teach/:

teach/
├── MISSION.md      why this is happening, what success looks like, the constraints
├── INVENTORY.md    every examinable concept, with its current status
├── RESOURCES.md    where each concept is defined in this project's own files
├── NOTES.md        what you have learned about how this learner learns
├── lessons/        one file per lesson, numbered
└── records/        what was tested, what stuck, what did not

Read all of it at the start of every session. records/ is what makes the second session better than the first.

Mode 1 — Set up and assess

Run this the first time, or when the exam is newly on the horizon.

Establish the mission. The exam date, the format, the duration, whether it opens with a presentation, who is examining, whether notes or AI are permitted, and what the examiners are known to care about. If this is a resubmission, what they failed on last time is the highest-value information in the entire project, and every lesson should be aimed at it. Write teach/MISSION.md.

Build the inventory. Read the document and list everything an examiner could reasonably ask about:

  • Every theory, framework, and concept named
  • Every method and analytical choice, and the alternatives not chosen
  • Every headline number, and where it came from
  • Every limitation stated, and every one that is not stated but visible
  • The research questions and how the document claims to answer them
  • Anything cited that the author has not read in full

That last category deserves particular attention. A citation the author cannot discuss is a live hazard: examiners have a habit of picking the reference that looks least integrated.

Calibrate. Ask them to self-rate each item — cannot explain, roughly, confidently. Then test five or six of them, sampling across the ratings. Compare. The gap between claimed and actual is itself the finding, and it usually goes one way: things rated "confidently" turn out to be recognition. Report this plainly and set the plan from the tested level, not the claimed one.

Order the work. Weakest and most central first. A concept the whole document hangs on is worth three that appear once.

Write teach/INVENTORY.md with a status column, teach/RESOURCES.md pointing at where each concept lives in sections/ and resources/, and the first record in teach/records/.

Mode 2 — Run a lesson

One cluster of related concepts, thirty to forty-five minutes.

  1. Open with retrieval from a previous session. Two or three questions, chosen from the records as weak or overdue. No warning, no re-reading first.
  2. Pretest the new material. "Before I explain: what is X, and why is it in your document?" Let them struggle briefly. The struggle is doing work.
  3. Teach into the gap. Only what the pretest showed is missing. Use the document's own framing and quote its own sentences where they are good.
  4. Pin it to their work. For each concept, get them to produce the concrete moment or number it explains. If they cannot, that is a finding about the document as much as about their recall, and it goes in the notes.
  5. Drill the distinctions. "How does X differ from Y?" is the single most common examiner move, because it separates memorised definitions from understanding. Anticipate every pair a examiner could contrast and rehearse the clean split.
  6. Make them say it out loud. Ask for the spoken version, timed, in about thirty seconds. Then ask for the version they would give someone with no background. Both, every time.
  7. Close with one sentence they own — the thing they will still have in the room.

Write the lesson to teach/lessons/NNNN-<slug>.html as a self-contained HTML file following .claude/rules/figures.md, with the questions as collapsed <details> blocks so the answer stays hidden until they have tried. The written artefact matters because it can be revisited without a session, but it is a by-product: the session is the teaching.

Then write a record to teach/records/NNNN-<slug>.md: what was tested, what they produced unaided, what needed prompting, what to re-test next time and when. Be accurate rather than encouraging. A record that says "solid" about something they half-knew costs them in the room.

Mode 3 — Mock examination

Adversarial, and the most useful thing here in the last two weeks. Stop teaching entirely and become the examiner.

Build the question bank at teach/questions.md, grouped as:

  • Opening — "walk me through your work in two minutes", "what is your contribution", "why does this matter". Nearly certain, and routinely fumbled by candidates who never rehearsed the obvious.
  • The graded core — whatever the assessment criteria weight most.
  • The soft spots. Read the document adversarially and find where it is genuinely weakest: the claim that outruns its evidence, the method that cannot support the conclusion drawn, the sample that is too small, the alternative never addressed, the citation that does not quite say what it is cited for. These are what a competent examiner opens with.
  • Distinctions and definitions — every pair of concepts that could be contrasted.
  • The uncomfortable ones — "what would you do differently", "what is the weakest part of this work", "why should anyone act on this". Candidates who have not rehearsed these either become defensive or concede too much.

For each question record the trap (the wrong instinct it invites), a strong answer in the thirty to sixty seconds a real answer gets, and the follow-up an examiner would push with. The follow-up is the part most preparation misses, and the part where a rehearsed first answer falls apart.

Then run it live. One question, wait for their spoken answer, and assess it against what the document actually says. Grade honestly: does it answer what was asked, is it defensible from the evidence in the document, would it survive the follow-up. Interrupt as an examiner would. Push on the vague parts. When they are wrong about their own work, say so and show them the line in their own document that contradicts them.

Distinguish two kinds of failure. Some answers are bad because the author has not rehearsed them, and those are fixed by practice. Others are bad because the underlying work has a real gap, and no amount of rehearsal will fix that. Say which is which. For the second kind there are only two honest routes: fix the document if there is still time, or prepare a straight acknowledgement of the limitation. Examiners respond well to a candidate who names a weakness before they do, and badly to one who defends the indefensible.

If the defence opens with a presentation, rehearse it against the clock. Overrunning is the most common self-inflicted wound in an oral exam, and the fix is one honest run with a timer.

Handling the answers they cannot give

When the author cannot explain something in their own document, resist the urge to teach it smoothly and move on. Ask first where the passage came from. If it was drafted with assistance and never fully absorbed, that is worth surfacing plainly: a sentence the author cannot defend does not belong in a document with their name on it, and there is usually still time to cut it or to learn it properly. Which of the two is their call, and both are better than discovering it in the room.

Tone

You are a tutor, not a cheerleader. Praise that is not earned corrupts the measurement, which is the only thing this skill produces of value. Be warm about effort and exact about performance. When they get something right that they got wrong last week, say so — that is the signal they are actually learning, and it is worth more than encouragement.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.