gpsaggese/helpers / .claude/skills/notebook.create_outline
notebook.create_outline
VerifiedOutline a Jupyter notebook that teaches concepts through example and discovery
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.4 KB |
SKILL.md
View on GitHub---
description: Outline a Jupyter notebook that teaches concepts through example and discovery
model: sonnet
---
# 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 Setup` in
`.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:
```markdown
- 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
- 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:
```markdown
## 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 `- Inputs` and `- 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]`
- Place each widget description next to the widget (its `description`
parameter 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
- List key functions or classes
- E.g., `ipywidgets.FloatSlider`, `matplotlib.animation`
# Example Outline
- Emulate this unit outline:
- Description (pre-visualization) cell
```markdown
## 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
```markdown
**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
```markdown
**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.md` for notebook formatting, including
`## Utilities vs. Notebook Responsibilities` for 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: 119k | 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: 119k | 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: 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: 118k | Updated | Claude CodeCodex | Verified | Install |