Skip to content
Back to search

codebase-to-course

"Turn any codebase into a beautiful, interactive single-page HTML course that teaches how the code works to non-technical people. Use this skill whenever someone wants to create an interactive course, tutorial, or educational walkthrough from a codebase or project. Also trigger when users mention 'turn this into a course,' 'explain this codebase interactively,' 'teach this code,' 'interactive tutorial from code,' 'codebase walkthrough,' 'learn from this codebase,' or 'make a course from this project.' This skill produces a stunning, self-contained HTML file with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zarazhangrui-codebase-to-course/badge.svg)](/listings/zarazhangrui-codebase-to-course)

HTML

<a href="/listings/zarazhangrui-codebase-to-course"><img src="/api/listings/zarazhangrui-codebase-to-course/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 221 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: codebase-to-course
  3. description: "Turn any codebase into a beautiful, interactive single-page HTML course that teaches how the code works to non-technical people. Use this skill whenever someone wants to create an interactive course, tutorial, or educational walkthrough from a codebase or project. Also trigger when users mention 'turn this into a course,' 'explain this codebase interactively,' 'teach this code,' 'interactive tutorial from code,' 'codebase walkthrough,' 'learn from this codebase,' or 'make a course from this project.' This skill produces a stunning, self-contained HTML file with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations."
  4. ---
  5. # Codebase-to-Course
  6. Transform any codebase into a stunning, interactive course. The output is a **directory** containing a pre-built `styles.css`, `main.js`, per-module HTML files, and an assembled `index.html` — open it directly in the browser with no setup required (only external dependency: Google Fonts CDN). The course teaches how the code works through scroll-based modules, animated visualizations, embedded quizzes, and plain-English translations of code.
  7. ## First-Run Welcome
  8. When the skill is first triggered and the user hasn't specified a codebase yet, introduce yourself and explain what you do:
  9. > **I can turn any codebase into an interactive course that teaches how it works — no coding knowledge required.**
  10. >
  11. > Just point me at a project:
  12. > - **A local folder** — e.g., "turn ./my-project into a course"
  13. > - **A GitHub link** — e.g., "make a course from https://github.com/user/repo"
  14. > - **The current project** — if you're already in a codebase, just say "turn this into a course"
  15. >
  16. > 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.
  17. 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 working directory.
  18. ## Who This Is For
  19. 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.
  20. **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.
  21. **Their goals are practical, not academic:**
  22. - Have enough technical knowledge to effectively **steer AI coding tools** — make better architectural and tech stack decisions
  23. - **Detect when AI is wrong** — spot hallucinations, catch bad patterns, know when something smells off
  24. - **Intervene when AI gets stuck** — break out of bug loops, debug issues, unblock themselves
  25. - Build more advanced software with **production-level quality and reliability**
  26. - Be **technically fluent** enough to discuss decisions with engineers confidently
  27. - **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")
  28. **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.
  29. ## Why This Approach Works
  30. 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.**
  31. 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."
  32. 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.*
  33. The directory-based output is intentional: separating CSS/JS from content means AI never regenerates boilerplate, each module is written independently (keeping output size small and quality high), and the assembled `index.html` works offline with zero setup.
  34. ---
  35. ## The Process
  36. ### Phase 1: Codebase Analysis
  37. 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.
  38. **What to extract:**
  39. - The main "actors" (components, services, modules) and their responsibilities
  40. - The primary user journey (what happens when someone uses the app end-to-end)
  41. - Key APIs, data flows, and communication patterns
  42. - Clever engineering patterns (caching, lazy loading, error handling, etc.)
  43. - Real bugs or gotchas (if visible in git history or comments)
  44. - The tech stack and why each piece was chosen
  45. **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."
  46. ### Phase 2: Curriculum Design
  47. Structure the course as **4-6 modules**. Most courses need 4-6. Only go to 7-8 if the codebase genuinely has that many distinct concepts worth teaching. Fewer, better modules beat more, thinner ones.
  48. 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.
  49. | Module Position | Purpose | Why it matters for a vibe coder |
  50. |---|---|---|
  51. | 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. |
  52. | 2 | Meet the actors | Know which components exist so you can tell AI "put this logic in X, not Y" |
  53. | 3 | How the pieces talk | Understand data flow so you can debug "it's not showing up" problems |
  54. | 4 | The outside world (APIs, databases) | Know what's external so you can evaluate costs, rate limits, and failure modes |
  55. | 5 | The clever tricks | Learn patterns (caching, chunking, error handling) so you can request them from AI |
  56. | 6 | When things break | Build debugging intuition so you can escape AI bug loops |
  57. | 7 | The big picture | See the full architecture so you can make better decisions about what to build next |
  58. This is a **menu, not a checklist**. Pick the modules that serve the codebase — a simple CLI tool needs 4, not 7. Adapt the arc to the codebase's complexity.
  59. **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.
  60. **Each module should contain:**
  61. - 3-6 screens (sub-sections that flow within the module)
  62. - At least one code-with-English translation
  63. - At least one interactive element (quiz, visualization, or animation)
  64. - One or two "aha!" callout boxes with universal CS insights
  65. - 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.
  66. **Mandatory interactive elements (every course must include ALL of these):**
  67. - **Group Chat Animation** — at least one across the course. These are the iMessage/WeChat-style conversations between components. They're one of the most engaging elements and must always appear, even if you have to creatively frame a module's concept as a conversation between actors.
  68. - **Message Flow / Data Flow Animation** — at least one across the course. The step-by-step packet animation between actors. If the codebase has any kind of request/response, data pipeline, or multi-step process, animate it. Every codebase has data flowing somewhere — find it.
  69. - **Code ↔ English Translation Blocks** — at least one per module (already required above, but reiterating: this is non-negotiable).
  70. - **Quizzes** — at least one per module (multiple-choice, scenario, drag-and-drop, or spot-the-bug — any quiz type counts).
  71. - **Glossary Tooltips** — on every technical term, first use per module.
  72. These five element types are the backbone of every course. Other interactive elements (architecture diagrams, layer toggles, pattern cards, etc.) are optional and should be added when they fit. But the five above must ALWAYS be present — no exceptions.
  73. **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 building. If they want changes, they'll tell you after seeing the result.
  74. **After designing the curriculum, decide which build path to use:**
  75. - **Simple codebase** (single-purpose CLI, small web app, library, one clear entry point, 5 or fewer modules) → go directly to Phase 3 Sequential.
  76. - **Complex codebase** (full-stack app, multiple services, content-heavy site, monorepo, or 6+ modules) → go to Phase 2.5 first, then Phase 3 Parallel.
  77. ### Phase 2.5: Module Briefs (complex codebases only)
  78. For complex codebases, write a brief for each module before writing any HTML. This is the critical step that enables parallel writing — each brief gives an agent everything it needs without re-reading the codebase.
  79. Read `references/module-brief-template.md` for the template structure. Read `references/content-philosophy.md` for the content rules that should guide brief writing.
  80. **For each module, write a brief to `course-name/briefs/0N-slug.md` containing:**
  81. - Teaching arc (metaphor, opening hook, key insight)
  82. - Pre-extracted code snippets (copy-pasted from the codebase with file paths and line numbers)
  83. - Interactive elements checklist with enough detail to build them
  84. - Which sections of which reference files the writing agent needs
  85. - What the previous and next modules cover (for transitions)
  86. The code snippets are the critical token-saving step. By pre-extracting them into the brief, writing agents never need to read the codebase at all.
  87. ### Phase 3: Build the Course
  88. The course output is a **directory**, not a single file. All CSS and JS are pre-built reference files — never regenerate them. Your job is to write only the HTML content.
  89. **Output structure:**
  90. ```
  91. course-name/
  92. styles.css ← copied verbatim from references/styles.css
  93. main.js ← copied verbatim from references/main.js
  94. _base.html ← customized shell (title, accent color, nav dots)
  95. _footer.html ← copied verbatim from references/_footer.html
  96. build.sh ← copied verbatim from references/build.sh
  97. briefs/ ← module briefs (complex codebases only, can delete after build)
  98. modules/
  99. 01-intro.html
  100. 02-actors.html
  101. ...
  102. index.html ← assembled by build.sh (do not write manually)
  103. ```
  104. **Step 1 (both paths): Setup** — Create the course directory. Copy these four files verbatim using Read + Write (do not regenerate their contents):
  105. - `references/styles.css` → `course-name/styles.css`
  106. - `references/main.js` → `course-name/main.js`
  107. - `references/_footer.html` → `course-name/_footer.html`
  108. - `references/build.sh` → `course-name/build.sh`
  109. **Step 2 (both paths): Customize `_base.html`** — Read `references/_base.html`, then write it to `course-name/_base.html` with exactly three substitutions:
  110. - Both instances of `COURSE_TITLE` → the actual course title
  111. - The four `ACCENT_*` placeholders → the chosen accent color values (pick one palette from the comments in `_base.html`)
  112. - `NAV_DOTS` → one `<button class="nav-dot" ...>` per module
  113. **Step 3: Write modules** — This is where the paths diverge.
  114. #### Sequential path (simple codebases)
  115. Read `references/content-philosophy.md` and `references/gotchas.md`. Then write modules one at a time. For each module, write `course-name/modules/0N-slug.html` containing only the `<section class="module" id="module-N">` block and its contents. Do not include `<html>`, `<head>`, `<body>`, `<style>`, or `<script>` tags.
  116. Read `references/interactive-elements.md` for HTML patterns for each interactive element type. Read `references/design-system.md` for visual conventions.
  117. #### Parallel path (complex codebases)
  118. Dispatch modules to subagents in batches of up to 3. Each agent receives:
  119. - Its module brief (from `course-name/briefs/`)
  120. - `references/content-philosophy.md` and `references/gotchas.md`
  121. - Only the sections of `references/interactive-elements.md` and `references/design-system.md` listed in the brief
  122. Each agent writes its module file(s) to `course-name/modules/`. Short modules (3 screens, one quiz) can be paired — two briefs given to one agent.
  123. **What agents do NOT receive:** the full codebase (snippets are in the brief), SKILL.md, other modules' briefs, or unneeded reference file sections.
  124. After all agents finish, do a quick consistency check in the main context: nav dots match modules, transitions between modules are coherent, no obvious tone shifts.
  125. **Step 4 (both paths): Assemble** — Run `build.sh` from the course directory:
  126. ```bash
  127. cd course-name && bash build.sh
  128. ```
  129. This produces `index.html`. Open it in the browser.
  130. **Critical rules:**
  131. - **Never regenerate** `styles.css` or `main.js` — always copy from references
  132. - Module files contain only `<section>` content — no boilerplate
  133. - Use CSS `scroll-snap-type: y proximity` (NOT `mandatory`)
  134. - Use `min-height: 100dvh` with `100vh` fallback on `.module`
  135. - Interactive element JS is in `main.js`; wire up via `data-*` attributes and CSS class names as shown in `references/interactive-elements.md`
  136. - Chat containers need `id` attributes; flow animations need `data-steps='[...]'` JSON on `.flow-animation`
  137. ### Phase 4: Review and Open
  138. After running `build.sh`, open `index.html` in the browser. Walk the user through what was built and ask for feedback on content, design, and interactivity.
  139. ---
  140. ## Design Identity
  141. 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:
  142. - **Warm palette**: Off-white backgrounds (like aged paper), warm grays, NO cold whites or blues
  143. - **Bold accent**: One confident accent color (vermillion, coral, teal — NOT purple gradients)
  144. - **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.
  145. - **Generous whitespace**: Modules breathe. Max 3-4 short paragraphs per screen.
  146. - **Alternating backgrounds**: Even/odd modules alternate between two warm background tones for visual rhythm
  147. - **Dark code blocks**: IDE-style with Catppuccin-inspired syntax highlighting on deep indigo-charcoal (#1E1E2E)
  148. - **Depth without harshness**: Subtle warm shadows, never black drop shadows
  149. ---
  150. ## Reference Files
  151. The `references/` directory contains detailed specs. **Read them only when you reach the relevant phase** — not upfront. This keeps context lean.
  152. - **`references/content-philosophy.md`** — Visual density rules, metaphor guidelines, quiz design, tooltip rules, code translation guidance. Read during Phase 2.5 (briefs) and Phase 3 (writing modules).
  153. - **`references/gotchas.md`** — Common failure points checklist. Read during Phase 3 and Phase 4 (review).
  154. - **`references/module-brief-template.md`** — Template for Phase 2.5 module briefs. Read only for complex codebases using the parallel path.
  155. - **`references/design-system.md`** — Complete CSS custom properties, color palette, typography scale, spacing system, shadows, animations, scrollbar styling. Read during Phase 3 when writing module HTML.
  156. - **`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 the relevant sections during Phase 3.
README.md · README · 92 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Codebase to Course
  2. A Claude Code skill that turns any codebase into a beautiful, interactive single-page HTML course.
  3. Point it at a repo. Get back a stunning, self-contained course that teaches how the code works — with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations.
  4. ## Who is this for?
  5. **"Vibe coders"** — people who build software by instructing AI coding tools in natural language, without a traditional CS education.
  6. You've built something (or found something cool on GitHub). It works. But you don't really understand *how* it works under the hood. This skill generates a course that teaches you — not by lecturing, but by tracing what happens when you actually use the app.
  7. **Your goals are practical, not academic:**
  8. - Steer AI coding tools better (make smarter architectural decisions)
  9. - Detect when AI is wrong (spot hallucinations, catch bad patterns)
  10. - Debug when AI gets stuck (break out of bug loops)
  11. - Talk to engineers without feeling lost
  12. You're not trying to become a software engineer. You want coding as a superpower.
  13. ## What the course looks like
  14. The output is a **single HTML file** — no dependencies, no setup, works offline. It includes:
  15. - **Scroll-based modules** with progress tracking and keyboard navigation
  16. - **Code ↔ Plain English translations** — real code on the left, what it means on the right
  17. <img width="720" alt="Code translation block" src="https://github.com/user-attachments/assets/fb9e7fac-05c1-4f98-b80c-46543ef81afc" />
  18. - **Animated visualizations** — data flow animations, group chat between components, architecture diagrams
  19. <img width="720" alt="Animated data flow" src="https://github.com/user-attachments/assets/20fb403e-7dfd-4a47-989b-bbae86ca8041" />
  20. - **Interactive quizzes** that test *application* not memorization ("You want to add favorites — which files change?")
  21. <img width="720" alt="Interactive quiz" src="https://github.com/user-attachments/assets/57706496-9fa8-457a-8450-3da22789951c" />
  22. - **Glossary tooltips** — hover any technical term for a plain-English definition
  23. <img width="720" alt="Glossary tooltip" src="https://github.com/user-attachments/assets/ac2f160a-d73f-4779-97b2-a06fdb5f3227" />
  24. - **Warm, distinctive design** — not the typical purple-gradient AI look
  25. ## How to use
  26. ### As a Claude Code skill
  27. 1. Copy the `codebase-to-course` folder into `~/.claude/skills/`
  28. 2. Open any project in Claude Code
  29. 3. Say: *"Turn this codebase into an interactive course"*
  30. ### Trigger phrases
  31. - "Turn this into a course"
  32. - "Explain this codebase interactively"
  33. - "Make a course from this project"
  34. - "Teach me how this code works"
  35. - "Interactive tutorial from this code"
  36. ## Design philosophy
  37. ### Build first, understand later
  38. This inverts traditional CS education. The old way: memorize concepts for years → eventually build something → finally see the point (most people quit before step 3). This way: **build something → experience it working → now understand how it works.**
  39. ### Show, don't tell
  40. Every screen is at least 50% visual. Max 2-3 sentences per text block. If something can be a diagram, animation, or interactive element — it shouldn't be a paragraph.
  41. ### Quizzes test doing, not knowing
  42. No "What does API stand for?" Instead: "A user reports stale data after switching pages. Where would you look first?" Quizzes test whether you can *use* what you learned to solve a new problem.
  43. ### No recycled metaphors
  44. Each concept gets a metaphor that fits *that specific idea*. A database is a library with a card catalog. Auth is a bouncer checking IDs. API rate limiting is a nightclub with a capacity limit. Never the same metaphor twice.
  45. ### Original code only
  46. Code snippets are exact copies from the real codebase — never modified or simplified. The learner should be able to open the actual file and see the same code they learned from.
  47. ## Skill structure
  48. ```
  49. codebase-to-course/
  50. ├── SKILL.md # Main skill instructions
  51. └── references/
  52. ├── design-system.md # CSS tokens, typography, colors, layout
  53. └── interactive-elements.md # Quiz, animation, and visualization patterns
  54. ```
  55. ---
  56. Built by [Zara](https://x.com/zarazhangrui) with Claude Code.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.