course-lesson-editor

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

1. Identify the lesson's one learner outcome and one main concept cluster.
2. Start with the problem or task before explaining the concept.
3. Anchor the lesson in something observable: a file path, command, prompt, output, or visible artifact.
4. Keep useful rough-draft connective lines when they give the lesson momentum, such as "In fact..." or "The best part..."
5. Keep the lesson sequence familiar: context, concrete demo, key idea, learner action.
6. End every lesson with a short preview of the matching exercise.
7. 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.