Decomposes a PXL Clock clockface into progressive learning steps. Creates a C# script, an explainer script, and description files per step. Does NOT render GIFs.
Decomposes an existing PXL Clock clockface into a progressive sequence of learning steps. Produces per step: a compilable .cs file, a display-only -explainer.cs, and a .short.md for the video overlay.
This skill does NOT render GIFs. That is a separate step.
All output text (descriptions, code comments) must be in English.
The PXL Clock is a 24x24 RGB-LED pixel display. Clockfaces are C# scripts that render animations on this 24x24 canvas. Each script defines a scene lambda that runs every frame (~40 fps):
#:package Pxl@*
using Pxl.Ui.CSharp;
var scene = (DrawingContext ctx) =>
{
ctx.DrawBackground(Colors.Black);
ctx.DrawTextMono4x5($"{ctx.Now:HH:mm}", 2, 10, color: Colors.White);
};
Key facts:
#:package Pxl@* imports the Pxl NuGet package (required in every script)var scene = (DrawingContext ctx) => { ... }; is the entry point — called every framectx.Now gives the current time, ctx.Elapsed the time since startThe full API reference is in llms.txt at the pxl-clock repo root.
CLOCKFACE_NAME = $ARGUMENTS
SOURCE_PATH = <provided via prompt>
OUTPUT_DIR = <provided via prompt>
REPO = /Users/ronald/repos/github.pxl/pxl-tutorial-maker
PXL_CLOCK_REPO = /Users/ronald/repos/github.pxl/pxl-clock
Read the source file at SOURCE_PATH. Also read $PXL_CLOCK_REPO/llms.txt for the full API reference.
Identify the concepts used in the clockface and sort them by dependency — which concept requires which other concept to make sense visually?
Common concepts (not exhaustive):
The dependency order directly determines the step order. A concept that depends on another must come after it. Example: "rainbow colors along the body" depends on "the body exists" — so the body shape must come first, colors second.
Design a progression from simplest building block to complete clockface. If the prompt specifies a minimum step count, create at least that many steps (more is fine if the clockface warrants it). If no minimum is given (or it is -1), decide the right number yourself based on the complexity of the clockface — typically 5–12 steps.
Each step must:
Step planning guidelines:
The one-change rule for linear steps:
When a step builds on the previous one (pattern 1 below), it must change exactly one essential thing. Not two, not three — one. What counts as "one essential thing" requires judgment: adding a DrawLine call is one thing; adding DrawLine + changing the background color + introducing a new variable is three things. Before writing a linear step, ask yourself: "Can I explain what changed in a single sentence without 'and'?" If not, split it into multiple steps.
This rule does NOT apply to combination steps (pattern 2 below) — when you merge previously isolated concepts, naturally many things change at once. That's fine because each concept was already understood individually.
Two valid step patterns:
Pattern 2 is preferred when it makes learning easier. Don't keep piling changes onto an increasingly complex scene if a concept deserves its own spotlight. Stepping back to a clean slate for one step, then combining, is a powerful teaching tool — it shows the concept in isolation, then proves it works in context.
Both patterns can be mixed freely. The key is: every step must either build on the previous one (changing one thing) OR introduce a concept in isolation that will be visibly combined later. The viewer must always understand how this step fits into the bigger picture.
Avoid:
Write all files into OUTPUT_DIR/.
For each step, create step-NN.cs:
// ---
// app: <ClockfaceName>Step<NN>
// displayName: <Clockface Name> - Step <N>
// author: Tutorial
// ---
// Step N: <Short title>
// <One-line description of what this step introduces>
#:package Pxl@*
using Pxl.Ui.CSharp;
// State variables (if any) go here, before the scene lambda
var scene = (DrawingContext ctx) =>
{
// rendering code
};
Conventions:
// --- ... // ---). Without it, Pxl.Render will refuse to compile. The app field must be a valid C# identifier (no spaces/hyphens).#:package Pxl@* (NOT #:project)var scene lambda is the only entry pointstep-01.cs, step-02.cs, ..., step-12.csFor each step, also create step-NN-explainer.cs. This is a display-only version of the code shown in the video overlay. It highlights only the essential/new parts introduced in this step. Everything else (boilerplate, unchanged code from previous steps) is replaced with // ... comments.
The explainer file is not compilable — it exists purely for visual presentation in the reel.
Rules:
// --- ... // ---)#:package and using directivesvar scene = (DrawingContext ctx) => { wrapper and closing }; — show only the body// ... line.cs file// ... (with a space) as the ellipsis marker — not //... or ...(, ,, or an operator, indent the continuation by 4 spaces). Shorten variable names in the explainer if needed — it's display-only, not compilable.Example 1 — everything is new (step 3 adds HSV color cycling):
Explainer step-03-explainer.cs:
var hue = (float)(ctx.Now.TimeOfDay.TotalSeconds * 30 % 360);
var color = Color.FromHsv(hue, 1f, 1f);
ctx.DrawLine(0, 12, 23, 12, color);
Example 2 — change in the middle of existing code (step 5 adds bounce logic inside an existing movement block):
Explainer step-05-explainer.cs:
// ...
if (x < 0 || x >= 24) dx = -dx;
if (y < 0 || y >= 24) dy = -dy;
x += dx;
y += dy;
// ...
Use // ... at top and/or bottom to show that surrounding code exists but is unchanged.
For each step, create a description file alongside the .cs file.
step-NN.short.md — 3 sentences / short paragraphs (blank line between each). This text appears as a typewriter overlay in the reel video. It must cover two things:
Separate each sentence into its own paragraph for readability in the video overlay. Always reference the previous step to make the progression clear (except step 1, which has no predecessor).
Writing style: Direct, conversational, practical. Use short punchy sentences. Name the concrete thing — "HSV cycling", "a Queue<Point>", "sin-based oscillation" — not vague abstractions. The tone is a developer explaining to another developer what's cool about this step.
Inline code formatting: Wrap source code identifiers, API calls, mathematical expressions, and color values in Markdown backticks (`). This includes: method names (DrawLine), types (Color, List<Point>), variables (vX, segCount), numeric constants (0.5f), math formulas (sqrt(4 - vX²)), and color references (Color.FromRgbByte(255, 0, 0)). Do NOT backtick-wrap plain English words or general concepts — only things that are literally code, math, or color values.
DON'T:
This step adds beautiful color effects to create a stunning visual experience on the display.
We enhance the animation with smooth transitions and elegant movement patterns.
(Vague, marketing-speak, no technical substance, no connection to previous step.)
DO — step 1 (no predecessor):
A horizontal red line cuts across the center of a black canvas.
Just one call —
DrawLine— but it's the backbone the worm will grow from.
DO — step 4 (building on step 3):
The solid red worm from step 3 explodes into a flowing rainbow — each segment a different color.
HSV color cycling via
Color.FromHsvassigns each body part a unique hue based on its index.The palette cycles through 30 hues, rippling along the body as it moves.
After writing all files, confirm:
step-NN.cs, step-NN-explainer.cs, step-NN.short.md files exist in OUTPUT_DIR/Report: number of steps created, one-line summary of each step's title.
OUTPUT_DIR/
├── step-01.cs
├── step-01-explainer.cs
├── step-01.short.md
├── step-02.cs
├── step-02-explainer.cs
├── step-02.short.md
├── ...
├── step-NN.cs ← final step = complete clockface
├── step-NN-explainer.cs
└── step-NN.short.md
$PXL_CLOCK_REPO/llms.txt for the complete Pxl.Ui.CSharp API.