¶ VidCraft - AI Video Production
¶ Table of Contents
- Overview
- Key Features
- Workflow Pipeline
- System Requirements
- Installation
- Configuration
- Skills
- Video Types
- MCP Tools
- Usage
- Quality Gates
- Troubleshooting
- Technical Details
- FAQ
¶ Overview
VidCraft is a Claude Code plugin for professional AI-generated video production with HeyGen and Synthesia. It guides you through the complete production lifecycle — from concept development through scripting and storyboarding to publishing.
VidCraft does not automate video generation itself — it optimizes the entire preparation and review process so you produce high-quality videos in a fraction of the time.
What VidCraft solves:
- Without VidCraft: Unstructured script writing, forgotten scenes, inconsistent quality
- Without VidCraft: Manual copy-paste between documents and platform
- With VidCraft: Structured workflow with quality gates, automated timing analysis, platform-optimized formatting
¶ Key Features
- 32 specialized skills for each production phase
- 29 MCP tools for state management, content, analysis, and quality gates
- 12 video types with pacing rules, structure templates, and best practices
- Document Analysis — Analyze existing documentation (PDF/DOCX/MD) and convert to video content
- 14-point script quality checklist with automated checks
- Pre-generation gates that block until everything is ready
- Dual platform support — HeyGen and Synthesia simultaneously
- Multi-language — Primary and translation languages configurable
¶ Workflow Pipeline
graph TD
A["New Project"] --> B{"Docs available?"}
B -->|Yes| C["Doc Analyzer"]
B -->|No| D["Develop Concept"]
C --> D
D --> E["Creative Brief"]
E --> F["Write Script"]
F --> G["Script Review 14-Point"]
G --> H["Create Storyboard"]
H --> I["Plan Screenshots"]
I --> J["Collect Assets"]
J --> K["Pre-Generation Check"]
K --> L{"Platform?"}
L -->|HeyGen| M["HeyGen Format"]
L -->|Synthesia| N["Synthesia Format"]
M --> O["Manual Generation"]
N --> O
O --> P["Video Review"]
P --> Q["Publish"]
¶ Typical Workflow
/vidcraft:new-project— Create project with directory structure/vidcraft:doc-analyzer— (Optional) Analyze existing documentation/vidcraft:project-conceptualizer— Develop concept and episode plan/vidcraft:brief-creator— Create creative brief/vidcraft:script-writer— Write scripts with narration and visual cues/vidcraft:script-reviewer— 14-point quality checklist/vidcraft:storyboard-creator— Scene-by-scene visual direction/vidcraft:screenshot-planner— Define screenshots and recordings/vidcraft:asset-collector— Verify and organize assets/vidcraft:pre-generation-check— Quality gates before generation/vidcraft:heygen-engineeror/vidcraft:synthesia-engineer— Platform format- Generate in HeyGen/Synthesia (manual)
/vidcraft:video-reviewer— 20-point review/vidcraft:release-director— Coordinate publishing
¶ System Requirements
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.10+ | Recommended: Python 3.12 |
| Claude Code | 1.0+ | CLI, Desktop, or VS Code Extension |
| pip | 22+ | For venv dependencies |
¶ Installation
git clone https://github.com/markus-michalski/vidcraft.git ~/projekte/vidcraft
- Download from GitHub Releases
- Extract to
~/projekte/vidcraft/
¶ Step 2: Install plugin
claude plugin install ~/projekte/vidcraft
¶ Step 3: Run setup
In Claude Code:
/vidcraft:setup
This automatically creates:
- Python venv at
~/.vidcraft/venv/ - Installs dependencies (FastMCP, PyYAML, pdfplumber, python-docx, textstat)
- Config template at
~/.vidcraft/config.yaml - Cache directory
~/.vidcraft/cache/
¶ Step 4: Customize configuration
nano ~/.vidcraft/config.yaml
¶ Step 5: Restart Claude
Restart Claude Code. Verify with /vidcraft:session-start.
¶ Configuration
¶ config.yaml
paths:
content_root: "~/video-projects"
video_root: "~/video-projects/videos"
assets_root: "~/video-projects/assets"
overrides: "~/video-projects/overrides"
defaults:
language: ["de", "en"]
wpm: 140
platform: "heygen"
heygen:
default_avatar: ""
default_voice: ""
synthesia:
default_avatar: ""
default_voice: ""
brand:
name: "Company Name"
primary_color: "#2563EB"
secondary_color: "#10B981"
tone: ["professional", "friendly"]
¶ Paths
| Path | Description |
|---|---|
~/.vidcraft/config.yaml |
User configuration |
~/.vidcraft/cache/state.json |
State cache (automatic) |
~/.vidcraft/venv/ |
Python virtual environment |
{content_root}/projects/ |
Project files (Markdown) |
{video_root}/projects/ |
Generated videos |
{assets_root}/projects/ |
Screenshots, images |
¶ Skills
¶ Core (6 Skills)
| Skill | Model | Description |
|---|---|---|
new-project |
Sonnet | Create project with directory structure |
session-start |
Sonnet | Initialize session, verify setup |
resume |
Sonnet | Continue working on a project |
next-step |
Sonnet | Recommend next action based on status |
project-dashboard |
Sonnet | Show progress dashboard |
project-conceptualizer |
Opus | 5-phase concept development |
¶ Research (4 Skills)
| Skill | Model | Description |
|---|---|---|
doc-analyzer |
Opus | Analyze PDF/DOCX/MD, extract video content |
researcher |
Opus | Topic research with web access |
audience-researcher |
Opus | Audience analysis and personas |
research-verifier |
Sonnet | Fact-checking and source validation |
¶ Writing (4 Skills)
| Skill | Model | Description |
|---|---|---|
script-writer |
Opus | Scripts with narration and visual cues |
script-reviewer |
Sonnet | 14-point quality checklist |
brief-creator |
Opus | Creative brief from requirements |
voice-checker |
Sonnet | Detect AI language patterns |
¶ Visual (4 Skills)
| Skill | Model | Description |
|---|---|---|
storyboard-creator |
Opus | Scene-by-scene storyboard |
shot-list-creator |
Sonnet | Production-ready shot list |
screenshot-planner |
Sonnet | Define screenshot positions |
asset-collector |
Sonnet | Verify and organize assets |
¶ Production (4 Skills)
| Skill | Model | Description |
|---|---|---|
heygen-engineer |
Sonnet | HeyGen-optimized format |
synthesia-engineer |
Sonnet | Synthesia-optimized format |
avatar-selector |
Sonnet | Avatar recommendation by audience |
pre-generation-check |
Sonnet | Quality gates before generation |
¶ Review (5 Skills)
| Skill | Model | Description |
|---|---|---|
video-reviewer |
Opus | 20-point post-generation review |
brand-checker |
Sonnet | Brand consistency audit |
accessibility-checker |
Sonnet | Accessibility (WCAG 2.1) |
voice-checker |
Sonnet | Detect AI language |
timing-validator |
Haiku | Quick timing check |
¶ Distribution (3 Skills)
| Skill | Model | Description |
|---|---|---|
release-director |
Sonnet | Coordinate publishing |
promo-writer |
Opus | Write social media copy |
thumbnail-director |
Sonnet | Create thumbnail concepts |
¶ Utility (4 Skills)
| Skill | Model | Description |
|---|---|---|
video-type-creator |
Opus | Create new video types |
help |
Haiku | Show available skills |
configure |
Sonnet | Interactive config setup |
setup |
Sonnet | First-time setup |
¶ Video Types
| Type | Duration | Pacing | Use Case |
|---|---|---|---|
| tutorial | 3-15 min | Slow, step-by-step | Software instructions |
| installation-guide | 2-8 min | Clear, sequential | Plugin/software installation |
| product-demo | 2-5 min | Medium, dynamic | Product showcase |
| explainer | 60-120s | Medium to fast | Explain concepts |
| training | 5-20 min | Structured | Employee training |
| onboarding | 3-10 min | Friendly, clear | New users/employees |
| marketing-spot | 15-60s | Fast, emotional | Advertising (AIDA) |
| faq-video | 30-90s | Direct | Support relief |
| testimonial | 60-120s | Authentic | Social proof |
| how-to | 2-8 min | Practical | Hands-on guides |
| webinar-teaser | 30-60s | Energetic | Event promotion |
| social-short | 15-60s | Very fast | TikTok/Reels/Shorts |
Each type has a README.md with structure template, pacing rules, script conventions, visual direction, and example storyboard.
New video types can be created anytime with
/vidcraft:video-type-creator.
¶ MCP Tools
¶ State Management (8 Tools)
| Tool | Description |
|---|---|
list_projects |
List all projects with status |
find_project |
Find project by slug or name |
get_project_full |
Complete project with all episodes and scenes |
get_project_progress |
Progress percentage per phase |
rebuild_state |
Rebuild state cache from Markdown |
get_session |
Current session (last project, phase) |
update_session |
Update session context |
search |
Full-text search across all projects |
¶ Content Operations (7 Tools)
| Tool | Description |
|---|---|
create_project_structure |
New project with templates |
create_episode |
Create episode in project |
create_scene |
Create scene in episode |
update_field |
Update YAML frontmatter field |
resolve_path |
Resolve filesystem path |
extract_section |
Extract markdown section |
format_for_clipboard |
Format script for copy-paste |
¶ Document Analysis (5 Tools)
| Tool | Description |
|---|---|
analyze_document |
Parse PDF/DOCX/MD and structure |
extract_key_points |
Identify key points for video |
suggest_video_structure |
Derive scene structure from docs |
analyze_complexity |
Assess complexity, recommend type |
suggest_video_topics |
Suggest video topics from docs |
¶ Platform Integration (5 Tools)
| Tool | Description |
|---|---|
validate_platform_limits |
Check character/scene limits |
get_platform_capabilities |
Query platform features |
heygen_format_script |
Format for HeyGen |
synthesia_format_script |
Format for Synthesia |
list_required_assets |
Identify missing assets |
¶ Script Analysis (2 Tools)
| Tool | Description |
|---|---|
analyze_timing |
WPM calculation, duration estimate |
check_readability |
Flesch score, sentence length |
¶ Quality Gates (2 Tools)
| Tool | Description |
|---|---|
run_pre_generation_gates |
All gates before generation |
validate_project_structure |
Check directory integrity |
¶ Usage
¶ Quick Start
/vidcraft:new-project "OXID Gallery Tutorial" tutorial
Claude creates the project structure and asks about episodes.
1. /vidcraft:new-project "OXID Gallery Tutorial" tutorial
2. /vidcraft:doc-analyzer ~/docs/gallery-readme.md
3. /vidcraft:script-writer oxid-gallery-tutorial 01-installation
4. /vidcraft:script-reviewer oxid-gallery-tutorial 01-installation
5. /vidcraft:storyboard-creator oxid-gallery-tutorial 01-installation
6. /vidcraft:pre-generation-check oxid-gallery-tutorial 01-installation
7. /vidcraft:heygen-engineer oxid-gallery-tutorial 01-installation
1. /vidcraft:doc-analyzer ~/docs/existing-manual.pdf
-> Analysis: 3500 words, 12 sections, recommended: tutorial series (3 episodes)
2. /vidcraft:new-project "Product Manual" tutorial
3. /vidcraft:brief-creator product-manual
4. /vidcraft:script-writer product-manual 01-introduction
1. /vidcraft:new-project "What is ALTCHA?" explainer
2. /vidcraft:script-writer what-is-altcha 01-explanation
3. /vidcraft:synthesia-engineer what-is-altcha 01-explanation
¶ Quality Gates
¶ Pre-Generation Gates
| # | Gate | Type | Description |
|---|---|---|---|
| 1 | Script Status | BLOCK | Script must be reviewed |
| 2 | Scenes Exist | BLOCK | At least one scene with narration |
| 3 | Narration Complete | BLOCK | All scenes must have narration |
| 4 | Visual Direction | WARN | All scenes should have visual direction |
| 5 | Timing | INFO | Show estimated duration |
¶ Script Quality Checklist (14 Points)
- Timing (WPM vs. target duration)
- Readability (Flesch score >= 60)
- Structure (type-conforming scene sequence)
- Hook quality (first 5 seconds)
- CTA present and clear
- Consistent tone
- No AI language
- Sentence length (max 20 words)
- Scene duration (none > 60s)
- Transitions defined
- Visual cues present
- On-screen text <= 7 words
- No jargon without explanation
- Summary present (for tutorials)
¶ Troubleshooting
¶ Problem: MCP Server not connecting
Symptoms: Skills show errors, no MCP tools available
Check:
- Plugin installed?
claude plugin list - venv exists?
ls ~/.vidcraft/venv/bin/python3 - Dependencies installed?
~/.vidcraft/venv/bin/pip list | grep mcp
Solution:
/vidcraft:setup
¶ Problem: State cache empty
Symptoms: list_projects shows nothing despite existing projects
Solution:
/vidcraft:session-start
This rebuilds the state cache automatically.
¶ Problem: Document analysis fails
Symptoms: analyze_document returns import error
Solution:
~/.vidcraft/venv/bin/pip install pdfplumber python-docx
¶ Technical Details
¶ Architecture
graph TD
A["Claude Code"] -->|stdio| B["FastMCP Server"]
B --> C["StateCache"]
C --> D["state.json"]
B --> E["Indexer"]
E --> F["Markdown Parsers"]
F --> G["Project Files"]
B --> H["Document Parser"]
H --> I["PDF / DOCX / MD"]
B --> J["Script Analyzer"]
¶ Project Structure
vidcraft/
├── .claude-plugin/ # Plugin manifest
├── servers/vidcraft-server/ # FastMCP server (Python)
├── tools/ # Backend modules
│ ├── shared/ # Config, Paths
│ ├── state/ # Indexer, Parsers
│ └── analysis/ # Document Parser
├── skills/ # 32 SKILL.md files
├── templates/ # 7 Markdown templates
├── video-types/ # 12 type definitions
├── reference/ # Knowledge base
├── hooks/ # PostToolUse validation
└── tests/ # 138 tests (pytest)
¶ Status Progressions
Project:
Concept -> Brief Complete -> Research Done -> Script Draft -> Script Approved
-> Storyboard Done -> Assets Ready -> Generated -> Reviewed -> Published
Episode:
Not Started -> Script Draft -> Script Reviewed -> Storyboard
-> Assets Collected -> Ready for Generation -> Generated -> QA Passed -> Final
Scene:
Outline -> Script Written -> Visual Defined -> Assets Ready -> Generated -> Approved
¶ FAQ
Q: Does VidCraft generate videos automatically?
A: No. VidCraft optimizes the preparation process (script, storyboard, formatting). Actual video generation happens manually in HeyGen or Synthesia. Future versions may include API integration.
Q: Can I use both platforms simultaneously?
A: Yes. Each episode can have its own platform. Creative work is platform-independent.
Q: Which document formats are supported?
A: PDF, DOCX, and Markdown. The doc analyzer extracts structure, code blocks, lists, and headings.
Q: Can I create custom video types?
A: Yes. Use /vidcraft:video-type-creator [name] to create new type definitions with pacing rules, structure templates, and best practices.
Q: Do I need a HeyGen/Synthesia account?
A: Yes, for generation. VidCraft itself is free and open source.
¶ License
MIT License — GitHub Repository
Developed by Markus Michalski