zarazhangrui/codebase-to-course

Purpose and Invocation

This repository is a Claude Code skill that analyzes an arbitrary target repository and produces a self-contained, interactive HTML course explaining it to nontraditional developers. The operational entry point is SKILL.md, which directs the agent’s analysis, curriculum planning, and HTML generation process.

Skill Orchestration

SKILL.md is the primary control layer. It defines how the skill should inspect a codebase, identify its architecture and runtime flows, select exact source snippets, and turn findings into course modules. It is intended to be installed under Claude Code’s skills directory rather than run as a standalone application.

Core path:

• SKILL.md

Course Generation Pipeline

The skill’s output boundary is one offline-capable HTML document. Its pipeline is conceptually:

1. Analyze the target repository’s structure and primary flows.

2. Build an architecture-focused learning plan.

3. Extract unmodified code from target-project files.

4. Compose visual modules, explanations, interactions, and quizzes.

5. Emit the completed single-page course.

The reusable course page foundation is supplied by:

• references/_base.html

• references/_footer.html

• references/build.sh

Presentation Runtime

Generated courses use browser-native HTML, CSS, and JavaScript rather than a framework or hosted backend. The base template establishes the document shell; references/styles.css provides the visual system; references/main.js supplies client-side behavior for navigation and interactive course elements.

Core paths:

• references/_base.html

• references/styles.css

• references/main.js

Content and Pedagogy Constraints

The skill is designed around experiential codebase explanation: tracing what happens during actual app use rather than teaching abstract computer-science concepts. It requires real, verbatim source snippets and favors visual explanations, concise text, and application-oriented quizzes.

The content rules and authoring guidance live in:

• references/content-philosophy.md

• references/gotchas.md

• references/module-brief-template.md

Interactive Learning Components

Interactive patterns—such as architecture diagrams, animated data-flow sequences, code-to-plain-English comparisons, and quizzes—are standardized separately from the page runtime. This makes course interactions a composable content layer that generated HTML can implement with the shared browser assets.

Core path:

• references/interactive-elements.md

Design-System Boundary

Visual consistency is centralized in the reference design system. It governs typography, colors, spacing, layout, and the distinctive non-generic course appearance, while generated course content supplies the codebase-specific modules.

Core path:

• references/design-system.md

Infrastructure and External Dependencies

There is no application server, database, API integration, package manifest, or deployment infrastructure in this repository. The material runtime is Claude Code for skill execution and the browser for consuming generated courses. The intended generated artifact has no runtime dependency on external services and works offline.