aradotso/trending-skills/codebase-to-course

---
name: codebase-to-course
description: Generate beautiful, interactive single-page HTML courses from any codebase using Claude Code — teaching non-technical vibe coders how their code works through animations, quizzes, and plain-English translations.
triggers:
  -"turn this codebase into a course"
  -"explain this codebase interactively"
  -"make a course from this project"
  -"teach me how this code works"
  -"interactive tutorial from this code"
  -"generate a course from this repo"
  -"create an HTML course for this project"
  -"make this codebase learnable"
---
 
# Codebase to Course
 
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
 
A Claude Code skill that turns any codebase into a beautiful, self-contained single-page HTML course. Designed for "vibe coders" — people who build with AI tools and want to understand their own codebase well enough to steer AI better, debug more effectively, and talk to engineers confidently.
 
## What it produces
 
A **single HTML file** with zero dependencies that works offline, containing:
 
-Scroll-based modules with progress tracking and keyboard navigation
-Code ↔ Plain English side-by-side translations using real code from the repo
-Animated visualizations — data flow, component group chats, architecture diagrams
-Interactive quizzes testing *application* ("which files change if you add favorites?"), not memorization
-Glossary tooltips on hover for every technical term
-Warm, distinctive design (not the typical purple-gradient AI aesthetic)
 
## Installation
 
### As a Claude Code skill
 

Clone the repo

git clone https://github.com/zarazhangrui/codebase-to-course

Install the skill

cp -r codebase-to-course/codebase-to-course ~/.claude/skills/

 
The skill folder structure after install:
 

~/.claude/skills/codebase-to-course/ ├── SKILL.md # Main skill instructions Claude reads └── references/ ├── design-system.md # CSS tokens, typography, colors, layout rules └── interactive-elements.md # Quiz, animation, visualization code patterns

 
### Verify installation
 
Open any project in Claude Code and say one of the trigger phrases. Claude will read `SKILL.md` and the reference files before generating the course.
 
## How to use
 
### Basic invocation
 
Open a project in Claude Code and say any of:
 

"Turn this codebase into an interactive course" "Teach me how this code works" "Make a course from this project" "Explain this codebase interactively"

 
Claude will:
1. Analyze the codebase structure (entry points, key files, data flow)
2. Identify the most important concepts for a vibe coder to understand
3. Generate a single `course.html` file in the project root
 
### What Claude analyzes
 
Claude reads and synthesizes:
- Entry points (`main.py`, `index.js`, `app.py`, `server.ts`, etc.)
- Key architectural files (routes, models, components, services)
- Config files to understand environment and dependencies
- README and any existing docs for intent/context
 
### Output location
 
By default, the course is saved as `course.html` in the project root. You can specify a different location:
 

"Turn this into a course and save it as docs/tutorial.html"

 
## Course structure Claude generates
 
Each course follows this module pattern:
 

Module 1: What Does This App Actually Do? → The "user journey" — what happens when someone uses it → Architecture overview diagram (animated)

Module 2: The Pieces (Components/Files/Services) → What each major piece does in plain English → How they talk to each other (group chat visualization)

Module 3: The Data → What gets stored, where, in what shape → Data flow animation (user action → processing → storage → response)

Module 4: [Feature-specific modules] → Real code snippets with side-by-side plain English → Quizzes on applying the concept

Module 5: Now You Can... → What you can now do better (steer AI, debug, talk to engineers) → Glossary of all technical terms used

 
## Design system (from `references/design-system.md`)
 
Claude follows strict design rules when generating courses:
 

/ Core design tokens Claude uses / :root { --bg: #faf9f7; / Warm off-white background / --text: #1a1916; / Near-black text / --accent: #d4651f; / Warm orange accent / --accent-light: #f5e6d8; / Light accent for highlights / --mono: 'JetBrains Mono', monospace; --sans: 'Inter', system-ui, sans-serif; }

 
Key layout rules:
- Every screen is at least 50% visual (diagram, animation, or interactive element)
- Max 2–3 sentences per text block
- Code snippets are **exact copies** from the real codebase — never simplified or modified
- No recycled metaphors — each concept gets a fresh one
 
## Interactive elements (from `references/interactive-elements.md`)
 
### Quiz pattern
 

<!-- Claude generates quizzes like this — testing application, not memory --> <div class="quiz-block" data-quiz-id="unique-id"> <p class="quiz-question"> A user reports stale data after switching pages. Where would you look first? </p> <div class="quiz-options"> <button class="quiz-option" data-correct="false"> The database schema </button> <button class="quiz-option" data-correct="true"> The cache invalidation logic in <code>src/hooks/useData.ts</code> </button> <button class="quiz-option" data-correct="false"> The CSS for the loading spinner </button> </div> <div class="quiz-feedback quiz-feedback--hidden"> <p class="quiz-explanation"> Stale data across page switches usually means the cache isn't being cleared when it should be. The <code>useData</code> hook controls when data gets refreshed. </p> </div> </div>

 
### Data flow animation pattern
 

<!-- Claude generates SVG animations showing data moving through the system --> <div class="flow-animation" data-flow="user-request"> <svg viewBox="0 0 800 200"> <!-- Nodes: Browser → API → Auth → DB → Response --> <g class="flow-node" data-step="1"> <rect x="20" y="80" width="120" height="40" rx="8"/> <text x="80" y="104">Browser</text> </g> <!-- Animated path between nodes --> <path class="flow-path" d="M 140 100 L 220 100" stroke-dasharray="80" stroke-dashoffset="80"> <animate attributeName="stroke-dashoffset" from="80" to="0" dur="0.5s" begin="flow-step-1.end"/> </path> <!-- ... more nodes ... --> </svg> <div class="flow-caption"> <span class="flow-step-label" data-step="1"> You click "Submit" — your browser packages the form data </span> </div> </div>

 
### Glossary tooltip pattern
 

<!-- Technical terms get automatic tooltips --> <span class="glossary-term" data-definition="A function that runs when data changes — like a notification that says 'hey, update yourself'"> useEffect </span>

 
### Code translation block pattern
 

<!-- Real code on the left, plain English on the right --> <div class="translation-block"> <div class="translation-code"> <pre><code class="language-typescript"> export async function GET(request: Request) { const { searchParams } = new URL(request.url) const id = searchParams.get('id') const item = await db.items.findUnique({ where: { id } }) if (!item) return NextResponse.json({ error: 'Not found' }, { status: 404 }) return NextResponse.json(item) } </code></pre> <p class="code-source">From: <code>app/api/items/route.ts</code></p> </div> <div class="translation-english"> <p> When someone asks for a specific item by ID, look it up in the database. If it doesn't exist, say "not found" (404). If it does, send it back. </p> <p> This is the <strong>API endpoint</strong> — the door your frontend knocks on to get data. </p> </div> </div>

 
## Directing Claude for better courses
 
### Specify your goal
 

"Make a course from this project — I want to understand it well enough to add a user favorites feature with AI help"

"Turn this into a course focused on the authentication flow — I keep breaking login when I add features"

 
### Specify what to skip
 

"Make a course from this, but skip the payment processing parts — focus on the core CRUD operations"

 
### Specify your background
 

"Make this into a course assuming I know what an API is but have never touched a database before"

 
### Ask for a specific module
 

"Just generate the data flow module for this codebase — I already understand the architecture"

 
## Common patterns Claude follows
 
### Metaphor rules
 
Each concept gets a unique metaphor that fits it specifically:
 
| Concept | Metaphor Claude might use |
|---|---|
| Database | Library with a card catalog |
| Auth/JWT | Wristband from a bouncer — proves you paid to get in |
| API | A restaurant menu — you can only order what's listed |
| Cache | Sticky note on your monitor vs. going to the filing cabinet |
| Webhook | A friend who texts you when something happens vs. you calling to check |
| Environment variables | The settings hidden behind a panel — not in the blueprint |
 
### What makes a good quiz question (Claude generates these)
 
❌ Bad: "What does API stand for?"  
✅ Good: "You want to add a 'favorites' feature. Based on what you learned, which files would you need to change?"
 
❌ Bad: "What HTTP method does GET use?"  
✅ Good: "A user says their profile changes aren't saving. You check the network tab and see a 200 OK response. Where would you look next?"
 
## Troubleshooting
 
### Course is too generic
 
**Problem:** Claude generated a course that could apply to any project.  
**Fix:** Tell Claude to read specific files first:
 

"Before making the course, read src/app/page.tsx, lib/db.ts, and api/routes/index.ts — the course should be specific to how THIS app works"

 
### Course is too technical
 
**Problem:** Explanations still feel like documentation.  
**Fix:** Redirect Claude's tone:
 

"Regenerate the course — explain everything as if you're texting a smart friend who has never coded but uses apps all day"

 
### Course is missing a key concept
 
**Problem:** Something important to the codebase isn't covered.  
**Fix:** Be explicit:
 

"The course is missing how the real-time updates work (Socket.io). Add a module between Module 3 and 4 that explains that with an animation"

 
### HTML file is too large to open smoothly
 
**Problem:** Very large codebases produce a very large HTML file.  
**Fix:** Scope the course:
 

"Make a focused course — just the authentication system and the main data models. Skip third-party integrations."

 
### Quizzes are too easy
 
**Problem:** Quiz questions are testing recall not application.  
**Fix:**
 

"The quizzes feel like trivia. Regenerate them so every question starts with a scenario: 'A user reports that...' or 'You want to add...'"

 
## Design principles to reinforce
 
If Claude drifts from the design philosophy, remind it:
 

"Remember: every screen should be at least 50% visual. If you wrote three paragraphs in a row, turn one into a diagram."

"Code snippets must be exact copies from the actual files — don't simplify or modify the real code."

"Quizzes test doing, not knowing. No definition questions — only scenario questions."

 
## Project links
 
- **Repository:** https://github.com/zarazhangrui/codebase-to-course
- **Built by:** [Zara Zhang Rui](https://x.com/zarazhangrui)
- **Skill install path:** `~/.claude/skills/codebase-to-course/`