Episode

Educational Video Episode Generator (/episode)

Autonomous skill that generates complete educational video episodes with Minecraft-style graphics. Claude acts as Creative Director, writing the script and orchestrating AI generation APIs to produce the final video.

Architecture

/episode "How photosynthesis works"
    │
    ├── Phase 0: Activation (state file, dependency check)
    ├── Phase 1: Script Generation (Claude writes episode script as JSON manifest)
    ├── Phase 2: Media Generation (pipeline.py calls APIs)
    │   ├── Images: Flux via fal.ai
    │   ├── Video clips: Kling I2V via fal.ai
    │   ├── Audio: ElevenLabs TTS
    │   └── Assembly: FFmpeg
    ├── Phase 3: Review (human watches output)
    └── Phase 4: Complete (checkpoint validation)

Triggers

• /episode <topic>
• "generate an episode about..."
• "create educational video on..."
• "produce an episode explaining..."

Phase 0: Activation

State File (Automatic)

Create .claude/autonomous-state.json with "mode": "episode" at activation.

Dependency Check

Before proceeding, verify dependencies are installed:

python3 -c "import fal_client; import elevenlabs" 2>/dev/null || {
    echo "Installing dependencies..."
    pip3 install fal-client elevenlabs
}

API Keys Check

Required environment variables:

• FAL_KEY - fal.ai API key
• ELEVENLABS_API_KEY - ElevenLabs API key

[ -z "$FAL_KEY" ] && echo "ERROR: FAL_KEY not set" && exit 1
[ -z "$ELEVENLABS_API_KEY" ] && echo "ERROR: ELEVENLABS_API_KEY not set" && exit 1

If missing, ask the user ONCE at start, then proceed autonomously.

Phase 1: Script Generation (Claude as Creative Director)

You ARE the creative director. Write the episode script as a JSON manifest.

Episode Structure: The 7-Act Framework

Every episode follows this learning-science-backed narrative structure:

Scene Count by Duration

Minecraft Visual Style Guide

ALWAYS include this prefix in visual prompts:

"Minecraft-style 3D voxel world. Blocky cubic geometry, pixel-art textures, warm ambient lighting. Characters are blocky humanoid figures with square heads. Bright saturated colors, soft shadows. Low-poly aesthetic."

Visual Metaphor Dictionary:

Manifest Schema

Create the manifest at episodes/EP{NNN}/manifest.json:

{
  "episode_id": "EP001",
  "title": "How Photosynthesis Works",
  "topic": "photosynthesis",
  "target_duration_seconds": 180,
  "style": "minecraft",
  "created_at": "2026-01-30T21:00:00Z",
  "cost_budget_usd": 25.00,
  "cost_spent_usd": 0.00,

  "scenes": [
    {
      "scene_id": "scene-001",
      "sequence": 1,
      "act": "SPARK",
      "duration_seconds": 10,
      "narration": "What if I told you that every leaf is a tiny factory?",
      "visual_prompt": "Minecraft-style forest clearing at sunrise. Sunbeams pierce through blocky oak leaves. Golden light particles float in the air. A blocky character looks up in wonder at the glowing canopy.",
      "camera": "slow_pan_up",
      "music_mood": "wonder",

      "image": {
        "status": "pending",
        "fal_request_id": null,
        "asset_path": null,
        "cost_usd": 0
      },
      "clip": {
        "status": "pending",
        "fal_request_id": null,
        "asset_path": null,
        "cost_usd": 0
      },
      "audio": {
        "status": "pending",
        "asset_path": null,
        "cost_usd": 0
      }
    }
  ],

  "assembly": {
    "status": "pending",
    "asset_path": null
  }
}

Writing the Script

1. Create episode directory:

   mkdir -p episodes/EP001/assets/{images,clips,audio}
   

2. Write manifest.json with all scenes following the 7-act structure

3. Each scene needs:

   • narration: What the narrator says (10-20 words per 10s)
   • visual_prompt: Detailed Minecraft-style visual description (include style prefix)
   • camera: Camera movement (static, slow_pan, zoom_in, tracking)
   • duration_seconds: 8-15 seconds per scene

Phase 2: Media Generation

Run the pipeline script to generate all media:

python3 ~/.claude/skills/episode/scripts/pipeline.py episodes/EP001/manifest.json

The script handles:

1. Images → Flux via fal.ai (~3-10s per image)
2. Video clips → Kling I2V via fal.ai (~60-180s per clip)
3. Audio → ElevenLabs TTS (~2-5s per scene)
4. Assembly → FFmpeg concat with crossfades

Monitoring Progress

The manifest is updated after each operation. Check progress:

cat episodes/EP001/manifest.json | jq '.scenes[] | {scene_id, image: .image.status, clip: .clip.status, audio: .audio.status}'

Resume from Checkpoint

If the pipeline crashes or times out, simply re-run:

python3 ~/.claude/skills/episode/scripts/pipeline.py episodes/EP001/manifest.json

The script reads the manifest and skips completed work.

Cost Tracking

The manifest tracks costs per operation. Check total:

cat episodes/EP001/manifest.json | jq '.cost_spent_usd'

Expected costs:

• 3-minute episode: $15-22
• 10-minute episode: $48-68

Phase 3: Review

After pipeline completes, the final video is at:

episodes/EP001/episode.mp4

Human review is required. Watch the video and verify:

• Narration is clear and educational
• Visuals match the Minecraft style
• Pacing feels natural
• No jarring cuts or artifacts
• Audio levels are balanced

Phase 4: Complete

Completion Checkpoint Schema

{
  "self_report": {
    "is_job_complete": true,
    "code_changes_made": true,
    "linters_pass": true,
    "category": "pattern"
  },
  "reflection": {
    "what_was_done": "Generated 3-min episode 'How Photosynthesis Works' with 15 scenes",
    "what_remains": "none",
    "key_insight": "Reusable lesson about episode generation approach (>50 chars)",
    "search_terms": ["episode", "video-generation", "minecraft"],
    "memory_that_helped": []
  },
  "evidence": {
    "episode_path": "episodes/EP001/episode.mp4",
    "manifest_path": "episodes/EP001/manifest.json",
    "cost_usd": 18.50,
    "duration_seconds": 182,
    "scene_count": 15
  }
}

Troubleshooting

fal.ai Queue Timeout

If Kling takes too long (>5 min per clip), the script may timeout. Just re-run:

python3 ~/.claude/skills/episode/scripts/pipeline.py episodes/EP001/manifest.json --phase clips

Rate Limits

The script caps concurrent video submissions to 3. If you hit rate limits, wait 60 seconds and re-run.

Style Drift

If later clips look less "Minecraft-like", the I2V model may be drifting. Regenerate the keyframe image with a stronger style prompt and re-run the clip generation.

FFmpeg Errors

Ensure FFmpeg is installed:

which ffmpeg || brew install ffmpeg

API Reference

fal.ai Endpoints

ElevenLabs

Example: 3-Minute Episode on Photosynthesis

# 1. Invoke the skill
/episode "How photosynthesis works"

# 2. Claude writes the script (manifest.json with 15 scenes)

# 3. Run the pipeline
python3 ~/.claude/skills/episode/scripts/pipeline.py episodes/EP001/manifest.json

# 4. Watch the output
open episodes/EP001/episode.mp4

# 5. Update checkpoint and complete

Skill Fluidity

You may use techniques from any skill for sub-problems without switching modes. Your autonomous state and checkpoint remain governed by /episode.

Philosophy

This skill embodies the Namshub principle: Claude is the intelligence, APIs are the tools.

Claude doesn't just call APIs. Claude is the creative director who:

• Writes compelling educational narratives
• Designs visual metaphors that make abstract concepts tangible
• Paces the episode for engagement and retention
• Makes intentional creative decisions at every step

The APIs generate pixels and audio. Claude provides the vision.