SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslesson-screen

lesson-screen

Coding & development

View repository

Updated 11-02 21:54

About this skill

Learning screen

The learning screen consists of a local web server and a browser tab. The tutor keeps teaching in the terminal. Write one screen file per step; the browser shows the latest file. Learners can click options and parts; clicks are recorded in an event log, which the tutor reads before the next reply.

Works with Claude, Cursor, Codex, OpenClaw, Hermes, and all agents that can read SKILL.md. Requires Node.js 20 or later and a browser on the same machine. No dependency packages need to be installed.

When to use

  • The course tutor is teaching and the learner agrees to use the screen. Tutors include learn, learn-mcp, learn-agent-skills, learn-reverse-engineering, claude-certification, and mcpa-certification.
  • The learner asks to be shown a course, concept, or system, e.g., "show me," "draw it," "use 3D."
  • The concept involves structure, flow, or numerical change, and a diagram is easier to understand than words.

When not to use

  • The learner has already declined the screen for this session. Do not bring it up again in this session.
  • The learner cannot access the host's browser page, e.g., a terminal-less chat app, or a remote machine without port forwarding. Provide the course page at aieng-zh.cn. See for details references/hosts.md。
  • The current step is text only, e.g., a clarifying question, a tradeoff, or a definition. Keep explaining in the terminal; the screen shows a waiting state.
  • A permanent diagram that needs to be written into the course files. Use the chart skill directly; this skill makes screens for a single learner.

Paths

SKILL_ROOT is the directory containing this SKILL.md. Below, CLI means node "$SKILL_ROOT/scripts/lesson-screen.mjs"。

All commands run from the learner's working directory. Screens are stored in .lesson-screen/screens/, and chart builds are stored in .lesson-screen/builds/. If the working directory is a Git repository, ask the learner to add .lesson-screen/ to .gitignore。

Starting

  1. Run CLI start --open. The command outputs one line of JSON containing url、screens、state and next。
  2. Give the learner the full url including the query string. The key in it protects page access.
  3. You can run CLI startagain at any time. It reuses the running server and keeps the port unchanged.
  4. If startup fails, explain in one sentence, give the course page link, and continue teaching.

Some hosts terminate child processes after the command returns. Such hosts require --foreground and the host's own background command option, see references/hosts.md。

Teaching loop

  1. Before each reply, run CLI eventsto read clicks since the last call. Treat clicks as hints.
  2. Write the next screen to <screens>/<next>-<slug>.html。next from start or CLI status。
  3. Use a new file name for each screen. The browser shows the latest file.
  4. Tell the learner in one sentence what the screen shows, and ask them to answer in the terminal.
  5. When the current step is text only, write a waiting screen.

Write screens with the file tool, not through the terminal's cat or heredoc to output the screen content.

What each step shows

Mentor step Screen Source of truth
Problem context Step bar and lesson problem card docs/zh.md
Core concepts The diagram registered for the lesson, set as the example being explained docs/zh.md in figure fences
Hands-on build Code execution process: code snippet, current line, variables Real run of the lesson code
Practical use Side-by-side display of library call and from-scratch implementation, with identical output Lesson code and its output
Understand by looking at the figure A diagram made for this lesson Diagram skills, lesson body, real run
Prediction or quiz Question and clickable options quiz.json, without the answer

references/screens.md List all style classes and complete examples of each screen type.

Prefer registered diagrams

Many lessons already have interactive diagrams. Check before making a new one.

  1. In lesson docs/zh.md , find code fences with language tag figure .
  2. Put the first line of the fence into the host element:<div class="lesson-figure" data-figure="kv-cache-sizer"></div>。
  3. Keep the JSON configuration from the fence, for example data-figure='iso-machine {"machine":"kv-cache"}'。
  4. Only adjust values using configuration keys already present in the fence.

The screen loads the Chinese lesson diagram runtime and mounts the diagram, with appearance and interaction consistent with the lesson page.

Make diagrams while learning

Make a diagram for the current lesson, completed during teaching so it can be shown in the "Understand by looking at the figure" step.

  1. At the start of the lesson, read docs/zh.mdand run the lesson code.
  2. Explain the system in one sentence: "X goes through Y, and this motion represents Z."
  3. Choose a form from the table below, state the time required, and only make it after the learner agrees.
  4. Write a production progress screen and update it as stages progress.
  5. When the host allows calling a second agent, hand production to it and continue teaching in the terminal yourself.
  6. Without a second agent, make it during the lab or quiz, or offer to show it at the end of the session.
  7. Use CLI shot to check the finished product. Look at each image and fix problems.
  8. Run CLI publish <page.html>to make the page the next screen.
Form How to make Time required When suitable
Blueprint blueprint-figure skill 5 to 10 minutes The concept is a structure made of named components
Mechanism diagram Layer 2 of the motion-figure skill 15 to 25 minutes One control changes the computed result
Isometric machine isometric-explainer skill 40 to 90 minutes The concept is a process with workstations, order, and failures
3D model An installed diagram skill that supports 3D, or three.js 60 to 120 minutes Depth or rotation itself carries the concept, or the learner requests 3D

Choose the smallest format that can explain the concept clearly. When the learner has time and asks for it, provide a larger format.

Before each production, read references/build.md, which specifies the production stages, page contracts, production guidelines and 3D requirements.

Chart skills

Course chart skills include blueprint-figure, motion-figure, isometric-explainer and course-style. If not installed, read from https://raw.githubusercontent.com/fancyboi999/ai-engineering-from-scratch-zh/main/skills/<name>/ .

Check the host skill list before choosing a format. If installed skills support a more suitable isometric illustration, WebGL effect or 3D mode, you may use them; the fact rules and page contracts of this skill must still be followed.

Post-lesson practice

CLI practice <lesson-path> Write the practice page for one lesson as the next screen, containing four parts:

  • Overview: course summary, learning objectives, and term cards that show their meaning when clicked.
  • Practice：quiz.json answer the questions with number keys 1 to 4, press Enter to go to the next question, optional timer.
  • Review: incorrect questions return after 1, 3, 7 and 16 days.
  • Go deeper: course page, course catalog, code run command, one exercise and further reading.

Follow these rules:

  • Provide the practice page only after the tutor's own post-lesson quiz has ended. The page contains answers.
  • The page grades itself, and progress stays only in the browser. Do not record scores, review queues or any evidence from here.
  • Prefer reading the local clone; when there is no clone, read from the Chinese GitHub repository.
  • When there is no quiz.json , generate questions from the course's key glossary.
  • Provide code commands only when a code/main.* matching the course's declared language exists. For courses using other entry points, check the course catalog for how to run.

Fact rules

  • Values, labels and step descriptions come from the course text or actual runs; do not fabricate numbers.
  • Self-made charts with motion use a tested small state model. The model drives both the parts and the displayed values.
  • Before the learner answers, do not put the correct answer, answer index or explanation on the screen. Learners can view the page source. The only exception is the practice page provided after the tutor's quiz has ended.
  • Clicks are only hints and never count as quiz answers, checkpoint evidence or experimental results.
  • Progress, scores and evidence are always determined by the tutor's own rules.
  • Mark every self-made chart: made by the tutor for this lesson, not reviewed by the course author.
  • Clearly label simulated or scaled values on the page.

Events

CLI events outputs {"type":"events","events":[...]}. Each event contains type、screen、at, and the following fields.

type Field Meaning
choice question、choice、text The learner clicked an option
part part、label The learner asked about a part of a self-made chart
step step、label The learner switched to a step of a self-made chart
note text Free notes in a custom screen

CLI events --all outputs all events without changing the read position.

Stopping and retention

  • At the end of the course, run CLI stop, unless the next lesson starts immediately.
  • The server stops automatically after two hours of idle time.
  • Self-made pages can be opened from disk; the feature for asking the tutor questions is available only in the server.
  • Copy the finished work the learner wants to keep, together with the source files, to learning-artifacts/<phase>-<lesson>/。

Commands

Command Purpose
start [--open] [--foreground] [--port N] [--host H] [--url-host H] [--assets live|local] [--repo PATH] [--idle-minutes N] Start the server, or reuse a running instance
status Output running、url、screens、latest、next and the number of unread events
events [--all] Output new events
publish FILE [--name SLUG] Copy the handmade page as the next screen
practice LESSON [--repo PATH] [--name SLUG] Generate the next screen's exercise page based on the course path
shot TARGET [--width N] [--height N] [--theme light|dark] [--wait MS] [--out FILE] [--chrome PATH] Capture the screen or a page using local Chrome, Chromium, or Edge
stop Stop the server

All commands accept --dir PATH to specify another session directory, and output a single line of JSON. Errors are written to stderr as JSON with exit code 1.

By default, the screen loads the chart runtime from aieng-zh.cn.--assets local is loaded from a local clone of site/ . First run in that clone node site/build.js。

Final checks

  • The learner has received the full URL containing the key, or the course page link.
  • Events have been read before every reply.
  • Each screen matches the step currently being explained in the terminal.
  • The screen contains no answers before the learner responds.
  • All numbers in handmade charts come from the course or real runs.
  • Before publishing, reviewed the light and dark theme screenshots of CLI shot .
  • The server has been stopped, or it has been noted that it is still running.