notebook-create-outline
Outline a Jupyter notebook that teaches concepts through example and discovery
SKILL.md.claude/skills/notebook.create_outline/SKILL.md
GitHubGoal
- Create a comprehensive outline for an interactive Jupyter notebook that teaches a concept (passed from the user) through visualization and hands-on exploration
- The outline is a markdown file that describes what each notebook cell contains, without writing any code, as a blueprint for implementation
Key Principles
- Follow the section
# Design Principles and Setupin.claude/skills/notebook.rules.md - The output is
notebook_outline.<TAG>.md, describing the notebook units - Say in the output file how it was generated, with this line right after the title:
- Generated by `.claude/skills/notebook.create_outline/SKILL.md` - Save the file in the current dir
- Do not write any code
Outline Unit Structure
- Each unit in the outline corresponds to a triplet of cells in the final notebook:
- Markdown cell: Section header, goal, and description of the panels and controls (before viz)
- Code cell: Visualization, widgets, and interactive controls
- Markdown cell: Guided usage, actions plus observations, then the implementation (after viz)
Numbering and Naming
- Number units incrementally:
- E.g.,
Cell 1,Cell 2, etc
- E.g.,
- Use descriptive titles that signal the learning objective
- Not just "Plot" or "Widget"
- Keep titles concise (5-7 words)
Outline Unit Description Template
Use this structure for each unit:
## Cell i: <Concise Learning Objective> **Goal** - <Learning objective 1> - <Learning objective 2> **Plots and their descriptions** - `<Plot 1 name>`: <Description of what it shows> - `<Plot 2 name>`: <Description of what it shows> - `Comments`: Current parameter values and state observations **Widgets** (if applicable) - `<widget name>`: <description, range, effect on display> - Each widget description is close to the widget itself **Guided usage** (post-visualization) - <Action on a widget, plus the observation it produces> - <Action on a widget, plus the observation it produces> **Implementation** Libraries and functions usedSection labels take no trailing colon, and item names are plain backtick, not bold plus backtick
In the final notebook, Plots and their descriptions plus Widgets become the
**Description**markdown cell (split into- Inputsand- Panels), placed right after GoalImplementation becomes its own
**Implementation**markdown cell, expanded into one bullet per algorithmic step, placed after Guided usage: see.claude/skills/notebook.rules.md## Visualization Cell Triplet Details
Goal (Required)
- 1-2 bullets stating the learning objectives
- If not the first unit, say how it builds on prior concepts
- Answers the question "Why is this outline unit important?"
Plots and Their Descriptions (Required)
Describe each plot using the pattern
`<Plot name>`: <DESCRIPTION>Place each description with its plot title, not in a separate section
Be specific about what the visualization shows, not implementation details
Include axes labels, color scheme, and what each panel displays
Example:
`Population bin`: Shows full population as colored marbles
Widgets (If Applicable)
- List each control with its name and range
- E.g.,
Slider for mu in [0.0, 1.0]
- E.g.,
- Place each widget description next to the widget (its
descriptionparameter or an adjacent label) - Explain the effect of changing each parameter on the display
- Keep widgets to pedagogically important parameters
- Avoid redundant controls and parameters students won't care about
Guided Usage (Required, Post-Visualization)
- List 2-3 bullets, each an action on a control plus the observation it produces,
e.g.,
Drag mu from 0.2 to 0.8/Observe the sample bin's color mix shift to match - These appear in a markdown cell after the visualization cell
- Focus on experiments with the widgets and what students learn from them, not general facts about the topic
- Do NOT repeat the Goal: go deeper
Comments Panel (Required)
- Contains only variable state and observations for the current state
- No general commentary like "key insight" or "key idea"
- Include current parameter values and sample statistics
- E.g., current mu value, number of samples, sample mean/std
Implementation (Required)
- Name specific libraries
- E.g.,
matplotlib,plotly,ipywidgets, etc
- E.g.,
- List key functions or classes
- E.g.,
ipywidgets.FloatSlider,matplotlib.animation
- E.g.,
Example Outline
Emulate this unit outline:
Description (pre-visualization) cell
## Cell 1: Visualizing Population Distribution **Goal** - Give students a concrete visual representation of the unknown population distribution they're trying to infer from samples - Understand that we can only observe samples, not the full populationVisualization cell
**Plots and their descriptions** - `Population bin`: Animated bin visualization with colored marbles (red vs blue) showing the true population - `Sample bin`: Shows a random sample drawn from the population - `Comments`: Current parameter values (mu, sample count) **Widgets** - `mu`: slider for true proportion of red marbles (0.0-1.0) - `seed`: random seed for reproducibilityCommentary
**Guided usage** - Drag `mu` from 0.2 to 0.8, leaving `sample_size` fixed - Observe the sample bin's color mix shift to track the hidden population, even though the population itself stays unseen - Repeat with a different `seed` - Observe the sample bin change while the population bin does not: only the sample is one random draw **Implementation** Matplotlib animation for marbles, ipywidgets FloatSlider for control, matplotlib patches for marble visualization
Lint
After generating the file
notebook_outline.<TAG>.md> lint_text.py -i `notebook_outline.<TAG>.md`
Conventions
- Follow
.claude/skills/notebook.rules.mdfor notebook formatting, including## Utilities vs. Notebook Responsibilitiesfor utility files and notebooks - For markdown text, follow
.claude/skills/markdown.rules.md: Markdown formatting rules.claude/skills/text.rules.md: Bullet point conventions
Verification
- The output file says that it was generated by
.claude/skills/notebook.create_outline/SKILL.md