---
name: teach-code
description: >-
  Interactive, stateful code-teaching workflow that builds self-contained HTML lessons (compiled from Markdown via build.py), printable reference sheets, learning records, and runnable per-lesson companion projects in ./apps/ verified with automated tests and linters. Use when the user asks to learn a programming language, framework, or engineering tool, build or extend an interactive coding course, create lessons or reference sheets, or invokes /teach-code or /teach.
title: teach-code
canonical_url: https://skilld.dev/gh/domesticmouse/skills/teach-code
last_updated: 2026-11-17T04:08:44.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/GLOSSARY-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/GLOSSARY-FORMAT.md), [references/LEARNING-RECORD-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/LEARNING-RECORD-FORMAT.md), [references/LESSON-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/LESSON-FORMAT.md), [references/MISSION-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/MISSION-FORMAT.md), [references/RESOURCES-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/RESOURCES-FORMAT.md), [scripts/sync_listing.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/scripts/sync_listing.py).
>
> If the user asked to install this Skill, run `npx skilld install domesticmouse/skills/teach-code`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/teach-code`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/domesticmouse/skills/teach-code) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/teach-code`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/teach-code --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/teach-code --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Interactive Code-Teaching Workflow (`teach-code`)

The user has asked you to teach them a programming topic or build out interactive course materials. This is a stateful request — they intend to learn the topic over multiple sessions by building real, verified software.

## Teaching Workspace (`.` or `./tutorial/`)

By default, use the repository root (`.`) as the teaching workspace for dedicated course repositories, or `./tutorial/` when adding a course inside an existing project repository (so root project files remain untouched). All course paths below are relative to the chosen teaching workspace root, while `references/*-FORMAT.md` links resolve from this skill's directory:

- `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This grounds all teaching. Use the format in [MISSION-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/MISSION-FORMAT.md).
- `reference/*.md`: A directory of Markdown reference materials (compiled to `reference/*.html` by `build.py`, with `GLOSSARY.md` compiling to `glossary.html`). These are the compressed learnings from the lessons — mental models, API/syntax cheat sheets, verification/testing guides, and glossaries. They are the raw units of learning, designed for quick lookup and clean printing.
- `RESOURCES.md`: A curated list of trusted primary sources, official documentation, and workspace skills (`.agents/skills/*`) used to ground your teaching in verified knowledge. Use the format in [RESOURCES-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/RESOURCES-FORMAT.md).
- `learning-records/*.md`: A directory of learning records capturing what the user has learned. These are loosely equivalent to architectural decision records (ADRs) — they capture non-obvious lessons, prior knowledge, and key insights that drive future sessions and calculate the zone of proximal development. Titled `0001-<dash-case-name>.md`, incrementing sequentially. Use the format in [LEARNING-RECORD-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/LEARNING-RECORD-FORMAT.md).
- `lessons/*.md`: A directory of Markdown lesson sources (compiled to `lessons/*.html` by `build.py`). A **lesson** is a single, self-contained tutorial unit that teaches one tightly-scoped concept or capability paired with an automated verification gate tied to the mission. This is the primary unit of teaching in this workspace.
- `index.md`: The Markdown course landing page (compiled to `index.html` by `build.py`) for local browsing and GitHub Pages hosting, auto-rendering lesson cards via `{{widget:lesson-cards}}` and reference sheet links/cards via `{{widget:reference-cards}}`.
- `build.py`: The Markdown-to-HTML static site builder (`markdown-it-py` + `pyyaml`). Only `.md` source files are tracked in Git (`index.html`, `lessons/*.html`, and `reference/*.html` are gitignored and generated locally via `.venv/bin/python build.py --check` or in CI via `.github/workflows/pages.yml`).
- `apps/<NNNN-lesson-slug>/`: A series of runnable project directories where each directory represents the exact, verifiable state of the companion application or script after completing the corresponding lesson (`lessons/<NNNN-lesson-slug>.md`).
- `assets/*`: Reusable **components** shared across lessons (`style.css`, `course.js`, quiz/exercise widgets, interactive simulators). See [Assets](#assets).
- `README.md`: Repository overview linking to the live GitHub Pages site (when hosted), published lessons, reference sheets, and license.
- `NOTES.md`: A scratchpad for recording user preferences, the curriculum roadmap, and working notes.

## Philosophy

To learn at a deep level, the user needs three things:

- **Knowledge**, captured from high-quality, high-trust resources (official language/framework documentation, primary texts, and any verified `.agents/skills/*` reference guides in the repository).
- **Skills**, acquired through highly-relevant interactive lessons devised by you, based on the knowledge.
- **Wisdom**, which comes from interacting with other learners and practitioners in real-world communities.

Before `RESOURCES.md` is well-populated, your focus should be to catalog high-quality resources (both external primary documentation and any verified `.agents/skills/*` skills in the workspace) to help the user acquire knowledge. Never trust unverified parametric knowledge when a compiler check, test suite, linter, script, or official documentation lookup can verify it.

### Fluency vs Storage Strength

Always distinguish between two types of learning:

- **Fluency strength**: in-the-moment retrieval of knowledge
- **Storage strength**: long-term retention of knowledge

Fluency can give an illusory sense of mastery, whereas storage strength is the real goal. Design lessons that build long-term retention through desirable difficulty:

- **Retrieval practice**: Recall from memory via interactive fill-in-the-blank code exercises and multiple-choice quizzes.
- **Spacing**: Distributing practice and revisiting earlier concepts across lessons.
- **Interleaving**: Mixing related skills (e.g., data modeling, API usage, error handling, and test assertions) within exercises and verification labs.

## Lessons & Markdown-to-HTML Pipeline (`build.py`)

A lesson is the primary artifact you produce: the unit in which knowledge and skills reach the user. Each lesson is authored as a clean Markdown file saved to `lessons/` and titled `0001-<dash-case-name>.md` (or starting at `0000-<dash-case-name>.md` / `0001-<dash-case-name>.md` for environment and project bootstrap), then compiled to HTML (`lessons/<NNNN-slug>.html`) by running `.venv/bin/python build.py --check`.

When teaching a programming language, framework, or tool where subsequent lessons need a configured project manifest, virtual environment, linter, and test runner, start with a bootstrap lesson covering project initialization, dependency setup, entry-point wiring, and test/lint configuration so every subsequent lesson builds on a concrete, runnable foundation.

### Explaining Code: Block-by-Block Walkthrough Followed by Full Context

When introducing or modifying code in a lesson, use the **Block-by-Block + In-Context** pattern to keep cognitive load low while giving the learner a self-contained, runnable reference:

1. **Start from Nothing & Grow the Code Inline (Never Assume External File References):**
   - Never write lesson prose assuming the learner has `apps/<NNNN-slug>/...` open in another window, and never link to relative source files outside the compiled site (such as `../apps/...`), which would 404 on GitHub Pages.
   - Start from a minimal foundation in the first lesson and progressively grow the codebase across lessons, showing both the newly added blocks step-by-step and the complete runnable code (with its verified terminal output) directly inside each lesson.
2. **Break Out Logical Blocks First (`### Block N: ...`):**
   - Instead of dropping a large file or function all at once and explaining it after the fact, split new or changed code into small, self-contained blocks (e.g., imports & configuration, data structures/types, core logic, inline tests).
   - For each block, show **only the relevant snippet** in a fenced code block, immediately followed by a focused bulleted breakdown unpacking the syntax, types, data flow, and API calls in that block.
3. **Show the Code in Full Context Next (`### Complete ... Listing`):**
   - After walking through the individual blocks, provide the complete source file or full surrounding module/function in context so the learner can see exactly how the pieces fit together and copy or compare the runnable code without guesswork.
4. **Keep Code Blocks Mostly Just Code (No License Headers or Massive Block Comments):**
   - Tutorial code (in lesson snippets, complete listings, interactive exercises, and `apps/<NNNN-slug>/` companion files) does not need license headers, ASCII banner dividers, or massive declarative block comments.
   - Put the commentary and explanations in the prose of the lesson, and let the code blocks, for the most part, just be clean, readable code.
   - When configuring linters or verification checks for `apps/<NNNN-slug>/`, rely on strict compiler diagnostics (e.g., `-Wall -Wextra -Werror -pedantic`), formatters, and test suites rather than upstream patch-check scripts that force license headers or boilerplate comment banners into tutorial source files.

### Markdown Directives & Frontmatter (`build.py`)

Follow the exact schema in [LESSON-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/LESSON-FORMAT.md). All course pages (`index.md`, `lessons/*.md`, `reference/*.md`) use YAML frontmatter (`title`, `page_title`, `nav_id`, `badge`, `subtitle`, plus `card.title` / `card.summary` for lessons and reference sheets, or `nav_label` for reference sheets) and clean Markdown directives compiled by `build.py`.

**Critical attribute & link syntax**: `build.py` parses **space-separated `key="value"` attributes**, never MyST/Pandoc curly braces (`{}`): write `:::quiz id="..."`, `:::callout title="..."`, and ```` ```rust caption="..." ```` (not `:::quiz{id="..."}` or ```` ```rust{caption="..."} ````). Always link internal documents using `.md` paths (e.g., `../reference/GLOSSARY.md`) so `build.py` rewrites them to exact output filenames (`glossary.html`).

- **Tufte Sidenotes**: `{{sidenote:Inline Markdown note text...}}` (renders a numbered superscript `<span class="sidenote-number"></span><span class="sidenote">...</span>` in the right margin on wide viewports, or toggles inline on narrow screens).
- **Callouts & Teacher Prompts**: `:::callout` (plus optional variants like `:::callout-warn` and `:::callout-success` for recommended primary sources, warnings, and notes) and `:::teacher-prompt title="..."` (for next-step prompts and reminders to ask questions) ... `:::`
- **Code Blocks & Mermaid Diagrams**: Fenced code blocks with language identifiers and optional space-separated captions (e.g., ```` ```rust ````, ```` ```python ````, ```` ```bash caption="Optional caption" ````), and ```` ```mermaid caption="Figure N.1: ..." ```` (wrapped in `<figure class="mermaid-figure">`). **Critical `build.py` rule**: Always extract fenced code blocks into single-line placeholders (`<!--FENCED_CODE_PLACEHOLDER_N-->`) *before* calling `md.render()` (and before rewriting links or sidenotes), then restore the rendered `<div class="code-figure">` / `<figure class="mermaid-figure">` HTML *after* `md.render()` completes, and verify in `build.py --check` that no `<pre><code...>` contains `<p>`, `<h1..6>`, or nested `<pre>` tags. If `<div class="code-figure"><pre><code>...` is injected directly before `md.render()`, CommonMark HTML block rules terminate the HTML block at the first blank line inside the code and parse the remaining code lines (such as `#  define ...` or 4-space indented C blocks) as Markdown headings, paragraphs, and nested code blocks!
- **Tables**: Standard GFM pipe tables (`| ... |`), optionally preceded by `Table: Caption text`, automatically styled with `<table class="ref-table">`.
- **Interactive Fill-in-the-Blank Exercises**: `:::exercise id="ex-NNNN" title="Interactive Lab: ..." badge="Skill Practice • Tight Feedback Loop"` containing explanatory prose, a fenced code block with `{{blank:answer|error_hint|placeholder|width}}` tokens (use `||` inside `answer` for multi-answer alternatives like `size.x / 2.0||size.x * 0.5`), and a **mandatory nested `:::prompts` YAML block** (`hint` and `success` keys) before the outer closing `:::`.
- **Verification & Test Coverage Gates**: `:::verify id="verify-NNNN" title="Verification Lab: ..." badge="..."` (with optional `tier`, `caught`, `missed` attributes when mutation testing is used) containing prose, test/verification commands and code blocks, and `- [ ]` step checklist items.
- **Multiple-Choice Quizzes**: `:::quiz id="quiz-NNNN" title="Retrieval Practice: ..." badge="3 Questions • Equal-Length Options"` with a YAML list of questions (`question`, `wrong_hint`, and exactly 4 `options` with `letter`, `text`, `correct: true|false`, `explain`). `build.py --check` enforces that all 4 options within each question have identical whitespace-split word counts!
- **Interactive Widgets**: `{{widget:lesson-cards}}`, `{{widget:reference-cards}}`, and custom interactive simulators (`{{widget:<simulator-id>}}`) defined in `assets/course.js`. In `build_lesson_cards_html()`, strip any leading `Lesson NNNN •` prefix from `badge` before combining it with `LESSON {num}` so `.lesson-card-meta` never duplicates the lesson number (e.g., `LESSON 0001 • Embedded C99 & GPIO`).
- **Heading Anchor Suffixes (`{#id}`) & TeX Math (`KaTeX`)**: Support `{#anchor-id}` at the end of Markdown headings in `build.py` (e.g., `re.sub(r"<h([1-6])>(.*?)\s*\{#([A-Za-z0-9_-]+)\}\s*</h\1>", r'<h\1 id="\3">\2</h\1>', html)` — always preserve the leading `h` before `\1` so malformed `<2 id="...">` tags never appear!). Support inline (`$...$`) and display (`$$...$$`) TeX math by protecting math spans (after fenced code blocks and inline `` `...` `` code spans) with placeholders before `md.render()` and restoring them afterward so `markdown-it-py` never turns subscripts (`$R_1 + R_2$`) into `<em>` tags or strips backslash escapes, then rendering them via **KaTeX** (`katex.min.css`, `katex.min.js`, and `contrib/auto-render.min.js` `renderMathInElement` in `assets/course.js`). Enforce in `build.py --check` that: (a) neither raw `{#...}` tokens nor malformed `<[1-6]` tags appear in rendered HTML, (b) no bare un-delimited TeX macros (`\approx`, `\pm`, `\Omega`, `\times`, `\le`, `\ge`, `\frac`, etc.) appear in prose outside `$...$`/`$$...$$` and `<pre>`/`<code>`, and (c) KaTeX assets are loaded whenever math delimiters are present.

### Runnable Per-Lesson Companion Apps (`apps/<NNNN-lesson-slug>/`)

Back every lesson with a real, runnable directory under `apps/<NNNN-lesson-slug>/` (matching the lesson filename stem):

1. **Static Site Builder & Listing Helper (`uv` + `scripts/sync_listing.py`):**
   - Use `.venv/bin/python build.py --out-dir _site --check` (created via `uv venv` and `uv pip install markdown-it-py pyyaml`) to compile and validate all Markdown lessons, reference sheets, internal links, and quiz option word counts, removing temporary `_site/` outputs afterward.
   - Instead of writing or pasting 500–1,500 line `Complete ... Listing` blocks inline, run [scripts/sync_listing.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/scripts/sync_listing.py) with `--write` to inject the exact formatted companion source into the lesson and `--check` to verify byte-for-byte parity across all lessons.
2. **Copy-Then-Apply Progression & `.gitignore` Hygiene:**
   - Start at the first lesson (`apps/0001-.../`) and progressively grow the application across lessons.
   - For each subsequent lesson $N$, copy the previous lesson's directory into `apps/<N>/` (using copy-on-write such as `cp -cR` on macOS/APFS when build directories are cloned), apply the new lesson's code and test updates, and update file timestamps (`touch`) if reusing incremental build artifacts so the compiler or test runner always builds the new lesson's code.
   - Verify `.gitignore` excludes compiled build outputs (`apps/*/target/`, `_site/`, generated `*.html`) before staging any files with Git.
3. **Execute, Format, Lint All Targets, Test & Validate After Every Lesson:**
   - Run the formatter first (`cargo fmt`, etc.), then run tests and strict linters across **all targets including unit test modules** (e.g., `cargo clippy --all-targets -- -D warnings`, `-Wall -Wextra -Werror`) against `apps/<NNNN-slug>/` before syncing the listing.
   - Ensure zero compiler/linter warnings and 100% passing tests (plus zero missed mutants when mutation testing is part of the workflow).
   - **Per-lesson validation gate**: Even when authoring multiple lessons in sequence, run `.venv/bin/python .agents/skills/teach-code/scripts/sync_listing.py --check` and `.venv/bin/python build.py --out-dir _site --check` after **each** lesson so schema, link, or quiz word-count errors never accumulate across files. If anything differs between runnable code/output and lessons, `reference/*.md`, or `assets/course.js`, reconcile immediately before moving on.

### Visual Design, Layout Rules, Prism.js, Mermaid.js & KaTeX

A lesson should be **beautiful**, with clean, readable typography and layout (think Edward Tufte), since the user will return to these materials to review:

- **Tufte-inspired layout**: Pair a readable main prose column (`max-width` tuned for ~65–75 characters per line) with a dedicated right margin for numbered sidenotes (`{{sidenote:...}}`), while allowing tables, code listings, interactive simulators, and Mermaid figures to span cleanly without horizontal cramping.
- **Dark mode by default with `@media print` override**: Use dark mode across all lessons and `reference/*.html` documents (`<meta name="color-scheme" content="dark">` in `<head>` and `:root { color-scheme: dark; }` in `assets/style.css`), paired with a `@media print` light-mode override (hiding top navigation controls, bottom pagers, and interactive buttons) so lessons and reference sheets print cleanly on paper. Pair `scrollbar-color` on `:root` with `scrollbar-width: thin` (required on macOS so custom scrollbars render) and wrap legacy `::-webkit-scrollbar` fallbacks in `@supports not (scrollbar-color: auto)`. Use high-contrast `accent-color` tokens for interactive form controls.
- **Modern web typography, transitions, and accessibility**: Enable cross-document view transitions (`@view-transition { navigation: auto; }` inside `@media (prefers-reduced-motion: no-preference)`), style focus rings with `:focus-visible` and `outline-offset: 2px` via `:where(...)` (never bare `:focus`), apply `text-wrap: balance` to headings/table headers (`h1, h2, h3, th`) and `text-wrap: pretty` to body copy (`p, li, blockquote`), use semantic HTML landmarks (`<header>`, `<nav>`, `<main>`, `<article>`, `<footer>`), and ensure scrollable `<pre>` code blocks receive `tabindex="0"` for keyboard scrolling (handled automatically in `assets/course.js`).
- **Prism.js for syntax highlighting**: Format all code blocks with Prism.js (`<pre><code class="language-<lang>">`), and load the Prism `keep-markup` plugin when embedding interactive `<input>` fill-in-the-blank tokens inside code blocks. Never hand-roll syntax `<span>` tags.
- **Mermaid.js for diagrams**: Use Mermaid.js (`<pre class="mermaid">` configured with `theme: "dark"`, wrapped in `<figure class="mermaid-figure">`) for architecture, lifecycle, state-machine, data-flow, and hierarchy diagrams instead of ASCII-art diagrams.
- **KaTeX for math rendering**: Render inline (`$...$`) and display (`$$...$$`) TeX equations with KaTeX (`katex.min.css` + `katex.min.js` + `contrib/auto-render.min.js` configured in `assets/course.js` with `ignoredTags: ["script", "noscript", "style", "textarea", "pre", "code", "option"]`). Always wrap TeX commands (`\Omega`, `\approx`, `\pm`, `\times`) inside `$...$` or `$$...$$` delimiters (or use standard Unicode like `Ω`, `≈`, `±` in plain text) so bare backslash macros never leak into prose.

### Course Index, Navigation & GitHub Pages Hosting

Keep the course navigable both locally and on GitHub Pages without cluttering the header bar:

1. **Flat Lesson List First & Minimal Tufte Breadcrumb Header (`build_nav_html` & `build_lesson_pager_html` in `build.py`):**
   - Start with a flat sequential list of lessons on `index.md` (`{{widget:lesson-cards}}`) rather than prematurely breaking the course into "Acts" or multi-part sections. Only introduce section groupings once enough lessons are published to warrant them.
   - Never dump all individual lesson numbers (`0001`–`0030`) into `<nav class="course-nav">`. Keep the top bar high-signal and single-line using two flex groups:
     - **Left (`.nav-breadcrumbs`)**: Contextual breadcrumb trail (`Index › Lesson NNNN` on lessons — or `Index › <Section> › Lesson NNNN` once a larger course is sectioned — `Index › <Sheet Name>` on reference pages, and `Index` on the landing page) with `aria-current="page"` on the active item.
     - **Right (`.nav-controls`)**: On lesson pages, a compact `← Prev · Next →` pill group (`.nav-pager-group`) with full lesson title `title="..."` tooltips, separated by `|` from the reference sheet links (`Glossary`, cheat sheets) and `.mission-badge`.
   - **Bottom-of-Lesson Pagination Cards (`.lesson-pager`)**: `build_lesson_pager_html()` automatically appends a two-column `<nav class="lesson-pager" aria-label="Lesson pagination">` footer at the end of every lesson article with `← Previous • Lesson NNNN` and `Next • Lesson NNNN →` cards showing full lesson titles (and hidden in `@media print`).
2. **Synchronize Navigation & Index via `build.py --check` on Every New Lesson:** Whenever you add or update a lesson (`lessons/<NNNN-slug>.md`) or reference sheet (`reference/*.md`):
   - Populate its YAML frontmatter (`title`, `page_title`, `nav_id`, `badge`, `subtitle`, `card`) and add the link to `README.md`.
   - Run `.venv/bin/python build.py --check` so `build.py` automatically regenerates `<nav class="course-nav">` and `<nav class="lesson-pager">` across every page, updates the `.lesson-card` grid in `index.html`, compiles all `.md` files to `.html`, and validates equal-word-count quiz rules and internal `.md` links (rewritten to `.html`).
3. **GitHub Pages Deployment (`.github/workflows/pages.yml` & `.nojekyll`):**
   - Before or immediately after pushing to `main`, verify whether GitHub Pages is already enabled (`gh api repos/<owner>/<repo>/pages`). On a fresh repository (`404 Not Found`), enable workflow-based Pages via `gh api --method POST repos/<owner>/<repo>/pages -f build_type=workflow` (and run `gh run rerun <run-id>` if the initial push's `deploy` job failed before Pages was enabled).
   - Configure `.github/workflows/pages.yml` to run `python build.py --out-dir _site --check` to compile the Markdown sources directly into `_site/` (`index.html`, `.nojekyll`, `assets/`, `lessons/*.html`, `reference/*.html`) so companion code directories (`apps/`) and internal tracking files (`MISSION.md`, `RESOURCES.md`, `NOTES.md`, `learning-records/`) are excluded from the published web artifact.
   - Pass `env: NODE_OPTIONS: --no-deprecation` on the `actions/deploy-pages@v4` step to suppress the benign Node.js `[DEP0040] DeprecationWarning: The punycode module is deprecated` warning.

Each lesson should be short, focused, and completable quickly within working-memory limits, giving the user a single tangible win directly tied to the mission and within their zone of proximal development.

If possible, open the compiled lesson file for the user or provide a direct clickable link. Every lesson should:
- Link via Markdown/HTML anchors to adjacent lessons and `reference/*.md` (compiled to `reference/*.html`) documents.
- Recommend a primary source (such as the relevant official documentation page, specification, book chapter, or workspace skill reference).
- Include a reminder (`:::teacher-prompt`) to ask follow-up questions to the agent.

## Assets

Lessons are built from reusable **components** stored in `assets/`: stylesheets, quiz widgets, interactive simulators or visualizers, fill-in-the-blank code completion exercises, and anything else a second lesson could reuse.

Reuse is the default, not the exception. Before authoring a lesson, read `assets/` and build from the components already there. When a lesson needs something new and reusable, write it as a component in `assets/` and wire it into `build.py`; never inline code a future lesson would duplicate.

A shared dark-mode stylesheet (`assets/style.css`) and a shared script (`assets/course.js`) that centrally loads and configures **Prism.js** (including `keep-markup` and the target language grammars), **Mermaid.js** (`theme: "dark"`), and **KaTeX** (including `auto-render`) alongside reusable quiz, fill-in-the-blank code exercise, and simulator widgets are the foundational components of the workspace: every lesson and reference sheet links them so the course looks and behaves like one cohesive site.

## The Mission

Every lesson should be tied into the mission — the reason the user is learning the topic, captured in `MISSION.md`.

If the user is unclear about aspects of the mission, or `MISSION.md` is not yet populated, ask clarifying questions **one at a time** to confirm their concrete goal, starting point, and what success looks like.

Missions may evolve as the user develops more skills and knowledge. Update `MISSION.md` and add a learning record when the mission shifts, confirming with the user first.

## Zone Of Proximal Development

Each lesson should challenge the user "just enough". Determine the next lesson by:

- Reading `learning-records/`
- Checking what has already been built in `lessons/` and `apps/`
- Selecting the next step toward the mission in `MISSION.md` and `NOTES.md`

## Knowledge & Skills

- **Knowledge**: Design each lesson around a concrete skill. Present only the knowledge required to acquire that skill, backed by citations to `RESOURCES.md` and `reference/*.html`. Keep cognitive load low during knowledge acquisition by breaking out new code block by block, explaining each snippet in isolation, and then showing the full code in context.
- **Skills**: Build durability through effortful retrieval and immediate feedback loops:
  - Interactive fill-in-the-blank code blocks (using `:::exercise` and Prism `keep-markup`).
  - Multiple-choice retrieval quizzes (`:::quiz`) with immediate feedback. **Quiz rule**: Every option within a quiz question must have the exact same word count (and similar character length), with the correct answer position varied across questions so formatting or length never leaks the answer.
  - Hands-on terminal verification, testing, and linting steps (`:::verify`).

## Acquiring Wisdom

Wisdom comes from testing skills in real-world engineering communities (e.g., official project GitHub Discussions, Discord/Zulip servers, and moderated language/framework forums). Include high-signal communities in `RESOURCES.md` while respecting any user preferences regarding community participation.

## Reference Documents

While creating lessons, maintain `reference/*.md` cheat sheets (compiled to `reference/*.html` by `build.py`) — the compressed essence of the lessons designed for quick reference and clean printing (e.g., mental model & API cheat sheets, testing & verification cheat sheets, and a Glossary following [GLOSSARY-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/teach-code/references/GLOSSARY-FORMAT.md)). Once a glossary is created, adhere to its terminology across every lesson.

## `NOTES.md`

Record any teaching preferences, curriculum roadmaps, or workflow notes expressed by the user in `NOTES.md` and consult it before designing each lesson.
