| name | course-lesson-editor |
| description | Turn rough course lesson sketches into clear developer education lessons that lead into exercises. Use when drafting, revising, or structuring lesson content, especially files like course/*/01-lesson.md and course/*/02-exercise.md. |
Course lesson editor
Use this skill to turn rough lesson notes into a concrete lesson learners can follow, then transition into a focused exercise. Preserve the author's voice, pacing, jokes, and point of view unless they block clarity.
Workflow
- Identify the lesson's one learner outcome and one main concept cluster.
- Start with the problem or task before explaining the concept.
- Anchor the lesson in something observable: a file path, command, prompt, output, or visible artifact.
- Keep useful rough-draft connective lines when they give the lesson momentum, such as "In fact..." or "The best part..."
- Keep the lesson sequence familiar: context, concrete demo, key idea, learner action.
- End every lesson with a short preview of the matching exercise.
- Edit for structure without making every lesson sound like the same template.
Lesson contract
Each 01-lesson.md should include these ingredients, but the section names and prose can vary:
- Frontmatter with
title, time, and outcome.
- One
# title after the frontmatter, matching the frontmatter title.
- A familiar opening that connects to what the learner already did, already knows, or is about to need.
- A concrete problem, demo, or artifact before abstract explanation.
- A few "what to notice" bullets after dense command output, transcripts, or examples.
- A small set of key ideas that support the demo.
- Commands, paths, prompts, outputs, or examples when they make the lesson more inspectable.
- A final exercise preview that tells the learner what they will build, inspect, revise, or decide next.
Do not force all lessons into identical headings. Prefer a human-written lesson that satisfies the contract over a perfectly uniform outline.
Heading standards
- Use exactly one
# heading in each lesson: the lesson title.
- Use
## headings for major beats only, such as Demo, Key idea, What to notice, Try it, or Exercise preview.
- Use
### headings only when a ## section has multiple real subparts. Avoid ### in short lessons.
- Use sentence case for headings and titles.
- Do not add headings just to make the lesson look structured. If the prose flows naturally, keep fewer headings.
Exercise preview
End each lesson with 1-3 sentences that point into the matching exercise. Keep it specific and conversational.
Good patterns:
- "Now we'll implement this by creating a small skill by hand."
- "Now, you'll build the same structure in
02-exercise.md with your own example."
- "Next, you'll inspect a few variants and decide which ones you would trust."
- "In the exercise, you'll turn this demo into a repeatable workflow."
Avoid generic endings like "Now it's your turn" unless the sentence also names the concrete task.
Developer education checks
- Teach one concept cluster at a time.
- Prefer examples, commands, paths, and visible outputs over broad theory.
- Explain only what the learner needs for this lesson; defer nice-to-have context.
- Use the course sequence as a constraint. Do not introduce later-lesson concepts early.
- Keep terminology consistent between lesson, exercise, solution, and referenced skills.
- Make success observable: the learner should know what changed or what output to expect.
- Preserve human texture. Keep useful asides, preferences, and first-person context when they make the lesson easier to follow.
- Preserve concise author phrasing when it adds energy or point of view. Do not replace every casual line with neutral instructional prose.
- Keep optional advanced material after the core lesson, and make clear that the habit matters more than the automation.
- Remove filler only when it weakens the lesson's direction, repeats a point, or obscures the next action.
Sentence clarity rules
- Start with short, familiar information; move new or complex information later.
- Make the main character the subject and the important action a verb.
- Cut throat-clearing and unnecessary nominalizations when meaning stays intact.
- Put the sentence's most important idea at the end.
- Do not use em dashes; prefer colons, semicolons, commas, or space-padded hyphens.
- Use sentence case for titles and headings.
Exercise handoff
When editing a matching 02-exercise.md, make it narrower than the lesson:
- State the objective in one sentence.
- List concrete requirements.
- Include one starter prompt, file path, or example input when useful.
- Avoid revealing the solution unless the user asks for it or is blocked.
- Keep the exercise small enough that the learner can complete it immediately after the lesson.
