| name | codebase-to-course |
|---|---|
| description | Use when the user wants a codebase turned into a beautiful, interactive single-page HTML course that explains how the system works to non-technical people, especially for interactive tutorials, walkthroughs, or code explained in plain English. |
Transform any codebase into a stunning, interactive single-page HTML course. The output is a single self-contained HTML file (no dependencies except Google Fonts) that teaches how the code works through scroll-based modules, animated visualizations, embedded quizzes, and plain-English translations of code.
In Codex, the default is to inspect the codebase, synthesize the curriculum, and write the finished HTML file into the workspace. Do not stop at analysis unless the user explicitly asked for planning only.
When this skill is active in Codex, do the work directly:
- Read the repo yourself instead of asking the user to explain the product unless something is genuinely ambiguous
- Treat "this codebase" or "this project" as the current workspace root
- If the user provides a GitHub link, clone it into
/tmp/<repo-name>; if network or permissions block cloning, request approval instead of asking the user to paste files - Generate the finished course as a single self-contained HTML file in the workspace, usually named
<repo-name>-course.htmlunless the user asked for a different filename - Inline all CSS and JavaScript; Google Fonts is the only allowed external dependency
- Prefer HTML, CSS, SVG, and canvas over separate decorative assets so the course stays portable
- Finish by reporting the output path, the course arc, and any important assumptions or gaps in the source material
When the skill is first triggered and the user hasn't specified a codebase yet, introduce yourself and explain what you do:
I can turn any codebase into an interactive course that teaches how it works — no coding knowledge required.
Just point me at a project:
- A local folder — e.g., "turn ./my-project into a course"
- A GitHub link — e.g., "make a course from https://github.com/user/repo"
- The current workspace — if you're already in a codebase, just say "turn this into a course"
I'll read through the code, figure out how everything fits together, and generate a beautiful single-page HTML course with animated diagrams, plain-English code explanations, and interactive quizzes. The whole thing runs in your browser — no setup needed.
If the user provides a GitHub link, clone the repo first (git clone <url> /tmp/<repo-name>) before starting the analysis. If they say "this codebase" or similar, use the current workspace directory.
The target learner is a "vibe coder" — someone who builds software by instructing AI coding tools in natural language, without a traditional CS education. They may have built this project themselves (without looking at the code), or they may have found an interesting open-source project on GitHub and want to understand how it's built. Either way, they don't yet understand what's happening under the hood.
Assume zero technical background. Every CS concept — from variables to APIs to databases — needs to be explained in plain language as if the learner has never encountered it. No jargon without definition. No "as you probably know." The tone should be like a smart friend explaining things, not a professor lecturing.
Their goals are practical, not academic:
- Have enough technical knowledge to effectively steer AI coding tools — make better architectural and tech stack decisions
- Detect when AI is wrong — spot hallucinations, catch bad patterns, know when something smells off
- Intervene when AI gets stuck — break out of bug loops, debug issues, unblock themselves
- Build more advanced software with production-level quality and reliability
- Be technically fluent enough to discuss decisions with engineers confidently
- Acquire the vocabulary of software — learn the precise technical terms so they can describe requirements clearly and unambiguously to AI coding agents (e.g., knowing to say "namespace package" instead of "shared folder thing")
They are NOT trying to become software engineers. They want coding as a superpower that amplifies what they're already good at. They don't need to write code from scratch — they need to read it, understand it, and direct it.
This skill inverts traditional CS education. The old model is: memorize concepts for years → eventually build something → finally see the point (most people quit before step 3). This model is: build something first → experience it working → now understand how it works.
The learner already has context that traditional students don't — they've used the app, they know what it does, they may have even described its features in natural language. The course meets them where they are: "You know that button you click? Here's what happens under the hood when you click it."
Every module answers "why should I care?" before "how does it work?" The answer to "why should I care?" is always practical: because this knowledge helps you steer AI better, debug faster, or make smarter architectural decisions.
The single-file constraint is intentional: one HTML file means zero setup, instant sharing, works offline, and forces tight design decisions.
Before writing course HTML, deeply understand the codebase. Read all the key files, trace the data flows, identify the "cast of characters" (main components/modules), and map how they communicate. Thoroughness here pays off — the more you understand, the better the course.
What to extract:
- The main "actors" (components, services, modules) and their responsibilities
- The primary user journey (what happens when someone uses the app end-to-end)
- Key APIs, data flows, and communication patterns
- Clever engineering patterns (caching, lazy loading, error handling, etc.)
- Real bugs or gotchas (if visible in git history or comments)
- The tech stack and why each piece was chosen
Figure out what the app does yourself by reading the README, the main entry points, and the UI code. Don't ask the user to explain the product — they may not be familiar with it either. The course should open by explaining what the app does in plain language (a brief "here's what this thing does and why it's interesting") before diving into how it works. The first module should start with a concrete user action — "imagine you paste a YouTube URL and click Analyze — here's what happens under the hood."
Structure the course as 5-8 modules. The arc always starts from what the learner already knows (the user-facing behavior) and moves toward what they don't (the code underneath). Think of it as zooming in: start wide with the experience, then progressively peel back layers.
| Module Position | Purpose | Why it matters for a vibe coder |
|---|---|---|
| 1 | "Here's what this app does — and what happens when you use it" | Start with the product (what it does, why it's interesting), then trace a core user action into the code. Grounds everything in something concrete. |
| 2 | Meet the actors | Know which components exist so you can tell AI "put this logic in X, not Y" |
| 3 | How the pieces talk | Understand data flow so you can debug "it's not showing up" problems |
| 4 | The outside world (APIs, databases) | Know what's external so you can evaluate costs, rate limits, and failure modes |
| 5 | The clever tricks | Learn patterns (caching, chunking, error handling) so you can request them from AI |
| 6 | When things break | Build debugging intuition so you can escape AI bug loops |
| 7 | The big picture | See the full architecture so you can make better decisions about what to build next |
Not every codebase needs all 7. A simple CLI tool might only need 4-5 modules. A microservices app might need 8. Adapt the arc to the codebase's complexity — use your judgment on which modules are worth including based on what would actually help the learner steer AI and debug better.
The key principle: Every module should connect back to a practical skill — steering AI, debugging, making decisions. If a module doesn't help the learner DO something better, cut it or reframe it until it does.
Each module should contain:
- 3-6 screens (sub-sections that flow within the module)
- At least one code-with-English translation
- At least one interactive element (quiz, visualization, or animation)
- One or two "aha!" callout boxes with universal CS insights
- A metaphor that grounds the technical concept in everyday life — but NEVER reuse the same metaphor across modules, and NEVER default to the "restaurant" metaphor (it's overused). Pick metaphors that organically fit the specific concept. The best metaphors feel inevitable for the concept, not forced.
Do NOT present the curriculum for approval — just build it. The user wants a course, not a planning document. Design the curriculum internally, then go straight to generating the HTML. If they want changes, they'll tell you after seeing the result.
Generate a single HTML file with embedded CSS and JavaScript. Read references/design-system.md for the complete CSS design tokens, typography, and color system. Read references/interactive-elements.md for implementation patterns of every interactive element type.
Build order (task by task):
-
Foundation first — HTML shell with all module sections (empty), complete CSS design system, navigation bar with progress tracking, scroll-snap behavior, keyboard navigation, and scroll-triggered animations. After this step, you should have a working skeleton you can scroll through.
-
One module at a time — Fill in each module's content, code translations, and interactive elements. Don't try to write all 8 modules in one pass — the quality drops. Build Module 1, verify it works, then Module 2, etc.
-
Polish pass — After all modules are built, do a final pass for transitions, mobile responsiveness, and visual consistency.
Critical implementation rules:
- The file must be completely self-contained (only external dependency: Google Fonts CDN)
- Use CSS
scroll-snap-type: y proximity(NOTmandatory— mandatory traps users in long modules) - Use
min-height: 100dvhwith100vhfallback for sections - Only animate
transformandopacityfor GPU performance - Wrap all JS in an IIFE, use
passive: trueon scroll listeners, throttle withrequestAnimationFrame - Include touch support for drag-and-drop, keyboard navigation (arrow keys), and ARIA attributes
After generating the course HTML file, open it in the browser for the user to review. Walk them through what was built and ask for feedback on content, design, and interactivity.
These principles are what separate a great course from a generic tutorial. They should guide every content decision:
People's eyes glaze over text blocks. The course should feel closer to an infographic than a textbook. Follow these hard rules:
Text limits:
- Max 2-3 sentences per text block. If you're writing a fourth sentence, stop and convert it into a visual instead.
- No text block should ever be wider than the content width AND taller than ~4 lines. If it is, break it up with a visual element.
- Every screen must be at least 50% visual (diagrams, code blocks, cards, animations, badges — anything that isn't a paragraph).
Convert text to visuals:
- A list of 3+ items → cards with icons (pattern cards, feature cards)
- A sequence of steps → flow diagram with arrows or numbered step cards
- "Component A talks to Component B" → animated data flow or group chat visualization
- "This file does X, that file does Y" → visual file tree with annotations or icon + one-liner badges
- Explaining what code does → code↔English translation block (not a paragraph about the code)
- Comparing two approaches → side-by-side columns with visual contrast
Visual breathing room:
- Use generous spacing between elements (
--space-8to--space-12between sections) - Alternate between full-width visuals and narrow text blocks to create rhythm
- Every module should have at least one "hero visual" — a diagram, animation, or interactive element that dominates the screen and teaches the core concept at a glance
Every code snippet gets a side-by-side plain English translation. Left panel: real code from the project with syntax highlighting. Right panel: line-by-line plain English explaining what each line does. This is the single most valuable teaching tool for non-technical learners.
Critical: No horizontal scrollbars on code. All code must use white-space: pre-wrap so it wraps instead of scrolling. This is a course for non-technical people, not an IDE — readability beats preserving indentation structure.
Critical: Use original code exactly as-is. Never modify, simplify, or trim code snippets from the codebase. The learner should be able to open the real file and see the exact same code they learned from — that builds trust. Instead of editing code to make it shorter, choose naturally short, punchy snippets (5-10 lines) from the codebase that illustrate the concept well. Every codebase has compact, self-contained moments — find those rather than butchering longer functions.
No walls of text. Each screen within a module teaches exactly one idea. If you need more space, add another screen — don't cram.
Introduce every new concept with a metaphor from everyday life. Then immediately ground it: "In our code, this looks like..." The metaphor builds intuition; the code grounds it in reality.
Critical: No recycled metaphors. Do NOT default to "restaurant" for everything — that's the #1 crutch. Each concept deserves its own metaphor that feels natural to that specific idea. A database is a library with a card catalog. Auth is a bouncer checking IDs. An event loop is an air traffic controller. Message passing is a postal system. API rate limiting is a nightclub with a capacity limit. Pick the metaphor that makes the concept click, not the one that's easiest to reach for. If you catch yourself using "restaurant" or "kitchen" more than once in a course, stop and rethink.
Follow what actually happens when the learner does something they already do every day in the app — trace the data flow end-to-end. "You know that button you click? Here's the journey your data takes after you click it..." This works because the learner has already experienced the result — now they're seeing the machinery behind it. It's like watching a behind-the-scenes documentary of a movie you loved.
Use "aha!" callout boxes for universal CS insights. Use humor where natural (not forced). Give components personality — they're "characters" in a story, not abstract boxes on a diagram.
Every technical term (API, DOM, callback, middleware, etc.) gets a dashed-underline tooltip on first use in each module. Hover on desktop or tap on mobile to see a 1-2 sentence plain-English definition. The learner should never have to leave the page to Google a term. This is the difference between a course that says it's for non-technical people and one that actually is.
Be extremely aggressive with tooltips. If there is even a 1% chance a non-technical person doesn't know a word, tooltip it. This includes:
- Software names they might not know (Blender, GIMP, Audacity, etc.)
- Everyday developer terms (REPL, JSON, flag, CLI, API, SDK, etc.)
- Programming concepts (function, variable, dictionary, class, module, etc.)
- Infrastructure terms (PATH, pip, namespace, entry point, etc.)
- Acronyms — ALWAYS tooltip acronyms on first use
The vocabulary IS the learning. One of the key goals is for learners to acquire the precise technical vocabulary they need to communicate with AI coding agents. Each tooltip should teach the term in a way that helps the learner USE it in their own instructions — e.g., "A flag is an option you add to a command to change its behavior — like adding '--json' to get structured data instead of plain text. When talking to AI, you'd say 'add a flag for verbose output.'"
Cursor: Use cursor: pointer on terms (not cursor: help). The question-mark cursor feels clinical — a pointer feels clickable and inviting.
Tooltip overflow fix: Translation blocks and other containers with overflow: hidden will clip tooltips. To fix this, the tooltip JS must use position: fixed and calculate coordinates from getBoundingClientRect() instead of relying on CSS position: absolute within the container. Append tooltips to document.body rather than inside the term element. This ensures tooltips are never clipped by any ancestor's overflow.
The goal of learning is practical application — being able to do something with what you learned. Quizzes should test whether the learner can use their knowledge to solve a new problem, not whether they can regurgitate a definition.
What to quiz (in order of value):
- "What would you do?" scenarios — Present a new situation the learner hasn't seen and ask them to apply what they learned. e.g., "You want to add a 'save to favorites' feature. Which files would you need to change?" This is the gold standard.
- Debugging scenarios — "A user reports X is broken. Based on what you learned, where would you look first?" This tests whether they understood the architecture, not just memorized file names.
- Architecture decisions — "You're building a similar app from scratch. Would you put this logic in the frontend or backend? Why?" Tests whether they understood the reasoning behind design choices.
- Tracing exercises — "When a user does X, trace the path the data takes." Tests whether they can follow the flow.
What NOT to quiz:
- Definitions ("What does API stand for?") — that's what the glossary tooltips are for
- File name recall ("Which file handles X?") — nobody memorizes file names
- Syntax details ("What's the correct way to write a fetch call?") — this isn't a coding bootcamp
- Anything that can be answered by scrolling up and copying — that tests scrolling, not understanding
Quiz tone:
- Wrong answers get encouraging, non-judgmental explanations ("Not quite — here's why...")
- Correct answers get brief reinforcement of the underlying principle ("Exactly! This works because...")
- Never punitive, never score-focused. No "You got 3/5!" — the quiz is a thinking exercise, not an exam
- Wrong answer explanations should teach something new, not just say "wrong, the answer was B"
How many quizzes: One per module, placed at the end after the learner has seen all the content. 3-5 questions per quiz. Each question should make the learner pause and think, not just pick the obvious answer.
Deciding what concepts are worth quizzing: Quiz the things that would actually help someone in practice — architecture understanding ("where does this logic live and why?"), debugging intuition ("what would cause this symptom?"), and decision-making ("what's the tradeoff here?"). If a concept won't help someone debug a problem, steer an AI assistant, or make an architectural decision, it's not worth quizzing.
The visual design should feel like a beautiful developer notebook — warm, inviting, and distinctive. Read references/design-system.md for the full token system, but here are the non-negotiable principles:
- Warm palette: Off-white backgrounds (like aged paper), warm grays, NO cold whites or blues
- Bold accent: One confident accent color (vermillion, coral, teal — NOT purple gradients)
- Distinctive typography: Display font with personality for headings (Bricolage Grotesque, or similar bold geometric face — NEVER Inter, Roboto, Arial, or Space Grotesk). Clean sans-serif for body (DM Sans or similar). JetBrains Mono for code.
- Generous whitespace: Modules breathe. Max 3-4 short paragraphs per screen.
- Alternating backgrounds: Even/odd modules alternate between two warm background tones for visual rhythm
- Dark code blocks: IDE-style with Catppuccin-inspired syntax highlighting on deep indigo-charcoal (#1E1E2E)
- Depth without harshness: Subtle warm shadows, never black drop shadows
These are real problems encountered when building courses. Check every one before considering a course complete.
Translation blocks use overflow: hidden for code wrapping. If tooltips use position: absolute inside the term element, they get clipped by the container. Fix: Tooltips must use position: fixed and be appended to document.body. Calculate position from getBoundingClientRect(). This is already specified in the reference files but is the #1 bug that appears in every build.
The most common failure is under-tooltipping. Non-technical learners don't know terms like REPL, JSON, flag, entry point, PATH, pip, namespace, function, class, module, PR, E2E, or even software names like Blender/GIMP. Rule of thumb: if a term wouldn't appear in everyday conversation with a non-technical friend, tooltip it. Err heavily on the side of too many. BUT: don't tooltip terms the user already knows well from their domain (e.g., AI/ML concepts for someone in AI).
The course looks like a textbook instead of an infographic. This happens when you write more than 2-3 sentences in a row without a visual break. Every screen must be at least 50% visual. Convert any list of 3+ items into cards, any sequence into step cards or flow diagrams, any code explanation into a code↔English translation block.
Using "restaurant" or "kitchen" for everything. Every module needs its own metaphor that feels inevitable for that specific concept. If you catch yourself reaching for the same metaphor twice, stop and find one that fits the concept organically.
Trimming, simplifying, or "cleaning up" code snippets from the codebase. The learner should be able to open the real file and see the exact same code. Instead of editing code to be shorter, choose naturally short snippets (5-10 lines) from the codebase that illustrate the point.
Asking "What does API stand for?" or "Which file handles X?" — those test recall, not understanding. Every quiz question should present a new scenario the learner hasn't seen and ask them to apply what they learned.
Stopping after analysis notes, a module outline, or design ideas instead of writing the course file. In Codex, the default is to deliver the actual HTML artifact unless the user explicitly asked for a plan or critique only.
Using scroll-snap-type: y mandatory traps users inside long modules. Always use proximity.
Trying to write all modules in one pass causes later modules to be thin and rushed. Build one module at a time and verify each before moving on.
A module with only text and code blocks, no interactivity. Every module needs at least one of: quiz, data flow animation, group chat, architecture diagram, drag-and-drop. These aren't decorations — they're how non-technical learners actually process information.
The references/ directory contains detailed implementation specs. Read them when you reach the relevant phase:
references/design-system.md— Complete CSS custom properties, color palette, typography scale, spacing system, shadows, animations, scrollbar styling. Read this before writing any CSS.references/interactive-elements.md— Implementation patterns for every interactive element: drag-and-drop quizzes, multiple-choice quizzes, code↔English translations, group chat animations, message flow visualizations, architecture diagrams, pattern cards, callout boxes. Read this before building any interactive elements.