Skip to content

gpsaggese/helpers / .claude/skills/notebook.create_outline

notebook.create_outline

Verified

Outline a Jupyter notebook that teaches concepts through example and discovery

FileKindSize
SKILL.mdskill md6.4 KB
---
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`
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall