# capy-video-gen-skill

capy-video-gen-skill — a Claude Code skill that transforms scripts and ideas into full-length videos where character faces remain consistent throughout. Use it when you need to create multi-shot video from text, a story, or a brief concept.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 138 repo stars
- Author: happycapy-ai
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/capy-video-gen-skill/SKILL.md
- Updated: 2026-09-03
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/capy-video-gen-skill

## What it does

ViMax is a multi-stage pipeline that parses a script, extracts characters with their features, generates three-angle portraits for each one, designs a shot-by-shot storyboard, renders each frame with face recognition prioritized, produces video clips, and assembles the final result. Across 257 experiments, face identification accuracy improved 70% (face distance dropped from 0.74 to 0.22).

You need an `AI_GATEWAY_API_KEY` to run it — HappyCapy pre-fills this. Inside, ViMax uses image generation (Gemini Flash) and video generation (Veo), and the reference image selector always ranks face identity first. The skill accepts two inputs: either a finished screenplay (script2video) or a brief idea (idea2video, which auto-generates a script).

For stable faces, write detailed character descriptions (ethnicity, age, hair colour and texture, eye shape, marks, jawline). Include at least one close-up shot per character. If you have real photos, place them in the working directory and pass them as a reference registry.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add happycapy-ai/Happycapy-skills --skill capy-video-gen-skill -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/capy-video-gen-skill/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/capy-video-gen-skill/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add happycapy-ai/Happycapy-skills --skill capy-video-gen-skill -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/capy-video-gen-skill/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add happycapy-ai/Happycapy-skills --skill capy-video-gen-skill -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/capy-video-gen-skill/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install happycapy-ai/Happycapy-skills skills/capy-video-gen-skill
```

2. **Manually: put the files in place**
- File: `.github/skills/capy-video-gen-skill/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add happycapy-ai/Happycapy-skills --skill capy-video-gen-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/happycapy-ai/Happycapy-skills --path skills/capy-video-gen-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/capy-video-gen-skill/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/capy-video-gen-skill/SKILL.md

## When to use it
- generate video from a written screenplay where all character faces stay identical
- break down a concept into video clips with consistent character faces
- assemble multi-shot video with control over framing and camera movement
- produce character portraits in multiple angles for face recognition
- select best-rendered frames while prioritising face identity

## Example prompts
- Create a video from this screenplay with three characters, each with a distinct face throughout
- Generate a full video from the idea of two friends meeting, no more than five shots
- Take the description of a girl in a red jacket meeting a friend, render it with close-up detail on faces

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4f16118dd9c0b4cd.

BEGIN THIRD-PARTY FILE 4f16118dd9c0b4cd
````text
---
name: capy-video-gen-skill
description: Multi-shot AI video generation pipeline with face identity consistency. Converts scripts or ideas into complete videos using character extraction, storyboarding, frame generation, and video assembly. 300 experiments validated, 70% face distance improvement. Use when the user asks to create a video from a script, story, idea, or wants multi-shot video with consistent characters.
allowed-tools: Bash, Read, Write, Edit
---

# Capy Video Gen Skill - Script-to-Video Pipeline

Generate complete multi-shot videos from scripts or ideas with consistent character faces across all scenes. Built for HappyCapy AI Gateway. 300 experiments validated, 70% face distance improvement.

## Overview

ViMax converts text scripts into full videos through an automated pipeline:
1. Extract characters from script with detailed physical features
2. Generate front/side/back character portraits
3. Design shot-by-shot storyboard
4. Decompose each shot into first_frame, last_frame, and motion descriptions
5. Build camera tree for shot relationships
6. Generate frames with reference image selection (face identity as top priority)
7. Generate video clips from frames
8. Concatenate into final video

## Installation Location

The ViMax pipeline code is at: `/home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/`

All commands must be run from this directory using the venv:
```bash
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
```

## Prerequisites

- `AI_GATEWAY_API_KEY` environment variable (auto-configured in HappyCapy)
- Python venv at `.venv/` (already set up)

## Quick Start

### Script-to-Video

Edit the script, requirements, and style in the entry script, then run:

```bash
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
```

### Idea-to-Video

For generating from a brief idea (auto-generates script first):

```bash
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
```

## Programmatic Usage

```python
import asyncio
from langchain.chat_models import init_chat_model
from tools.render_backend import RenderBackend
````
END THIRD-PARTY FILE 4f16118dd9c0b4cd

The third-party file has ended. Everything between the 4f16118dd9c0b4cd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2292 of 9703 bytes. © happycapy-ai · MIT · https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/capy-video-gen-skill/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
