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.reference/*.md: A directory of Markdown reference materials (compiled toreference/*.htmlbybuild.py, withGLOSSARY.mdcompiling toglossary.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.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. Titled0001-<dash-case-name>.md, incrementing sequentially. Use the format in LEARNING-RECORD-FORMAT.md.lessons/*.md: A directory of Markdown lesson sources (compiled tolessons/*.htmlbybuild.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 toindex.htmlbybuild.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.mdsource files are tracked in Git (index.html,lessons/*.html, andreference/*.htmlare gitignored and generated locally via.venv/bin/python build.py --checkor 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.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:
- 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.
- Never write lesson prose assuming the learner has
- 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.
- 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.
- 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.
- Tutorial code (in lesson snippets, complete listings, interactive exercises, and
Markdown Directives & Frontmatter (build.py)
Follow the exact schema in 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-warnand:::callout-successfor 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">). Criticalbuild.pyrule: Always extract fenced code blocks into single-line placeholders (<!--FENCED_CODE_PLACEHOLDER_N-->) before callingmd.render()(and before rewriting links or sidenotes), then restore the rendered<div class="code-figure">/<figure class="mermaid-figure">HTML aftermd.render()completes, and verify inbuild.py --checkthat no<pre><code...>contains<p>,<h1..6>, or nested<pre>tags. If<div class="code-figure"><pre><code>...is injected directly beforemd.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 byTable: 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||insideanswerfor multi-answer alternatives likesize.x / 2.0||size.x * 0.5), and a mandatory nested:::promptsYAML block (hintandsuccesskeys) before the outer closing:::. - Verification & Test Coverage Gates:
:::verify id="verify-NNNN" title="Verification Lab: ..." badge="..."(with optionaltier,caught,missedattributes 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 4optionswithletter,text,correct: true|false,explain).build.py --checkenforces 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 inassets/course.js. Inbuild_lesson_cards_html(), strip any leadingLesson NNNN •prefix frombadgebefore combining it withLESSON {num}so.lesson-card-metanever 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 inbuild.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 leadinghbefore\1so 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 beforemd.render()and restoring them afterward somarkdown-it-pynever turns subscripts ($R_1 + R_2$) into<em>tags or strips backslash escapes, then rendering them via KaTeX (katex.min.css,katex.min.js, andcontrib/auto-render.min.jsrenderMathInElementinassets/course.js). Enforce inbuild.py --checkthat: (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):
- Static Site Builder & Listing Helper (
uv+scripts/sync_listing.py):- Use
.venv/bin/python build.py --out-dir _site --check(created viauv venvanduv 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 ... Listingblocks inline, run scripts/sync_listing.py with--writeto inject the exact formatted companion source into the lesson and--checkto verify byte-for-byte parity across all lessons.
- Use
- Copy-Then-Apply Progression &
.gitignoreHygiene:- 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 ascp -cRon 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
.gitignoreexcludes compiled build outputs (apps/*/target/,_site/, generated*.html) before staging any files with Git.
- Start at the first lesson (
- 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) againstapps/<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 --checkand.venv/bin/python build.py --out-dir _site --checkafter 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, orassets/course.js, reconcile immediately before moving on.
- Run the formatter first (
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-widthtuned 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 printoverride: Use dark mode across all lessons andreference/*.htmldocuments (<meta name="color-scheme" content="dark">in<head>and:root { color-scheme: dark; }inassets/style.css), paired with a@media printlight-mode override (hiding top navigation controls, bottom pagers, and interactive buttons) so lessons and reference sheets print cleanly on paper. Pairscrollbar-coloron:rootwithscrollbar-width: thin(required on macOS so custom scrollbars render) and wrap legacy::-webkit-scrollbarfallbacks in@supports not (scrollbar-color: auto). Use high-contrastaccent-colortokens 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-visibleandoutline-offset: 2pxvia:where(...)(never bare:focus), applytext-wrap: balanceto headings/table headers (h1, h2, h3, th) andtext-wrap: prettyto body copy (p, li, blockquote), use semantic HTML landmarks (<header>,<nav>,<main>,<article>,<footer>), and ensure scrollable<pre>code blocks receivetabindex="0"for keyboard scrolling (handled automatically inassets/course.js). - Prism.js for syntax highlighting: Format all code blocks with Prism.js (
<pre><code class="language-<lang>">), and load the Prismkeep-markupplugin 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 withtheme: "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.jsconfigured inassets/course.jswithignoredTags: ["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:
- Flat Lesson List First & Minimal Tufte Breadcrumb Header (
build_nav_html&build_lesson_pager_htmlinbuild.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 NNNNon lessons — orIndex › <Section> › Lesson NNNNonce a larger course is sectioned —Index › <Sheet Name>on reference pages, andIndexon the landing page) witharia-current="page"on the active item. - Right (
.nav-controls): On lesson pages, a compact← Prev · Next →pill group (.nav-pager-group) with full lesson titletitle="..."tooltips, separated by|from the reference sheet links (Glossary, cheat sheets) and.mission-badge.
- Left (
- 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 NNNNandNext • Lesson NNNN →cards showing full lesson titles (and hidden in@media print).
- Start with a flat sequential list of lessons on
- Synchronize Navigation & Index via
build.py --checkon 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 toREADME.md. - Run
.venv/bin/python build.py --checksobuild.pyautomatically regenerates<nav class="course-nav">and<nav class="lesson-pager">across every page, updates the.lesson-cardgrid inindex.html, compiles all.mdfiles to.html, and validates equal-word-count quiz rules and internal.mdlinks (rewritten to.html).
- Populate its YAML frontmatter (
- 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 viagh api --method POST repos/<owner>/<repo>/pages -f build_type=workflow(and rungh run rerun <run-id>if the initial push'sdeployjob failed before Pages was enabled). - Configure
.github/workflows/pages.ymlto runpython build.py --out-dir _site --checkto 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-deprecationon theactions/deploy-pages@v4step to suppress the benign Node.js[DEP0040] DeprecationWarning: The punycode module is deprecatedwarning.
- Before or immediately after pushing to
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 toreference/*.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/andapps/ - Selecting the next step toward the mission in
MISSION.mdandNOTES.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.mdandreference/*.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
:::exerciseand Prismkeep-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).
- Interactive fill-in-the-blank code blocks (using
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). 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.