manim-skill

Project Structure

Create a dedicated folder for each animation project in the user's current working directory (NOT in this skill's base directory). Use this flat structure:

<project-name>/
├── plan.md              # Planning document (Phase 1)
├── script.py            # Manim code (Phase 2)
├── concat.txt           # ffmpeg scene list (Phase 3)
├── final.mp4            # Stitched output (Phase 3)
└── media/               # Auto-generated by manim
    └── videos/
        └── script/
            └── 480p15/  # or 1080p60
                ├── Scene1_Name.mp4
                ├── Scene2_Name.mp4
                └── ...

Before starting: Create the project folder and work from within it. All commands should be run from the project directory.

mkdir -p <project-name> && cd <project-name>

Workflow Overview

Plan → Code → Render → Iterate

Phase 1: Plan

If the user has already used plan mode in claude code or provided detailed requirements, write that in plan.md and skip to Phase 2. Otherwise, you MUST carefully plan the video structure before writing code.

Before writing any Manim code, wrtie plan.md:

# [Video Title]

## Overview
- **Topic**: [Core concept]
- **Hook**: [Opening question/mystery]
- **Target Audience**: [Prerequisites]
- **Estimated Length**: [X minutes]
- **Key Insight**: [The "aha moment"]
- **Resolution**: [480p(default), 1080p]
- **Aspect Ratio**: [16:9(default) / 9:16 / 1:1]

## Narrative Arc
[2-3 sentences describing the journey from confusion to understanding]

---

## Scene 1: [Scene Name]
**Duration**: ~X seconds
**Purpose**: [What this scene accomplishes]

### Visual Elements
- [List of mobjects needed]
- [Animations to use]
- [Camera movements]

### Content
[Detailed description of what happens, what's shown, what's explained]

### Voiceover
- **Text**: "[Exact script or key points]"
- **Sync Points**: "[phrase]" → syncs with [animation]

### Technical Notes
- [Specific Manim classes/methods to use]
- [Any tricky implementations to note]

---

## Scene 2: [Scene Name]
...

---

## Transitions & Flow
[Notes on how scenes connect, recurring visual motifs]

## Shared Elements
- [Recurring mobjects across scenes, e.g., "coordinate axes reappear in scenes 2, 4, 6"]
- [Visual motifs, e.g., "blue highlight for key terms"]

## Color Palette
- Primary: [color] - used for [purpose]
- Secondary: [color] - used for [purpose]
- Accent: [color] - used for [purpose]
- Background: [color]

Phase 2: Code

BEFORE writing any code, you MUST invoke the manimce-best-practices skill using the Skill tool, then read the relevant rule files it references (e.g., rules/scenes.md, rules/animations.md) based on what your video needs.

Write Manim Community Edition code in script.py.

Code Structure

1. One class per scene - Name scenes descriptively: Scene1_Introduction, Scene2_DerivePDE
2. Always add subtitles to your animations with add_subcaption()
   • Manim generates a .srt file automatically
   • The viewer handles subtitle display and lets users toggle/resize them

from manim import *

## Scene1_Introduction
class Scene1_Introduction(Scene):
    def construct(self):
        ## Scene1_Introduction.title
        title = Text("My Topic", font_size=48, color=BLUE)
        self.add_subcaption("Introducing our topic", duration=2)
        self.play(Write(title))
        self.wait(1)

        ## Scene1_Introduction.fadeout
        self.play(FadeOut(title), subcaption="Let's begin", subcaption_duration=1)

Phase 3: Render

Use manim CLI to render scenes. Multiple scenes can be rendered in parallel with one command.

manim -q<quality> [--media_dir <output_dir>] <script.py> Scene1 Scene2 Scene3 ...

Quality flags:

• -ql - Low quality (480p15, fastest for testing. Use by default)
• -qh - High quality (1080p60, only when user explicitly requests)

Output location: /media/videos/<script_name>/<quality>/SceneName.mp4

Default /media is located in current directory.

If any scene fails: Read the error, fix the code, re-render only the failed scenes.

Stitch scenes with ffmpeg

Once all scenes render successfully, combine them. All paths are relative to the project folder:

# Create concat list (run from project folder)
cat > concat.txt << 'EOF'
file 'media/videos/script/480p15/Scene1_Intro.mp4'
file 'media/videos/script/480p15/Scene2_Main.mp4'
file 'media/videos/script/480p15/Scene3_Conclusion.mp4'
EOF

# Combine videos
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy final.mp4

Result: final.mp4 is created in the project folder alongside script.py and concat.txt.

Phase 4: Iterate on User Feedback

Launch the viewer for user to review and provide feedback (run from project folder):

python3 ../tools/video_viewer.py final.mp4 --order concat.txt [--script script.py]

• --order: Video order file (concat.txt, required for chapters)
• --script: Manim script (enables high-quality download option)

When user provides feedback:

1. Identify which scenes need changes
2. Modify the code
3. Re-render only affected scenes
4. Re-stitch the final video
5. Run the viewer command again