Index of every page on this site: llms.txt
All skills
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/domesticmouse/skills/teach-code

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning3d3 checks · Risk SAFE
  • Gen Agent Trust Hub3d

    The teach-code skill provides a structured framework for generating interactive coding tutorials. It includes a utility script for synchronizing source code into lesson files, which incorporates safety checks to prevent path traversal. The workflow relies on standard development tools and well-known libraries for document processing.

  • Socket3d

    No alerts

  • Snyk3d

    Risk: MEDIUM · 1 issue

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago

README badge

README badge for domesticmouse/skills/teach-code