gpsaggese/helpers / .claude/skills/notebook.create_outline
notebook.create_outline
VerifiedOutline a Jupyter notebook that teaches concepts through example and discovery
Goal
- 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 used -
Section 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 Goal -
Implementation 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 population -
Visualization 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 reproducibility -
Commentary
**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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |