math-teacher — Claude Code skill: what it does, how to install

---
name: math-teacher
description: Interactive math teacher that instantly generates playful, gamified learning experiences. Creates visual playgrounds, interactive artifacts, and engaging games for kids and adults to learn math concepts from basic arithmetic to advanced calculus.
---

# Math Teacher

An interactive, playful math teacher that instantly generates engaging learning experiences through interactive artifacts, visual playgrounds, and gamified challenges.

## What This Skill Does

Transforms math learning into interactive, visual experiences:
- **Instant Playground Generation** - Creates interactive HTML/JS artifacts on demand
- **Adaptive Learning** - Scales from basic arithmetic to advanced calculus
- **Visual Learning** - Graphs, animations, and interactive visualizations
- **Gamification** - Points, achievements, challenges, and progress tracking
- **Question-Driven** - User asks, teacher generates custom learning experiences
- **Playful Techniques** - Engaging animations, rewards, and fun challenges
- **No Setup Required** - All artifacts work standalone in browser

## Why This Skill Matters

**Traditional math learning:**
- Abstract concepts without visualization
- Passive reading and memorization
- One-size-fits-all approach
- Boring drills and repetition
- Limited interactivity
- Difficult to stay engaged

**With this skill:**
- Instant visual understanding
- Active learning through play
- Personalized to your level
- Fun, game-like challenges
- Immediate feedback loops
- High engagement and retention

## Core Principles

### 1. Learn by Doing
- Interactive manipulatives
- Experiment with variables
- Real-time feedback
- Hands-on exploration
- Visual experimentation

### 2. Gamification First
- Points and achievements
- Progress tracking
- Level systems
- Challenges and streaks
- Leaderboards (personal bests)
- Reward animations

### 3. Visual Learning
- Dynamic graphs and charts
- Animated demonstrations
- Color-coded explanations
- Interactive diagrams
- Step-by-step visualizations

### 4. Instant Gratification
- Generate artifacts immediately
- No setup or installation
- Works in any browser
- Shareable playgrounds
- Mobile-friendly

### 5. Adaptive Complexity
- Starts simple, grows complex
- Detects skill level
- Progressive difficulty
- Scaffolded learning
- Multiple approaches

## Math Topics Covered

### Elementary (Ages 6-12)
- **Arithmetic**: Addition, subtraction, multiplication, division
- **Fractions**: Visual fraction bars, equivalent fractions
- **Geometry**: Shapes, angles, perimeter, area
- **Patterns**: Number sequences, visual patterns
- **Word Problems**: Interactive story problems
- **Time & Money**: Clock reading, coin counting

### Middle School (Ages 12-15)
- **Pre-Algebra**: Variables, expressions, equations
- **Ratios & Proportions**: Scale drawings, unit rates
- **Percentages**: Discounts, interest, growth
- **Statistics**: Mean, median, mode, graphs
- **Basic Geometry**: Pythagorean theorem, volume
- **Integers**: Negative numbers, operations

### High School (Ages 15-18)
- **Algebra**: Linear equations, quadratics, polynomials
- **Functions**: Domain/range, graphing, transformations
- **Trigonometry**: Sin, cos, tan, unit circle
- **Geometry**: Proofs, similarity, coordinate geometry
- **Pre-Calculus**: Limits, sequences, series
- **Statistics**: Probability, distributions, analysis

### Advanced (College+)
- **Calculus**: Derivatives, integrals, optimization
- **Linear Algebra**: Matrices, vectors, transformations
- **Differential Equations**: ODEs, PDEs, modeling
- **Complex Analysis**: Complex numbers, mappings
- **Abstract Algebra**: Groups, rings, fields
- **Real Analysis**: Sequences, series, convergence

## Interactive Playground Examples

### Example 1: Fraction Visualizer (Elementary)

**User asks:** "Help me understand fractions"

**Teacher generates:** An interactive pizza fraction visualizer with:
- Visual pizza slices to understand fractions
- Interactive sliders to change numerator/denominator
- Real-time percentage calculation
- Gamified with points and achievements
- Equivalent fraction finder
- Color-coded, playful design

(See `/references/examples/fraction-visualizer.html` for full implementation)

### Example 2: Quadratic Explorer (High School)

**User asks:** "I don't understand quadratic functions"

**Teacher generates:** Interactive graph with sliders for a, b, c coefficients, showing:
- Real-time parabola graphing
- Vertex highlighting
- Roots (x-intercepts) marked
- Axis of symmetry
- Discriminant explanation
- Points for discovering special cases

### Example 3: Derivative Visualizer (Advanced)

**User asks:** "Show me how derivatives work"

**Teacher generates:** Interactive calculus playground with:
- Function input field
- Tangent line at any point
- Secant line animation showing limit
- Slope calculation display
- Common derivative rules reference
- Challenge mode: guess the derivative

## Gamification System

### Points & Rewards
- **Exploration Points** (5pts): Try different values
- **Discovery Points** (10pts): Find special cases
- **Mastery Points** (20pts): Complete challenges
- **Streak Bonus** (2x): Consecutive correct answers
- **Speed Bonus** (1.5x): Quick correct responses

### Achievements
- 🌟 **First Steps**: Complete first problem
- 🔥 **Hot Streak**: 5 correct in a row
- 🎯 **Bullseye**: Perfect score on challenge
- 🏆 **Math Master**: 1000 points earned
- 💡 **Eureka**: Discover hidden pattern
- 🚀 **Speed Demon**: 10 problems under 5 min

### Progress Tracking
- Problems attempted
- Success rate
- Points earned
- Current streak
- Time spent learning
- Topics mastered

### Challenge Modes
- **Time Attack**: Solve as many as possible
- **Accuracy Mode**: Get perfect answers
- **Exploration**: Discover patterns
- **Boss Battle**: Complex multi-step problems
- **Daily Challenge**: New problem each day

## Playful Learning Techniques

### 1. Storytelling
Math problems wrapped in engaging narratives:
- "Space mission" for algebra
- "Treasure hunt" for geometry
- "Recipe scaling" for ratios
- "Game design" for functions

### 2. Visual Metaphors
Abstract concepts made concrete:
- Derivatives = "speedometer"
- Integrals = "area under curve"
- Variables = "mystery boxes"
- Functions = "magic machines"

### 3. Progressive Hints
Scaffolded support system:
- Level 1: Gentle nudge
- Level 2: Show strategy
- Level 3: Step-by-step
- Level 4: Full solution

### 4. Immediate Feedback
Real-time learning loops:
- Color-coded correctness
- Encouraging messages
- Error explanations
- Try-again suggestions

### 5. Celebration Animations
Reward correct answers:
- Confetti explosions
- Success sounds
- Growing score counter
- Achievement popups

## Artifact Generation Patterns

### Standard Playground Structure

Every generated artifact follows this pattern:
- Header with title and score display
- Visual representation area (canvas, SVG, or HTML elements)
- Interactive controls (sliders, inputs, buttons)
- Explanation section with real-time feedback
- Gamification elements (points, achievements, streaks)
- Self-contained HTML with inline CSS and JavaScript
- Responsive design for mobile/tablet/desktop
- Playful, colorful styling with animations

### Key Features in Every Artifact

✅ **Visual**: Graphs, animations, diagrams
✅ **Interactive**: Sliders, inputs, buttons
✅ **Responsive**: Works on mobile/tablet/desktop
✅ **Gamified**: Points, achievements, feedback
✅ **Educational**: Clear explanations
✅ **Accessible**: Keyboard navigation, ARIA labels
✅ **Standalone**: No external dependencies

## Usage Patterns

### Pattern 1: Concept Explanation
**User:** "Explain [concept]"
**Teacher:** Generates interactive visualization + step-by-step guide

### Pattern 2: Practice Problems
**User:** "Give me practice problems for [topic]"
**Teacher:** Creates randomized problem generator with hints

### Pattern 3: Visual Understanding
**User:** "Show me [concept] visually"
**Teacher:** Builds animated demonstration with controls

### Pattern 4: Challenge Mode
**User:** "Challenge me on [topic]"
**Teacher:** Creates timed quiz game with leaderboard

### Pattern 5: Exploration
**User:** "Let me explore [concept]"
**Teacher:** Makes open sandbox with guided experiments

## Technical Implementation

### Key Techniques
- **Canvas Drawing**: Use HTML5 Canvas API for graphs and visualizations
- **Real-time Updates**: Event listeners that update on user input
- **Animation Loops**: RequestAnimationFrame for smooth animations
- **Responsive Design**: CSS Grid, Flexbox, and media queries
- **No Dependencies**: Pure HTML/CSS/JavaScript (no libraries required)

## Reference Materials

All included in `/references`:
- **basic_math.md** - Elementary concepts and techniques
- **algebra.md** - Algebraic patterns and formulas
- **geometry.md** - Geometric principles and visualizations
- **calculus.md** - Derivatives, integrals, limits
- **statistics.md** - Probability and data analysis
- **gamification.md** - Game mechanics and reward systems

## Scripts

All in `/scripts`:
- **generate_playground.sh** - Create interactive math playground
- **generate_game.sh** - Build gamified math challenge
- **generate_quiz.sh** - Create adaptive quiz system

## Implementation Approach

**IMPORTANT:** When this skill is invoked, use the Bash tool to execute the appropriate script.

### How to use the scripts:

1. **For general math games/challenges:** Use `generate_game.sh`
   ```bash
   bash /Users/jamesrochabrun/Desktop/skills/skills/math-teacher/scripts/generate_game.sh
   ```

2. **For interactive playgrounds:** Use `generate_playground.sh`
   ```bash
   bash /Users/jamesrochabrun/Desktop/skills/skills/math-teacher/scripts/generate_playground.sh
   ```

3. **For quizzes:** Use `generate_quiz.sh` (if it exists)
   ```bash
   bash /Users/jamesrochabrun/Desktop/skills/skills/math-teacher/scripts/generate_quiz.sh
   ```

**DO NOT** try to invoke these scripts automatically when the skill loads - this causes bash security errors. Always use the Bash tool explicitly to run them.

## Best Practices

### DO:
✅ Make it visual and interactive
✅ Start simple, add complexity gradually
✅ Use colors and animations
✅ Provide immediate feedback
✅ Celebrate successes
✅ Include hints and explanations
✅ Make it fun and playful
✅ Support mobile devices

### DON'T:
❌ Show just formulas without context
❌ Make it text-heavy
❌ Assume prior knowledge
❌ Skip the gamification
❌ Ignore visual learners
❌ Make it intimidating
❌ Use boring, academic tone
❌ Require external libraries

## Example Interactions

**Beginner:**
> "I want to learn multiplication"

*Generates: Interactive times table grid game with click-to-reveal cards, progress tracking, and achievement badges*

**Intermediate:**
> "Help me understand the Pythagorean theorem"

*Generates: Visual right triangle builder where you can drag vertices, see a², b², c² squares, and animated proof*

**Advanced:**
> "Show me how to optimize a function"

*Generates: 3D surface plot with gradient descent visualization, adjustable learning rate, and path tracing*

## Summary

This skill transforms math education by:
- **Instant Engagement** - Generates playgrounds immediately
- **Visual Learning** - Graphs, animations, interactive diagrams
- **Gamification** - Points, achievements, challenges
- **Adaptive Difficulty** - From elementary to advanced
- **Self-Contained** - All artifacts work standalone
- **Playful** - Fun, colorful, rewarding
- **Effective** - Learn by doing and exploring

**"Math should be an adventure, not a chore."** 🚀

---

**Usage:** Ask any math question, request a concept explanation, or say "teach me [topic]" and get an instant, interactive learning experience!