Skip to content
Back to search

understanding-ladder

MarketplaceWorks with Claude CodeGitHub

Karpathy's understanding ladder as agent skills: auto-pick text, diagram, interactive HTML, or video storyboard for any explanation. Nothing cut. English + 中文.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/changwenc--understanding-ladder/badge.svg)](/listings/changwenc--understanding-ladder)

HTML

<a href="/listings/changwenc--understanding-ladder"><img src="/api/listings/changwenc--understanding-ladder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Any agent that supports [Agent Skills](https://agentskills.io)** (Claude Code, Codex, Cursor, …), via [skills](https://github.com/vercel-labs/skills):

npx skills add ChangWenC/understanding-ladder

**Claude Code plugin:**

/plugin marketplace add ChangWenC/understanding-ladder
/plugin install understanding-ladder@understanding-ladder

**Manual** (Claude Code global skills directory):

git clone --depth 1 https://github.com/ChangWenC/understanding-ladder.git
cp -r understanding-ladder/skills/* ~/.claude/skills/

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.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "understanding-ladder",
  3. "owner": {
  4. "name": "ChangWenC",
  5. "url": "https://github.com/ChangWenC"
  6. },
  7. "metadata": {
  8. "description": "Karpathy's understanding ladder as agent skills (English + Chinese).",
  9. "version": "0.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "understanding-ladder",
  14. "source": "./",
  15. "description": "Karpathy's understanding ladder as agent skills: pick text, diagram, interactive HTML, or video storyboard by content type. English + Chinese (plain-chinese).",
  16. "version": "0.1.0"
  17. }
  18. ]
  19. }
README.md · README · 133 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # understanding-ladder
  2. **Agent skills that make LLM explanations easier to understand — built on Karpathy's understanding ladder.**
  3. English | [中文](README.zh-CN.md)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Claude%20Code%20%7C%20Codex%20%7C%20Cursor-d97757) ![Languages](https://img.shields.io/badge/output-English%20%7C%20中文-555)
  5. ![Before/after: a dense status update rewritten with every fact kept](docs/assets/hero-en.png)
  6. ```bash
  7. npx skills add ChangWenC/understanding-ladder
  8. ```
  9. **[Live demo →](https://changwenc.github.io/understanding-ladder/docs/demo/)** one explanation, rewritten at every rung.
  10. ---
  11. ## Why
  12. In October 2026, Andrej Karpathy [wrote](https://x.com/karpathy/status/2105819303471976479) that LLM output is nearly free; *understanding* it is the bottleneck. So stop accepting walls of text and ask for formats that are easier to understand. He ranked four, each "even better" than the last:
  13. | Rung | Format | Why it helps |
  14. |---|---|---|
  15. | 1 | Text in ASD-STE100 (controlled English) | One idea per sentence, one meaning per word |
  16. | 2 | Diagram | Structure laid out at once instead of line by line |
  17. | 3 | Interactive HTML page | Move the parameter, see the result change |
  18. | 4 | 3Blue1Brown-style explainer video | Animation + narration for processes over time |
  19. The hard part is not knowing the ladder. It is **picking the right rung every time** without being asked — and not climbing higher than the question needs. This repo turns that into a skill.
  20. ## What you get
  21. ### `understanding-ladder` — which format
  22. Classifies the content, recommends the **lowest rung that fully answers**, and produces it:
  23. | Content | Rung | Output |
  24. |---|---|---|
  25. | Definition, fact, procedure | 1 · text | ~80% ASD-STE100 in English, `plain-chinese` in Chinese |
  26. | Process, causality, states, components | 2 · diagram | Mermaid / SVG + "how to read this diagram" |
  27. | A parameter changes the outcome | 3 · page | Single-file HTML with sliders, opens with a double-click |
  28. | A derivation that unfolds over time | 4 · video | Storyboard + narration; [showtime](https://github.com/FavioVazquez/showtime) ≥ 0.4.0 renders it with `--from-storyboard` |
  29. Three rules hold on every rung:
  30. - **Nothing cut.** Simple language, not less content. Every number, condition, and hedge survives.
  31. - **Draft first.** Every diagram, page, or video starts from a rung-1 text draft you can check.
  32. - **"What to check" at the end.** Easier to understand ≠ verified.
  33. Works in English and Chinese — it replies in your language.
  34. → [SKILL.md](skills/understanding-ladder/SKILL.md) · [English examples](examples/understanding-ladder/en/) · [Chinese examples](examples/understanding-ladder/)
  35. ### `plain-chinese` — rung 1 for Chinese
  36. In English you can just say "in ASD-STE100" and the model knows the rules. **Chinese has no such name.** `plain-chinese` spells the rules out: 15 of them, grouped into words, sentences, paragraphs, what to delete, and what to keep. `understanding-ladder` calls it automatically for Chinese output.
  37. → [SKILL.md](skills/plain-chinese/SKILL.md) · [5 before/after pairs](examples/plain-chinese/)
  38. ## Demo: one explanation, every rung
  39. Topic: **why does server latency explode once utilization passes ~80%?**
  40. ![Demo page switching between rungs 0–4](docs/assets/ladder-demo-en.gif)
  41. [Open the live demo](https://changwenc.github.io/understanding-ladder/docs/demo/) (English / 中文 toggle, single file, no dependencies). Tab 3 has a slider: drag utilization from 90% to 95% — five more points, double the latency.
  42. ## Install
  43. **Any agent that supports [Agent Skills](https://agentskills.io)** (Claude Code, Codex, Cursor, …), via [skills](https://github.com/vercel-labs/skills):
  44. ```bash
  45. npx skills add ChangWenC/understanding-ladder
  46. ```
  47. **Claude Code plugin:**
  48. ```text
  49. /plugin marketplace add ChangWenC/understanding-ladder
  50. /plugin install understanding-ladder@understanding-ladder
  51. ```
  52. **Manual** (Claude Code global skills directory):
  53. ```bash
  54. git clone --depth 1 https://github.com/ChangWenC/understanding-ladder.git
  55. cp -r understanding-ladder/skills/* ~/.claude/skills/
  56. ```
  57. ## Use
  58. Just ask. The skill triggers from its description:
  59. ```text
  60. Help me understand how learning rate affects convergence.
  61. Explain the TLS 1.3 handshake the clearest way.
  62. An agent wrote this plan — help me see what it actually does.
  63. Walk me through the Fourier series from rung 1 to rung 4.
  64. ```
  65. No install? Paste this (Karpathy's "80%" plus the one rule that matters most):
  66. ```text
  67. Write about 80% of the way to ASD-STE100: one idea per sentence, one term per meaning, active voice, no filler. Cut nothing — keep every fact, number, condition, and hedge; just make the sentences clean.
  68. ```
  69. ## Limits
  70. - **Easier to understand ≠ verified.** The ladder lowers the cost of understanding, not of checking. A polished artifact lowers your guard; an error in an animation is more convincing than in text. Hence "What to check" on every output.
  71. - Rung 4 writes the storyboard; rendering is done by a video tool. [showtime](https://github.com/FavioVazquez/showtime) 0.4.0+ reads the table directly (`showtime new <template> <dir> --from-storyboard storyboard.md`, English or Chinese headers).
  72. - `plain-chinese` is a lightweight rule set for LLMs, not a full writing standard. Sentence-length numbers are rules of thumb, not tested in reading studies.
  73. - The examples were produced by following the skills and checked by hand. They show direction, not a benchmark.
  74. ## Related work
  75. | Project | What it does | Difference |
  76. |---|---|---|
  77. | [FutureAtoms/karpathy-ladder](https://github.com/FutureAtoms/karpathy-ladder) | English ladder skill; renders diagrams, spec sheets, and video with Playwright/Manim | This repo is zero-dependency, picks the *lowest* sufficient rung, and covers Chinese |
  78. | [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill) | English STE rewriting with a linter | Rung 1 only; this repo covers the whole ladder |
  79. | [mzopedia/simplified-technical-chinese](https://github.com/mzopedia/simplified-technical-chinese) | A full Simplified Technical Chinese spec: 40 rules, word list, checker | Heavier and more formal; use it for documentation. `plain-chinese` targets LLM explanations |
  80. Ideas only; no content copied.
  81. ## Credits
  82. - The ladder comes from [Andrej Karpathy's post](https://x.com/karpathy/status/2105819303471976479).
  83. - Rung 1 is **inspired by [ASD-STE100](https://www.asd-ste100.org/); not affiliated with ASD.** No STE rule text or dictionary is reproduced. ASD-STE100 is a registered trademark of ASD.
  84. - Rung 4 tools: [showtime](https://github.com/FavioVazquez/showtime), [Manim](https://www.manim.community/), [Kokoro](https://github.com/hexgrad/kokoro).
  85. ## License
  86. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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