Skip to content
Back to search

understudy

Your coding agent writes you a real textbook, teaches you from it, and never writes your project for you.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/persxn/understudy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/persxn/understudy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/persxn--understudy/badge.svg)](/listings/persxn--understudy)

HTML

<a href="/listings/persxn--understudy"><img src="/api/listings/persxn--understudy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 375 lines
  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/logo-dark.png">
  4. <source media="(prefers-color-scheme: light)" srcset="docs/brand/logo-light.png">
  5. <img src="docs/brand/logo-light.png" alt="understudy" width="420">
  6. </picture>
  7. **Your coding agent writes you a real textbook, teaches you from it, and never writes your code.**
  8. Skills and scripts for Claude Code. One subject becomes one book on your own disk: numbered sections,
  9. programs that were actually run, figures, hidden answers. When the subscription runs out, the book and
  10. your progress stay.
  11. <a href="#a-page-from-a-real-chapter">See a page</a> ·
  12. <a href="#start-in-a-minute">Start</a> ·
  13. <a href="#how-a-chapter-gets-made">How it works</a> ·
  14. <a href="#what-it-costs">Cost</a> ·
  15. <a href="#a-month-with-no-ai">No AI</a> ·
  16. <a href="#honest-limits">Limits</a>
  17. </div>
  18. ---
  19. ## Who this is for
  20. A student who wants to become a developer and pays for an AI subscription one month at a time, when
  21. there is money for it.
  22. Most AI help is gone when the chat closes. You asked good questions, got good answers, and a month later
  23. none of it is anywhere you can open. understudy turns the month you paid for into something you keep:
  24. - **A textbook, written for you, in plain files.** One subject is one book. Markdown you can read in any
  25. editor, a reading page for your browser, and its own git repository you can push to GitHub.
  26. - **Your progress, on your machine.** What you have learnt, what you got wrong in practice and where you
  27. stopped live in a `private/` folder next to the book. Nothing is kept in a conversation.
  28. - **A month off loses nothing.** You read, you practise with spaced repetition, and a note tells you the
  29. one sentence to say to the agent when your subscription is back.
  30. - **You still write every line of your projects.** The agent explains, asks, reviews and points at the
  31. section that covers your problem. It does not type your code.
  32. <p align="center">
  33. <picture>
  34. <source media="(prefers-color-scheme: dark)" srcset="docs/readme/what-stays-with-you-dark.png">
  35. <img src="docs/readme/what-stays-with-you.svg" alt="A month with a subscription: the agent writes the book into book/ and records your levels and practice into private/. A month without: you read, practise and pick up the resume note from those same folders. When the subscription is back, you say one sentence to carry on." width="560">
  36. </picture>
  37. </p>
  38. ---
  39. ## A page from a real chapter
  40. This is from [`examples/learn-c-chapter-12/12-file-handling.md`](examples/learn-c-chapter-12/12-file-handling.md),
  41. "Chapter 12: File handling", written by the system for a C book. Section 12.8, cut down. A section opens
  42. on a need, gives a picture, shows how the thing works, shows the real thing, shows what goes wrong, and
  43. ends in "Check yourself" with the answers hidden. (This chapter is from an earlier version that used
  44. fixed headings; today's headings are named after the content, and the shape follows the subject.)
  45. > **The question.** Your program calls `fprintf(out, "hello, disk\n")`. The call returns. Then, while the
  46. > file is still open, the program opens the same file to read and counts its bytes, using the read loop
  47. > from §12.4. How many bytes are there?
  48. >
  49. > You'd expect twelve. There are none. Where did they go, and when do they arrive?
  50. > **The picture.** Think of posting letters. You could walk to the post box with each letter the moment
  51. > you finish writing it. Or you could put each finished letter in a tray by the door, and walk to the box
  52. > once, when the tray is full or when you go out anyway. [...] Here's where the picture stops being true.
  53. > If your house burns down, you lose only the letters in the tray, and you know which ones. If your
  54. > program crashes, the bytes in its tray are lost too, but nothing tells you.
  55. <p align="center">
  56. <img src="examples/learn-c-chapter-12/fig/12-file-handling/buffer-tray.svg" alt="Flow chart, top to bottom. your program fprintf leads to buffer in the FILE record (fast: copy bytes). The buffer leads to operating system (when full, fflush or fclose). The operating system leads to late.txt. The buffer is highlighted." width="220"><br>
  57. <sub><i>Figure 12.8a, drawn by <code>scripts/us_draw.py</code> from a short text description.</i></sub>
  58. </p>
  59. **The code.** The program writes, then counts what another reader can see after each step. The output
  60. under it was not typed by anyone: a script compiled and ran the program and pasted what it printed.
  61. ```c
  62. fprintf(out, "hello, disk\n");
  63. printf("after fprintf: %ld bytes in late.txt\n", bytes_in("late.txt"));
  64. fflush(out);
  65. printf("after fflush: %ld bytes in late.txt\n", bytes_in("late.txt"));
  66. fprintf(out, "second line\n");
  67. printf("after fprintf: %ld bytes in late.txt\n", bytes_in("late.txt"));
  68. fclose(out);
  69. printf("after fclose: %ld bytes in late.txt\n", bytes_in("late.txt"));
  70. ```
  71. ```text
  72. after fprintf: 0 bytes in late.txt
  73. after fflush: 12 bytes in late.txt
  74. after fprintf: 12 bytes in late.txt
  75. after fclose: 24 bytes in late.txt
  76. ```
  77. **Check yourself** (one of four):
  78. > A program prints `saving...` with `printf`, then crashes. Run in a terminal, you see `saving...`. Run as
  79. > `./prog > log.txt`, `log.txt` is empty. Explain the difference.
  80. >
  81. > <details>
  82. > <summary>Answer</summary>
  83. >
  84. > In the terminal, `stdout` is line buffered and the line (ending with `'\n'`) was passed on before the
  85. > crash. To a file, `stdout` is fully buffered, so the line was still in the buffer when the crash ended
  86. > the process, and it was lost.
  87. >
  88. > </details>
  89. The whole chapter has 16 sections, 45 programs, 12 figures and 75 hidden answers. The full standard a
  90. chapter is held to is [`rules/book-standard.md`](rules/book-standard.md).
  91. ---
  92. ## Start in a minute
  93. You need [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3 and git. The scripts use
  94. only Python's standard library: nothing to install. A book about C also needs a C compiler, and so on for
  95. other subjects.
  96. ```bash
  97. git clone https://github.com/persxn/understudy.git
  98. cd understudy
  99. claude
  100. ```
  101. Then say what you want, in your own words:
  102. ```text
  103. I want to learn Git.
  104. ```
  105. There is nothing to memorise. "Teach me Docker", "quiz me on chapter 3", "I'm stuck on my project" and
  106. "what should I learn next?" each load the right skill by themselves. On the first run the agent creates
  107. `book/` (your book, its own git repository) and `private/` (your records, never pushed).
  108. ---
  109. ## How a chapter gets made
  110. <table>
  111. <tr>
  112. <td width="44%" align="center">
  113. <picture>
  114. <source media="(prefers-color-scheme: dark)" srcset="docs/readme/from-wish-to-chapter-dark.png">
  115. <img src="docs/readme/from-wish-to-chapter.svg" alt="Flow chart: &quot;I want to learn Git&quot; leads to plan the book, then you approve (or ask for changes), then one writer writes the whole chapter, then scripts run code, paste output, draw and check, then one review (the risk list, then one read), then you read and practise." width="300">
  116. </picture>
  117. </td>
  118. <td>
  119. 1. **Plan.** The agent maps the subject into parts, chapters and numbered sections, in the order a
  120. textbook teaches them, and shows you the contents page. Nothing is written until you approve it.
  121. 2. **Write.** One writer agent writes the whole chapter in one voice, from the book's one-page sheet
  122. (reader, promise, running project, pictures, names), a short guide for the kind of subject (a language,
  123. a tool, a framework, how a system works, or a professional skill) and one sample. What it is not sure
  124. of, it marks with a hidden risk note instead of stopping to look it up.
  125. 3. **Run, draw, check.** Scripts then run every program and terminal session and paste the real output,
  126. draw the figures from short descriptions, and check the chapter: a "Check yourself" in every section,
  127. nothing used before the section that teaches it, every reference pointing at a real section. A book
  128. with nothing to run (say, usability testing) sets `run: none` and teaches through worked cases.
  129. 4. **One review.** A fresh agent that did not write the chapter first settles a script-made list (the
  130. writer's risk notes, commands that can delete things, output that could not be run here), each item the
  131. cheapest sure way. Then it reads the chapter once, hunting five things a list cannot show: an example that
  132. disagrees with itself, something used before you have it, a page that shows what you would not see, too
  133. many new words at once, and repetition. After that, you are the reviewer, and what you report is fixed
  134. in place.
  135. 5. **Read and practise.** In your browser, with the tutor, or with no AI at all.
  136. </td>
  137. </tr>
  138. </table>
  139. The model writes only the teaching. Running code, pasting output, drawing, numbering, the contents page,
  140. key terms and the index are done by scripts, which cost no tokens.
  141. ---
  142. ## What it costs
  143. The current version was tested on three unlike subjects. In each, one Opus agent went from the learner's first
  144. "hi" to a planned book, a written first chapter and its review, in a clean copy:
  145. | First chapter of a book on | Kind | Words | Programs run | Time | Tokens |
  146. |---|---|---|---|---|---|
  147. | Python, for a spreadsheet user | language | about 7,800 | 33 of 33 | 11.8 min | 153,280 |
  148. | Operating systems, before an exam | system | about 13,400 | 26 of 26 | 13.1 min | 188,742 |
  149. | Usability testing, for a design intern | skill (nothing to run) | about 11,200 | none | 8.1 min | 139,542 |
  150. That is 12 to 20 tokens per word of finished chapter, planning and review included. The three chapters, as they
  151. came out, are in [`examples/final-validation/`](examples/final-validation/).
  152. Is it good? An independent reader agent, given only the chapter, the contents page and a card describing the
  153. learner, scores eight lines from 1 to 10 ([`tests/evals/RUBRIC.md`](tests/evals/RUBRIC.md)). The three chapters
  154. scored **8.4, 8.1 and 8.9**: 9 on depth and on exercises in all three, 9 or 10 on practical relevance, 8 or 9 on
  155. clarity and order, and 6 to 8 on accuracy. What costs points is small and real: one statement about a case nobody
  156. ran (false, in the operating systems chapter, and since fixed by the product's own review), examples whose details
  157. do not quite agree with each other, and more words than a busy learner needs. The older, costlier version is kept
  158. for comparison in [`examples/learn-git/`](examples/learn-git/) (about 290,000 tokens a chapter, rated 4.17 of 5).
  159. **Not measured yet:** how much of a Pro plan's usage one chapter takes. Write one chapter, look at your usage
  160. meter, and set your pace from that.
  161. ---
  162. ## A month with no AI
  163. Everything below runs on your machine with no subscription and no internet.
  164. **Read.** `python3 scripts/us_reader.py --serve`, then open http://localhost:8765. The reading page is a
  165. single offline file in your book: an expandable tree of the whole book (like `tree` on Linux), a graph of
  166. which chapters lean on which, and a reading view for chapters.
  167. <p align="center">
  168. <picture>
  169. <source media="(prefers-color-scheme: dark)" srcset="docs/readme/reading-page-dark.png">
  170. <img src="docs/readme/reading-page.png" alt="The reading page showing section 12.8 of a C book: the chapter's sections on the left, the section's question and picture in the middle with a figure, and the section's parts listed on the right." width="820">
  171. </picture>
  172. </p>
  173. **Practise.** `python3 scripts/us_practice.py` asks the "Check yourself" questions and practice exercises
  174. from the chapters you have, one at a time. You answer on paper or in your head, see the hidden answer,
  175. and say honestly whether you got it. Right answers come back later and later (1, 3, 7, 14, 30 days);
  176. missed ones come back tomorrow. The author's own 11-chapter C book gives 537 questions this way.
  177. ```text
  178. [1/2] Learn C · §12.1 Why files: data that outlives the program · new
  179. 1. You run a program that sets `int best = 0;`, reads ten scores and keeps the
  180. highest in `best`. You run it again tomorrow. What is `best` when the second
  181. run starts, and why?
  182. Answer:
  183. It's 0 again. The second run is a new process with fresh memory, and line one of
  184. `main` sets `best` to 0. [...]
  185. Did you get it? (y)es (p)artly (n)o (q)uit
  186. ```
  187. **Pick up where you left off.** `python3 scripts/us_resume.py` writes `private/RESUME.md` from your files
  188. alone. A real one, after one practice round:
  189. ```markdown
  190. ## Today, with no AI
  191. - Read chapter 12, File handling.
  192. - Practice: 0 questions due today, 73 new waiting.
  193. ## Weak spots
  194. - §12.1 Why files: data that outlives the program (missed 1)
  195. ## When your subscription is back, start with this sentence:
  196. > I'm back after a break. I was at my book Learn C, chapter 12, §12.1 Why files: data that
  197. > outlives the program. Read private/RESUME.md and private/practice.json, update my levels
  198. > from my offline practice, then go over §12.1, and pick up from there.
  199. ```
  200. ---
  201. ## The skills
  202. Nine skills. Claude Code loads the one that fits what you said; only that one costs tokens.
  203. | Skill | Loads when you... |
  204. |---|---|
  205. | `us-start` | begin, come back, set a goal, ask about progress or what is next |
  206. | `us-map` | need a subject planned as a book, or ask for a roadmap |
  207. | `us-write` | ask for a chapter, several chapters, notes from your own lectures, or a cheat sheet |
  208. | `us-draw` | ask for a diagram of something you are studying |
  209. | `us-review` | report a mistake in your book, or a chapter has just been written |
  210. | `us-teach` | want to study, ask a question, be quizzed or revise |
  211. | `us-build` | build your own project, get stuck on it, or want it reviewed |
  212. | `us-design` | practise system design or a mock interview |
  213. | `us-compete` | practise algorithms and contest problems |
  214. Writing and reviewing run in separate agents ([`.claude/agents/`](.claude/agents/)), so a chapter never
  215. fills your main conversation.
  216. Each skill is a short list of steps (under 1,000 tokens) with its own `references/` folder: one small file
  217. per topic, read only at the step that needs it. For example `us-write` has a guide for each of the five
  218. kinds of subject, one for each shape of section, pages on explaining, exercises and what to mark as
  219. risky, a checklist and three sample sections; `us-map` has a plan pattern per kind, sizing, sources and
  220. templates for the three files every book starts with. Each folder's `README.md` is the index.
  221. ## Commands you might type
  222. | Command | What it does |
  223. |---|---|
  224. | `python3 scripts/us_reader.py --serve` | open your books in the browser |
  225. | `python3 scripts/us_practice.py [BOOK] --due` | practise what is due today |
  226. | `python3 scripts/us_practice.py --stats` | your practice record and weak spots |
  227. | `python3 scripts/us_resume.py` | write the "where you left off" note |
  228. | `python3 scripts/us_doctor.py [BOOK]` | check that this machine can do what the book teaches, before any usage is spent |
  229. | `python3 scripts/us_plan.py cost BOOK` | hours of study and cost of writing, chapter by chapter |
  230. | `python3 scripts/us_plan.py needs BOOK 4.6 5.6` | the few sections to write when you need something now |
  231. | `python3 scripts/us_find.py WORDS --read` | find and print the section that teaches something |
  232. | `python3 scripts/us_plan.py status BOOK` | what is written and reviewed, chapter by chapter |
  233. | `python3 scripts/us_autopilot.py BOOK --chapters 3` | write chapters one after another with no conversation open |
  234. A ready-made contents page ships for Git: [`plans/learn-git/PLAN.md`](plans/learn-git/PLAN.md), 6 parts,
  235. 17 chapters, 189 sections, with a [practice card](plans/learn-git/PRACTICES.md) of current Git habits and
  236. their sources. When you ask to learn Git, the planner offers this plan first instead of drawing a new one.
  237. ---
  238. ## Honest limits
  239. - **Quality:** three first chapters (a language, a system, a professional skill) scored 8.1 to 8.9 out of 10
  240. from independent reader agents. Accuracy is the weakest line: expect a small slip or two in a chapter, and
  241. report it, because what you report is fixed in place. No person has rated a chapter yet; you are the first.
  242. - **Only first chapters were measured in this version.** A chapter deep inside a book, which leans on earlier
  243. ones, was measured only in the older version.
  244. - **Cost per session:** not measured (see above).
  245. - **Tools that keep things outside a folder (Docker):** the runner now tracks and removes what a book's
  246. runs make in Docker, never touches anything else, can press Ctrl-C and type into a container, and
  247. refuses commands that would wipe your own containers. This is proven on small home-made images. A full
  248. Docker chapter with real downloads has **not** been written yet, because the build machine cannot reach
  249. Docker Hub. A ready-made Docker plan is in [`plans/learn-docker/`](plans/learn-docker/). Databases,
  250. Kubernetes and cloud tools have no such support yet.
  251. - **When your machine cannot run something:** the machine check stops before a chapter is written and
  252. says why in plain words. What still cannot run is marked "not run" in the book and counted, never
  253. invented.
  254. - **Windows:** the scripts need Linux, macOS or WSL (which is also what Docker needs on Windows).
  255. - **Autopilot:** the script is tested with a stand-in for the agent. It has not yet written chapters of a
  256. real book unattended.
  257. - **Other systems:** the books try to flag commands that differ on macOS and Windows, but every chapter
  258. so far was written and run on Linux.
  259. - **Other agents:** `python3 scripts/install.py` makes the skills visible to Codex and Gemini CLI. Their
  260. format was checked against those tools' documentation; they have not been run there.
  261. Still to be done by a person: read a whole chapter and say where it lost you; write a Docker or Spring Boot
  262. chapter on a machine where downloads work; run a few chapters through the autopilot; read the usage meter after
  263. one chapter on a Pro plan.
  264. ## Helping
  265. - **Read a chapter and say where it lost you or what is wrong.** That is the review this system depends
  266. on. Open an issue with the section number.
  267. - Run the tests before and after a change to a script: `python3 tests/book/run.py`, and the same for
  268. `tests/run`, `tests/draw`, `tests/tools` and `tests/offline`. After a change to a skill or a rule, re-run the
  269. three learner cases in [`tests/evals/`](tests/evals/) and have a fresh reader score them.
  270. [`examples/final-validation/`](examples/final-validation/README.md) records what was measured and what was found;
  271. [`tests/evals/README.md`](tests/evals/README.md) says how to re-test.
  272. - Keep the agent's load small: a script beats an instruction, because a script costs no tokens.
  273. ## Standing on
  274. - **[persxn/learn-c-the-jojo-way](https://github.com/persxn/learn-c-the-jojo-way)**, the author's own C
  275. book (11 chapters, 284,695 words, 90 figures). It is the model every book here is measured against.
  276. - **[persxn/jojocode-ui-skill](https://github.com/persxn/jojocode-ui-skill)**, the design language of the
  277. reading page.
  278. - [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) for the rule of the smallest
  279. change that solves it; [emilkowalski/skills](https://github.com/emilkowalski/skills),
  280. [jakubkrehel/make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better),
  281. [addyosmani/web-quality-skills](https://github.com/addyosmani/web-quality-skills) and
  282. [vercel-labs/web-interface-guidelines](https://github.com/vercel-labs/web-interface-guidelines) for
  283. the interface work.
  284. - The teaching, diagram and graph projects studied, and exactly what was and was not taken from each, are
  285. listed in [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
  286. ---
  287. <div align="center">
  288. <picture>
  289. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/mark-dark.png">
  290. <img src="docs/brand/mark-light.png" alt="" width="48">
  291. </picture>
  292. For anyone learning to program on a budget · licence: [MIT](LICENSE)
  293. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.