engagement-pass¶

Retrofit existing notebooks with interactive engagement elements — Plotly plots, video embeds, ipywidgets, animations, concept maps, and "build a toy" exercises. Triggers on "add engagement to", "make interactive", "retrofit", "engagement pass on", or when upgrading static notebooks with interactive elements.

Security: CLEAN

Install¶

brunnr install engagement-pass

Tags: Educational Suite

Security Scan¶

CLEAN — 0 findings

This skill passed all 7+1 threat class checks with no findings.

File Info¶

Property	Value
Path	`skills/engagement-pass/SKILL.md`
Size	7.6 KB
SHA-256	`eb0f4737cc9d2ffc16ef26934633ff119dc9950ee8ab1884284e11fee6bcaf3c`
README	`skills/engagement-pass/README.md`

Skill Prompt¶

Engagement Pass¶

A retrofit skill that analyzes existing Jupyter notebooks and adds interactive engagement elements without changing the narrative flow or learning sequence.

When to use: On notebooks that are already written and working but are purely static (matplotlib only, no widgets, no videos, no interactive plots).

When NOT to use: During initial notebook generation — the lesson-generator skill now includes engagement patterns (sections 13-18) and should generate with them from the start.

Trigger Detection¶

Activate on: - "Add engagement to [notebook]" - "Make [notebook] interactive" - "Retrofit [notebook]" - "Engagement pass on [notebook]" - "Add interactive elements to [notebook]" - "This notebook needs more dopamine"

Process¶

Step 1: Analyze¶

Read the target notebook and identify enhancement opportunities:

Scan for: | What to Find | Enhancement Type | Priority | |-------------|-----------------|----------| | Static matplotlib scatter plots with meaningful per-point data | Plotly conversion | High | | 3D matplotlib surface plots | Plotly 3D conversion | High | | Missing concept map after imports | Arc progress map | High | | Concept introductions (interludes, theory sections) | Video embed opportunity | High | | Parameter explorations ("try changing X") | Widget (ipywidgets) | Medium | | Simulations or Monte Carlo sections | Button-triggered widget | Medium | | Time-series / convergence / updating sections | FuncAnimation | Medium | | Static bar charts comparing categories | Plotly bar with hover | Medium | | Exercise sections without a "build" component | "Build a toy" candidate | High | | Every single matplotlib plot | NOT a conversion candidate | N/A |

Output: A concrete enhancement list with cell numbers and descriptions.

Step 2: Prioritize¶

Not everything should be converted. Apply the engagement budget:

High priority (do first): 1. Arc progress concept map (after imports) — every notebook needs one 2. 1-2 key Plotly conversions where hover/interaction genuinely helps 3. 1 strategic video embed at a concept introduction point

Medium priority (do if budget allows): 4. Widget for parameter exploration 5. Animation for a dynamic concept 6. Additional Plotly conversions

Low priority (skip unless specifically requested): 7. Converting every matplotlib plot to Plotly 8. Adding widgets to sections where the static version is clear enough 9. Multiple animations (expensive to render)

Budget limits per notebook: - Max 1 concept map - Max 3 video embeds - Max 4 Plotly conversions - Max 3 widgets - Max 2 animations - At least 1 "build a toy" exercise

Step 3: Apply¶

Insert enhancements using templates from lesson-generator/interactive-templates.md.

For each enhancement:

Concept Map¶

Add engagement imports to the imports cell (Cell 2)
Insert arc_progress_map() call as a new cell after imports
Use ARC_0_MODULES list and set current_module appropriately

Video Embed¶

Identify the target section from lesson-generator/video-index.md
Create a new markdown cell with contextual intro (1-2 sentences)
Add code cell with embed_video(video_id, title, context)
Place AFTER the reader has worked through the concept, not before

Plotly Conversion¶

Read the existing matplotlib cell
Determine what hover data would be useful
Replace with equivalent Plotly code using templates
Keep the same color palette and visual style
Remove the old matplotlib cell (don't leave both)

Identify the parameter(s) the reader should explore
Choose widget type: @interact for simple sweeps, button for stochastic processes
Add the widget cell after the static version
Include a "What to notice" comment guiding exploration

Animation¶

Show the static/final result first (existing cell)
Add animation cell after with FuncAnimation → HTML(anim.to_jshtml())
Include frame counter and running metrics in the animation

"Build a Toy" Exercise¶

Place in the Exercises section
Provide scenario, components, task, success criteria, extensions
Include starter code and a working solution in a separate cell
The toy must be interactive (widgets + plotly/matplotlib)

Step 4: Validate¶

After applying enhancements:

[ ] All cells run sequentially without error
[ ] Story flow is unchanged — enhancements clarify, don't distract
[ ] No widget overload (check budget limits)
[ ] Imports cell includes all needed engagement imports
[ ] Videos reference correct IDs from video-index.md
[ ] Plotly plots use consistent color palette and plotly_white template
[ ] Concept map correctly identifies current module

Quality Checklist¶

Run this checklist after every engagement pass:

[ ] Concept map present after imports
[ ] 1-3 strategic video embeds at concept introductions (not more)
[ ] Key plots converted to Plotly (hover data is useful, not just pretty)
[ ] At least 1 widget for parameter exploration
[ ] 0-1 animations for dynamic concepts
[ ] At least 1 "build a toy" exercise in the exercises section
[ ] Story flow preserved — if you removed the enhancements, the notebook still makes sense
[ ] All cells run sequentially without error
[ ] No engagement bloat — every interactive element has a reason to be interactive

Reference Files¶

File	Location	Purpose
`engagement-patterns.md`	`.claude/skills/lesson-generator/`	When/how to use each pattern type
`interactive-templates.md`	`.claude/skills/lesson-generator/`	Copy-paste code templates
`video-index.md`	`.claude/skills/lesson-generator/`	YouTube video IDs per module/section
`SKILL.md` (lesson-generator)	`.claude/skills/lesson-generator/`	Sections 13-18 define generation-time patterns

What This Skill Does NOT Do¶

Rewrite narrative: The story, voice, and flow are sacred. Enhancements slot in alongside, never replace.
Restructure exercises: Exercise order and structure remain unchanged. "Build a toy" is added, not substituted.
Add theory content: No new concepts, formulas, or explanations. Only interactive wrappers around existing content.
Fix bugs: If the notebook has code errors, fix those first before running an engagement pass.
Change the belt level: A Core notebook stays Core. A Depth notebook stays Depth. Engagement elements don't change the target audience.

Example: Before/After¶

Before (static matplotlib scatter)¶

fig, ax = plt.subplots(figsize=(10, 5))
ax.scatter(salience_scores, intuitive, c='#2196F3')
ax.set_xlabel('Salience Score')
ax.set_ylabel('Intuitive Rating')
ax.set_title('Scorer vs. Intuition')
plt.show()

After (Plotly with hover context)¶

plotly_scatter_with_context(
    x=salience_scores, y=intuitive_ratings,
    labels=[f"Entry {i}" for i in range(len(ENTRIES))],
    descriptions=[e.task[:60] for e in ENTRIES],
    title="SalienceScorer vs. Intuitive Ratings",
    xaxis_title="Salience Score", yaxis_title="Intuitive Rating"
)

The Plotly version lets the reader hover over each point and see which entry it is, what the task was, and both score values. The matplotlib version just shows dots.

README¶

Engagement Pass¶

A retrofit skill that adds interactive engagement elements to existing Jupyter notebooks.

What It Does¶

Analyzes a static notebook and adds: - Concept map — interactive arc progress map after imports - Plotly conversions — key matplotlib plots upgraded with hover context - Video embeds — curated YouTube videos at concept introduction points - Widgets — parameter exploration via sliders and buttons - Animations — FuncAnimation for time-evolution concepts - "Build a toy" exercises — interactive construction exercises

When to Use¶

Use this skill on notebooks that are already written and working but are purely static (matplotlib only, no widgets, no videos). The lesson-generator skill now generates with engagement built in — use engagement-pass only for upgrading older notebooks.

Invocation¶

Say any of: - "Add engagement to Module 0.1" - "Make the probability notebook interactive" - "Retrofit Module 0.2" - "Engagement pass on 0.1-taste-demo-core.ipynb"

Process¶

Analyze — Scan for enhancement opportunities (static plots, missing concept map, parameter explorations, exercise gaps)
Prioritize — Apply engagement budget (max 1 concept map, 3 videos, 4 Plotly conversions, 3 widgets, 2 animations, 1+ build-a-toy)
Apply — Insert enhancements using templates from lesson-generator/interactive-templates.md
Validate — Verify all cells run, story flow preserved, no widget overload

Quality Checklist¶

After every engagement pass, verify:

[ ] Concept map present after imports
[ ] 1-3 strategic video embeds at concept introductions
[ ] Key plots converted to Plotly (hover data is useful)
[ ] At least 1 widget for parameter exploration
[ ] 0-1 animations for dynamic concepts
[ ] At least 1 "build a toy" exercise
[ ] Story flow preserved
[ ] All cells run sequentially without error

What It Does NOT Do¶

Rewrite narrative — Story, voice, and flow are sacred
Restructure exercises — Exercise order stays the same; "build a toy" is added alongside
Add theory content — Only interactive wrappers around existing content
Fix bugs — Fix code errors before running an engagement pass
Change belt level — Core stays Core, Depth stays Depth

Example: Before/After¶

Before (static matplotlib):

ax.scatter(salience_scores, intuitive, c='#2196F3')

After (Plotly with hover):

plotly_scatter_with_context(
    x=salience_scores, y=intuitive_ratings,
    labels=[f"Entry {i}" for i in range(len(ENTRIES))],
    descriptions=[e.task[:60] for e in ENTRIES],
    title="SalienceScorer vs. Intuitive Ratings"
)

Hover over any point to see which entry it is and what the task was.

Reference Files¶

All engagement patterns, templates, and video mappings live in lesson-generator/: - engagement-patterns.md — When/how to use each pattern - interactive-templates.md — Copy-paste code blocks - video-index.md — YouTube video IDs per module

License¶

MIT

engagement-pass¶

Install¶

Security Scan¶

File Info¶

Skill Prompt¶

Engagement Pass¶

Trigger Detection¶

Process¶

Step 1: Analyze¶

Step 2: Prioritize¶

Step 3: Apply¶

Concept Map¶

Video Embed¶

Plotly Conversion¶

Widget Addition¶

Animation¶

"Build a Toy" Exercise¶

Step 4: Validate¶

Quality Checklist¶

Reference Files¶

What This Skill Does NOT Do¶

Example: Before/After¶

Before (static matplotlib scatter)¶

After (Plotly with hover context)¶

README¶

Engagement Pass¶

What It Does¶

When to Use¶

Invocation¶

Process¶

Quality Checklist¶

What It Does NOT Do¶

Example: Before/After¶

Reference Files¶

License¶