# Codebase To Course > ```markdown - Skill: `aradotso-trending-skills/codebase-to-course` (Agent Skill) - Install (CLI): `npx skillmds@latest add aradotso-trending-skills/codebase-to-course` - Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso-trending-skills/codebase-to-course/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: aradotso (https://skillmd.com/u/aradotso-trending-skills) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/aradotso-trending-skills/codebase-to-course --- ```markdown --- 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 ```bash # 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: ```css /* 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 ```html

A user reports stale data after switching pages. Where would you look first?

Stale data across page switches usually means the cache isn't being cleared when it should be. The useData hook controls when data gets refreshed.

``` ### Data flow animation pattern ```html
Browser
You click "Submit" — your browser packages the form data
``` ### Glossary tooltip pattern ```html useEffect ``` ### Code translation block pattern ```html 

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)
}

From: app/api/items/route.ts

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.

This is the API endpoint — the door your frontend knocks on to get data.

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