codebase to course

Documentation Community

Skill notes

First-Run Welcome

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"

Who This Is For

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.

Why This Approach Works

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."

Phase 1: Codebase Analysis

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)

Phase 2: Curriculum Design

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. 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.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Documentation
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@zarazhangrui · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Codebase Analysis

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)

02
Phase 2: Curriculum Design

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. 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.

03
Phase 2.5: Module Briefs (complex codebases only)

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. Read `references/module-brief-template.md` for the template structure. Read `references/content-philosophy.md` for the content rules that should guide brief writing. For each module, write a brief to `course-name/briefs/0N-slug.md` containing:

04
Phase 3: Build the Course

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. Output structure: Step 1 (both paths): Setup — Create the course directory. Copy these four files verbatim using Read + Write (do not regenerate their contents): `references/styles.css` → `course-name/styles.css` `references/main.js` → `course-name/main.js`

05
Phase 4: Review and Open

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.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.