# Output Ladder
English | [简体中文](README.zh-CN.md)
Choose a useful medium for understanding a topic, then get a prompt to create it.
Output Ladder is an agent skill for turning a learning goal into clear writing, a diagram, an interactive web page, or an explainer video. It considers the audience and practical constraints, explains its choice, and produces a self-contained prompt you can reuse.
**It generates prompts by default.** Creating the actual page, diagram, or video is a separate request and depends on the tools available in your agent environment.
## The four-level ladder
| Level | Medium | Useful for | Example |
| --- | --- | --- | --- |
| L1 | Clear writing | Definitions, distinctions, rules, and reasoning | Explain Bayes' theorem with a worked example |
| L2 | Diagrams / images | Structure, relationships, flows, and comparisons | Map a system's components and data flow |
| L3 | Interactive web | Changing inputs and observing outcomes | Explore gradient descent with a learning-rate slider |
| L4 | Explainer video | Guided sequences, animation, and narrative | Explain an algorithm through a narrated walkthrough |
The ladder expands the available media; a higher level does not guarantee better understanding. The skill selects the simplest medium that meets your learning goal and constraints. L3 supports learner-controlled exploration, while L4 supports guided exposition without requiring interaction.
If you already know which medium you want, specify it and the skill will honor that choice.
## Installation
The skill instructions are in [`SKILL.md`](SKILL.md), at the root of this repository. No packages or API keys are required to install the skill itself.
Run the appropriate command from the root of your downloaded or cloned repository.
### Codex
Install for your user account:
```bash
mkdir -p "$HOME/.agents/skills/output-ladder"
cp SKILL.md "$HOME/.agents/skills/output-ladder/SKILL.md"
```
Invoke it with `$output-ladder` in your request.
### Claude Code
Install for your user account:
```bash
mkdir -p "$HOME/.claude/skills/output-ladder"
cp SKILL.md "$HOME/.claude/skills/output-ladder/SKILL.md"
```
For a project-specific installation, place the file at `.claude/skills/output-ladder/SKILL.md` inside that project instead.
Invoke it with `/output-ladder` followed by your request.
### Other agents
For environments supporting the Agent Skills format, install the `output-ladder` folder using that environment's instructions. You can also provide the contents of `SKILL.md` directly as instructions to an LLM; automatic discovery and invocation depend on the host.
## Usage
Natural language is enough. Describe the topic, who it is for, and any constraints. The response follows your language unless you request another.
For Codex:
```text
$output-ladder Help me understand Bayes' theorem. I'm a beginner; recommend a useful format and give me a prompt.
```
For Claude Code:
```text
/output-ladder Help me understand TCP congestion control. Use an interactive web page for beginners, offline, with no external dependencies.
```
You can also use field-style shorthand:
```text
/output-ladder topic: Raft consensus audience: beginner preference: video constraints: offline, 3 minutes, captions without narration
```
These fields guide the agent; they are not a strict command-line syntax.
| Input | Meaning | Default |
| --- | --- | --- |
| `topic` | Concept, system, or algorithm to understand | Required; inferred from the request when possible |
| `audience` | Beginner, intermediate, or expert | Intermediate when no context indicates otherwise |
| `preference` | L1–L4, writing, diagram/image, web, or video | Recommend a suitable medium |
| `constraints` | Offline, no API keys, stack, duration, budget, or accessibility needs | Follow constraints stated in the request |
## What you get
A response contains:
1. **Topic analysis:** The learning bottleneck and relevant audience assumptions.
2. **Recommended or selected level:** The medium and a brief rationale.
3. **Ready-to-use prompt:** A copyable prompt with content, deliverable, constraints, accuracy checks, and observable learning outcomes.
4. **Alternative options:** Up to two useful alternatives, omitted when you request only one format.
5. **Practical tips:** Suggestions for verification and iteration.
For example, an offline TCP congestion-control request can produce an L3 prompt for a simplified TCP Reno simulator with a congestion-window chart, loss-event controls, explicit model assumptions, and worked traces. See the [complete example in SKILL.md](SKILL.md#example).
Copy the generated prompt into an agent with the appropriate tools, or ask your current agent to use it to create the artifact.
## Constraints and quality
The skill applies your constraints to the main prompt, alternatives, and tool recommendations.
- **Offline:** No runtime network requests, CDNs, remote fonts, or cloud narration. One-time setup requirements are identified separately; specify “offline setup too” if dependencies must already be available locally.
- **No API keys:** Choose tools that do not require credentials. This is distinct from offline operation.
- **Video:** A storyboard, source project, and rendered video are different deliverables. State which you need; rendering requires an appropriate toolchain.
- **Accuracy:** Check key facts, equations, algorithm variants, and simulated behavior. Custom artifacts can be disposable while still requiring correct teaching content.
- **Writing:** ASD-STE100-inspired technical English is optional. Short sentences alone do not establish formal compliance with the standard.
Mermaid, native HTML/CSS/JS, Manim, and Remotion are possible artifact tools, not dependencies of this skill. Tool availability, costs, and generated output quality depend on your environment.
## Source and attribution
Inspired by [Andrej Karpathy's original post](https://x.com/karpathy/status/2105819303471976479) on understanding language-model outputs through writing, diagrams/images, web pages, and bespoke explainer videos.
The post presents these media progressively, discusses ASD-STE100 and 3b1b-style explainers, and advocates custom, discardable software artifacts. This project adds the **Understanding-First Output Ladder** name, L1–L4 labels, selection rules, parameters, and prompt templates. Those additions are project interpretations, not a named methodology from the original post. This project does not imply endorsement by Karpathy or affiliation with 3Blue1Brown.
## Contributing
Improvements to format selection, prompt quality, examples, and accessibility are welcome. Keep changes consistent with the skill's scope: choosing media and generating prompts for understanding.
When proposing a behavioral change, include a realistic request and the resulting output. Check explicit preferences, L1/L4 boundaries, offline constraints, and topic accuracy where relevant. Distinguish structural validation from actual model behavior testing.
## License
Released under the [MIT License](LICENSE).
The `SKILL.md` instructions and the README files are covered by the same MIT terms. The inspiration and attribution notes above describe provenance, not endorsement: the MIT grant applies to this project's own text, not to Andrej Karpathy's original post or to any third-party trademarks.