Jane Street's socratic-tutor skill: turn any chatbot into a strict personal tutor

Jane Street published a one-skill Agent Skills repo that turns a chatbot into a strict Socratic tutor — diagnostic, skill map, one question at a time. This guide installs it in Claude Code and runs a real session.

• The repo: janestreet/agent_skills — created November 3, 2026; 3,093 stars and 182 forks as of November 10, 2026; MIT license; two commits; exactly one skill inside.
• The skill: socratic-tutor — a single SKILL.md file. Trigger phrases: “teach me”, “tutor me”, “quiz me”, “drill me”, “help me master”.
• The method: break the topic into 4–10 subskills, run a 3–5 question diagnostic, track each subskill at levels 0–5, ask one question at a time, interleave spaced review, and finish with a mixed assessment. Default target is 4/5; 5/5 for full mastery.
• Install: copy the socratic-tutor folder to ~/.claude/skills/ (personal) or .claude/skills/ (one project). Codex, Cursor and Gemini CLI read .agents/skills/ instead. A plain chatbot takes a paste of the SKILL.md body.
• The guard: a one-off “explain X” question gets a normal answer — the tutoring loop only starts when you ask to be taught, and the skill asks you to confirm first.

The first question

On November 3, 2026, Jane Street put a single file on GitHub. No launch post, no demo video, no scripts to run: one SKILL.md inside a repo called agent_skills, named socratic-tutor. Within a week it had passed 3,000 stars.

Here is the scene it is built for. You type “teach me SQL window functions” and wait for the neat explanation. Instead, the tutor answers with a question: what do you think PARTITION BY does? That is not a bug. The skill is written to never lecture first. It asks, you answer, and it asks again — narrower, harder, until the idea is yours.

This guide installs that skill and runs a real session with it. Fifteen minutes, no API key, nothing to compile.

What happened

Jane Street is the quantitative trading firm; its repo, janestreet/agent_skills, is public under the MIT license. As of November 10, 2026 it holds 3,093 stars and 182 forks, across exactly two commits, on the master branch. The whole repo is one skill.

A skill, in the Agent Skills format, is a folder with a SKILL.md file: frontmatter with a name and a description, then Markdown instructions the agent reads when your request matches. The socratic-tutor description lists its triggers plainly: “teach me”, “tutor me”, “quiz me”, “drill me”, “help me master”. It also states what it is not for: one-off “explain X” or “what is X” questions.

The method has five moving parts, all written into the file:

• Diagnostic. Before teaching anything, 3–5 probing questions spanning easy to hard, to place your starting level per subskill.
• Skill map. The topic is broken into 4–10 concrete subskills, each tracked at a level from 0 to 5 and re-rendered as an ASCII map after every change.
• One question at a time. The tutor ends its message immediately after the question and waits. No hints, no example answers, no teaching content after it.
• Strict evaluation. Levels are earned, not given: a level rises only on demonstrated performance across two or more independent checks, at least one of them unprompted recall.
• Spaced review and a final assessment. Earlier subskills get re-tested without warning; a failed review lowers the level. The course ends with a mixed assessment covering everything.

The levels themselves are the spine of the whole thing:

Level 5 has a hard bar: you must handle an edge case or an adversarial question and explain the concept clearly enough that the tutor would trust you to teach it.

What you’ll need

• A coding agent that reads skills — Claude Code is the smoothest path, and the skill also works in Codex, Cursor and Gemini CLI — or any plain chatbot for the paste-in method.
• git and a terminal.
• A topic you actually want to learn, not just read about. The diagnostic will find out if you are bluffing.

Step 1 — Get the skill

Clone the repo. It is tiny: one skill folder, a README, a license.

git clone https://github.com/janestreet/agent_skills.git
ls agent_skills/socratic-tutor/

You should see SKILL.md. That file is the entire product. Read it before installing anything — it is short, and it tells you exactly what you are about to let an agent do to you.

Step 2 — Install it in your agent

Installing a skill means putting its folder where your agent looks. For Claude Code, the personal location loads in every project on the machine:

mkdir -p ~/.claude/skills
cp -r agent_skills/socratic-tutor ~/.claude/skills/

Two variants, same file. To scope it to one repository instead, copy it to .claude/skills/ inside that project and commit it with the code. If you use Codex, Cursor or Gemini CLI, the folder they read is .agents/skills/ — same SKILL.md, different shelf. If you have never installed a skill before, our hands-on with Anthropic’s official Agent Skills walks through the format and the same folders.

No chatbot with a skills folder? Paste the body of SKILL.md into the chat (or a custom/system prompt), followed by what you want to learn. The README documents this as the supported fallback, and it is how the skill works on claude.ai and ChatGPT.

Step 3 — Check it loaded

ls ~/.claude/skills/socratic-tutor/
# SKILL.md

Start a fresh Claude Code session and type teach me SQL window functions. The first thing the tutor must do is confirm intent — something like “Want a quick answer, or should I actually teach you this properly?” If you get a straight explanation instead, the skill did not load: check the folder name is exactly socratic-tutor, that SKILL.md sits directly inside it, and start a new session.

Step 4 — Take the diagnostic, read your skill map

Confirm you want the full loop. The tutor breaks the topic into subskills — for window functions, something like PARTITION BY, ordering inside the window, ROW_NUMBER vs RANK, and frame clauses — then asks 3–5 probing questions, one at a time, before teaching anything. Answer honestly; guessing high only buys you harder questions.

Then it shows the map. This is the format the skill renders, with levels filled in from your diagnostic:

Topic: SQL window functions              overall: ######.... 58%
-----------------------------------------------------------------
PARTITION BY            [########..]  4/5  * independent
window ordering         [######....]  3/5  <- current focus
ROW_NUMBER vs RANK      [##........]  1/5
frame clauses           [##........]  1/5
-----------------------------------------------------------------

The map is the session’s memory. It re-renders after every level change, and you can ask for it anytime with “show progress”.

Step 5 — Work the loop

From here the rules are strict, and they are the point. The tutor asks one question and stops. When you are wrong, it does not hand you the answer — it asks a narrower question that exposes the contradiction in your reasoning, and only explains directly after two or three failed attempts, then immediately re-tests the same idea from a different angle. When you are right, it may play devil’s advocate: “Are you sure? What about X?”

Where tools are available it sets practical exercises — “write a query that…”, “predict what this code prints” — and checks your actual output rather than your description of it. Earlier subskills resurface without warning; fail a review and the level drops.

You have four commands for the session, all in plain words:

To resume, paste the saved block after “resume from:”. That is the whole persistence story: without a saved state, a new session starts from scratch.

What you built

Not an app, and not a document: a tutor that knows your level. Fifteen minutes in, you have a skill map with real numbers on it, a list of the subskills you can actually do, and a saved state block that lets the next session pick up where this one stopped. The deliverable is the map — and the fact that you earned the levels on it.

Why it matters

Most AI “tutoring” is explanation with a friendly tone. You ask, it tells, you nod, and nothing sticks — the test comes a week later and the knowledge is gone. The Socratic method inverts the burden: the model’s job is to make you produce the reasoning, and the skill file is unusually explicit about how. “Do not flatter,” it instructs. “‘Not quite — why would X happen if Y were true?’ beats ‘Great try!’”

That strictness is also why the format matters more than the firm. A skill is just Markdown, which means any team can write one — Anthropic’s official set covers Word, Excel, PowerPoint and PDF, and community skills now range from research co-advisors to 3D-studio assistants. Jane Street’s contribution is a proof that the format can carry a real teaching method, not just a checklist.

The catch

Three honest limits. First, the repo holds exactly one skill and two commits. It is a week old, with no roadmap and no stated plan for more skills; what you install today is the whole product. Second, there are no scripts, no tools, no tests — the entire mechanism is prose instructions, so everything depends on the model following them. A weak model will lecture anyway, and you will have to nudge it back with “just tell me” in reverse: remind it to ask. Third, the skill map is ASCII text, not a tracker. Progress lives in the conversation and in whatever state block you remember to save.

What’s next

Watch the repo — a second skill from Jane Street would tell you whether this is a program or a one-off. Then run a second topic through it, ideally one you know badly: the diagnostic is most useful where your confidence is highest and your knowledge thinnest. And if the format clicks, compare it with Addy Osmani’s agent-skills collection to see how different authors bend the same SKILL.md shape to different jobs.