manim-skill— agent 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