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/`