Some time around 385 BC, Plato wrote a scene into the Meno that teachers still cite. Socrates calls over a slave boy who has never studied geometry and draws a square in the dust. How would you make a square with double the area? The boy answers instantly: double the sides. Socrates draws it, and the boy sees for himself that the new square holds four times the area, not two. He guesses again, and fails again. Then, question by question — never a lecture — Socrates walks him to the real construction: build the new square on the diagonal of the old one. No formula was handed over. The boy produced every step himself, out loud, under pressure, and could defend it.
That scene is the design document for what Jane Street published on GitHub this month: a repository named agent_skills containing exactly one file that matters, a SKILL.md that turns any modern LLM into the Socrates from that dialogue — a tutor that asks one question at a time, refuses to lecture, tracks what you have actually mastered on a six-level scale, and will lower your score without warning if a review question exposes that you never really learned something.
The repository was created on November 3, 2026, and within ten days it had collected more than 7,400 stars and over 490 forks. It contains six files in total, one of which is .ocamlformat, the configuration for the OCaml code formatter — about as pure a Jane Street fingerprint as a license header. Everything else is a license, a README, a contributing note, and the skill itself.
What a skill is, mechanically
A SKILL.md is a markdown file with a YAML frontmatter header that agentic tools load as an instruction pack. Claude Code made the format common: the model reads the file, and the file tells the model how to behave for a class of tasks. There is no executable code in it. Jane Street's README describes two ways to use their tutor: copy the socratic-tutor directory into your agent's skills folder and ask "teach me X", or paste the body of the file into any plain chatbot as a system prompt.
Which means the entire artifact is prose. Everything interesting about it lives in the writing, and the writing rewards a close read.
The frontmatter knows when not to run
The file's first engineering decision sits in the YAML header:
--- name: "socratic-tutor" description: "Structured Socratic tutoring when the user explicitly asks to be taught, quizzed, or drilled to mastery on a topic: diagnostic placement, a skill map with levels 0-5, spaced review, and a final assessment. Trigger phrases: 'teach me', 'tutor me', 'quiz me', 'drill me', 'help me master'. Not for one-off 'explain X' or 'what is X' questions." --- Read that description as a routing rule, because that is what it is. Agents match incoming requests against skill descriptions, and this one spends half of its length on a negative clause: not for one-off questions. A skill that triggers too eagerly is worse than one that never triggers, and the author clearly knew it. The description names exact trigger phrases so the router has something concrete to match, and it names the excluded cases so "explain recursion" at 11pm does not accidentally turn into a forty-minute diagnostic with a progress bar.
The guard clause is a cost calculation
The file's second decision repeats the same idea inside the body. If intent is ambiguous, the agent must ask exactly one question — "Want a quick answer, or should I actually teach you this properly?" — before starting anything. The reasoning written into the file is explicit about the asymmetry: a false start costs the user an unwanted quiz; a confirmation costs one word.
That is a genuinely reusable rule for any agent behavior with an expensive happy path. Estimate the cost of a false positive against the cost of a confirmation gate, and when the ratio is this lopsided, write the gate into the procedure rather than hoping the model exercises judgment at runtime. Judgment is exactly what fails under a vague prompt; a written gate does not.
The skill map is state, and state is the hard part
LLM sessions are stateless in every way that matters for teaching: the model does not remember Tuesday, does not know what you got wrong last week, and will happily re-explain the same concept forever. The tutor's answer is to externalize the state into the conversation itself. The topic gets broken into four to ten subskills, each tracked at a level from 0 (unaware) to 5 (can teach it), and the model re-renders the map in ASCII after every level change:
Topic: <topic> overall: ######.... 58% ----------------------------------------------------------------- subskill A [########..] 4/5 * independent subskill B [######....] 3/5 <- current focus subskill C [##........] 1/5 ----------------------------------------------------------------- Two user commands complete the design. "save state" makes the agent emit a compact block holding the topic, the map, and notes on your observed misconceptions; "resume from:" followed by that block restores the course in a brand-new session. The student, not the platform, carries the transcript. This is the same trick the better agent harnesses use for long-running work — when the runtime forgets, make the runtime's own output be the checkpoint.
The teaching loop is mostly a list of prohibitions
The core loop is short: ask one question, end the message immediately after it, and wait for the answer. What fills the file is everything the tutor must not do. No hints after the question. No example answers appended just in case. When you are wrong, the tutor does not correct you — it asks a narrower question that exposes the contradiction inside your own reasoning, and only explains directly after two or three failed attempts, immediately re-testing the same idea from a different angle. When you are right, it will sometimes argue with you anyway, because an answer you cannot defend under pressure is not yet knowledge.
Anyone who has used a chatbot for study recognizes what these rules are fighting. Left alone, models flatter, hint, and collapse into lecturing the moment the user hesitates. The skill reads like a list of observed model failure modes with a countermeasure bolted onto each one.
Evaluation is where tutoring prompts usually die
The strictest section of the file is the one on earning levels:
- Levels are earned, not given. Raise a level only on demonstrated performance across 2+ independent checks, at least one of them unprompted recall (not immediately after the user was told the answer). - A vague or partially-correct answer is not correct. Probe until you know whether the user actually understands. Do not attribute to the user any insight they did not actually express. - Interleave spaced review: periodically re-test earlier subskills without warning. If the user fails a review, lower the level and revisit. Three ideas in that block come from learning science rather than prompt folklore: recognition is not recall, hence the unprompted check; spacing beats massing, hence the unannounced review; and progress must be reversible, hence levels that go down. The file even bans flattery by name — "Not quite — why would X happen if Y were true?" beats "Great try!" Level 5 is reserved for a student who handles an adversarial edge case and then explains the concept clearly enough that the tutor would trust them to teach it.
Running it takes two minutes
With a skill-aware agent, installation is a directory copy into the skills folder. With anything else, paste the file body into the chat and say "teach me Bayesian inference," or whatever you are actually working on. A session opens with the diagnostic — three to five probing questions spanning easy to hard, per subskill — and only after placement does the first lesson begin. Mid-course, the escape hatches are explicit: "just tell me" suspends Socratic mode for a single question, "harder" and "easier" retune the difficulty, and "show progress" redraws the map.
The course ends only when every subskill reaches the target level — 4 out of 5 by default, 5 if you asked for full mastery — followed by a final mixed assessment with at least one question per subskill and one integrative problem. Fail it, and you go back into the loop.
What the Hacker News thread got right
The front-page discussion, at 539 points when this article was researched, split into three camps, and all three teach something. The skeptics called it a prompt with a README, which is technically true and mostly beside the point — the value of the file is that a serious firm wrote down a hundred lines of teaching discipline so you do not have to rediscover them yourself. One commenter reduced the entire effect to a single sentence — "when the user is wrong, do not give the answer" — which is fair as far as it goes and misses the diagnostic, the state tracking, and the review schedule that make the effect hold across sessions instead of one afternoon.
Another commenter pointed to an earlier community skill, bevibing/socrates-skill, published back in April 2026 with a few hundred stars, doing the same job for Claude Code. Jane Street's contribution is packaging and distribution, not invention, and the star count says more about the firm's brand gravity than about novelty. The most useful comment in the thread was the weariest one: skills written for a model six months ago are already bit-rotting, because the newer model does much of it natively. That risk applies to every skill file in every repository, including this one, and it is the honest counterweight to the current excitement around the format.
The pattern worth stealing
Strip the pedagogy away and the file is a template for any behavior you want from a stateless model: a routing header that says when not to run, a cheap confirmation gate placed before an expensive procedure, state externalized into artifacts the user can carry between sessions, a loop defined by its prohibitions, and an evaluation section that treats progress as revocable. The next skill you write — for code review, for incident triage, for anything with levels of competence — can reuse all five parts unchanged.
The slave boy in the Meno walked away able to double a square. Jane Street's bet, written into a hundred lines of markdown, is that the method scales better than the lecture ever did.
Originally published on Dispatch.
