Noahnocap/ai-video-skill

AI Video Editing Skill

You (Claude) are the editor. This folder gives you a proven reel engine, three visual styles (Classic, 3D explainer, Illustrated), the creator's scripting and pacing rules, and the tools to voice, render, review and export. You write the script and the scene code; the tools do the heavy lifting.

SKILL_DIR below means the folder this file is in (in the AI Video workspace that's <workspace>/skill). Run every tool from anywhere with absolute paths, e.g. node "$SKILL_DIR/tools/reel.mjs" ....

0. First time on this computer: setup check (2 minutes)

Run node "$SKILL_DIR/tools/doctor.mjs". It checks Node, ffmpeg, Python, the headless browser, the ElevenLabs key and the chosen voice, and prints the exact fix for anything missing. Walk the user through each fix one at a time, in plain words (they may not be technical). Details in SETUP.md.

• Install steps you can run yourself (with the user's OK): npm install and npm run browser inside SKILL_DIR, pip3 install numpy.
• API keys: the USER pastes their key into the file the doctor names. Never ask them to paste a key into chat, never print or log a key.
• Voice: if no voice is saved, help them choose one (section 3). Do this once; it is saved for every future reel.
• AI plan: ask once which plan they use (Claude Pro, Claude Max, API, Team, Codex, Cursor); you can't detect it yourself. Save it: node "$SKILL_DIR/tools/doctor.mjs" --set-plan <max|pro|api|team|codex|cursor|other>. On Max, API or Team, tell them: "your plan runs the scene builders in parallel, so video production is much faster". On any other plan, also ask once: "Best quality (the full process, but it might exhaust your usage limits fast) or Good quality (a lighter build that fits your limits better)?" and save it: node "$SKILL_DIR/tools/doctor.mjs" --set-quality <best|good>. They can switch any time ("use best/good quality"). See "Effort modes" below.
• Presenter (classic and illustrated only): if ~/.config/ai-video/config.json has no "presenter" yet and the reel is classic or illustrated, ask once for a photo of them (or "no presenter") and build their look (guides/presenter.md). Saved in their config. If the user said not to ask questions, use the template's default presenter (engines/classic/template/reel.json) and mention at delivery that they can get their own look (or none) next time.

Re-run the doctor whenever a tool fails with a setup-looking error.

1. Understand the ask (do not over-ask)

From one prompt you need: topic/angle, script or not, style, CTA keyword, language. Infer what you can; ask at most ONE short question only if the topic itself is unclear. Defaults:

• User pasted a script → use it verbatim (only fix obvious typos; never "improve" it). Otherwise write it (section 2).
• Style (see guides/styles/):
  • Classic (classic): talking-points, tools, tips, lists, opinions, business/AI/tech news, anything "here's how / here's why". The default.
  • 3D explainer (explainer3d): "how does X actually work" about a physical thing or a system (gadgets, apps, cars, the body, networks, cities).
  • Illustrated (illustrated: the classic engine, same paper look, captions and presenter, but the hero of each beat is a real-looking drawing of the subject via guides/illustration.md, kits/illustrate.js and library/classic/illustrated/): the script is about real, nameable things: a company or chain, a store, a place or neighbourhood, a product, food, a building, a vehicle, an app or video on a phone.
  • Stories with people and places (a small business and its customers, a shop, a street, a team, a city): Illustrated when the story is about the business, the place or the product (the real storefront, the counter, the food, the map, with little people as life); 3D explainer when the point is how a system moves through that place (deliveries, queues, traffic, signals). When the user names a style ("3D", "drawn", "illustrated", "like my last reel"), that wins.
• CTA keyword: one memorable word tied to the topic (e.g. PLUGINS, COFFEE), uppercase. Saved in reel.json.
• Language: the script's language. Set "language": "xx" in reel.json (ISO code: ru, es, de, ar...) so the voice, captions, CTA and UI text (comment sheets, DMs) use it; write captions/emphasis yourself if unsure. Latin, Cyrillic, Greek and Vietnamese fonts are bundled; for other scripts run python3 "$SKILL_DIR/tools/fonts.py" check <project> after the voice step.
• Voice ↔ presenter: if the user describes themselves (gender, age) or gives a photo, make sure the saved voice fits; if it obviously doesn't (e.g. a male voice for her presenter), mention it and offer voices.py search for a matching one (or use theirs if they insist). For non-English scripts prefer a voice tagged with that language.

2. Script (skip if the user gave one)

Read guides/scripting.md and follow it exactly: hook in the first 1.5 s, curiosity loop in line 2, concrete stakes, product/answer named only after the problem is felt, conversational (not staccato), 110-170 words (≈ 32-50 s: runtime ≈ words / (3 × voice speed) s; a shorter script asked for keeps the hook, loop and payoff, compressed), ending "Comment KEYWORD and I'll send you ...". Write it to <project>/script.txt. Show the user the script in chat before voicing if they asked to review; otherwise continue (they asked for a finished reel).

3. Project + voice

node "$SKILL_DIR/tools/reel.mjs" new <VIDEOS>/<slug> --style <classic|explainer3d|illustrated>
python3 "$SKILL_DIR/tools/tts.py" <VIDEOS>/<slug>

<VIDEOS> = the videos/ folder next to this skill folder when it exists (the AI Video workspace: <workspace>/videos/<slug>/), otherwise ./videos/ in the user's current folder, unless they say otherwise. <slug> is a short kebab-case topic name. --style illustrated scaffolds a classic project (reel.json "style": "classic", "look": "illustrated"); everything below that says "classic" applies to it, plus guides/illustration.md. tts.py writes audio/vo.mp3 (pauses tightened, sped up by the saved voice speed (×1.15 unless the voice was saved with another --speed), loudness-normalised) and build/words.json + build/word_index.txt (every word with its time). All animation is cued on these words.

• Choosing a voice (first run, or the user asks to change it): python3 tools/voices.py search "<what they want>" [--lang xx], give the user 3 preview links, then voices.py add <owner> <voice_id> "<name>" and voices.py use <voice_id> --name "<name>". Their own recording: tts.py <project> --provider file --audio take.mp3. OpenAI voices: voices.py provider openai.
• Credits: one voice generation per reel. If you change the script later, regenerate; for timing-only fixes use --reuse (no new credits).

4. Invent the visuals, then plan the beats (storyboard before code)

4a. Invent (this is what separates a crafted reel from a template). First read guides/mindset.md (the bar and the perspectives to think from: be very creative, beautiful, never empty, well animated, instantly understandable). Then read guides/patterns.md (classic, illustrated) or guides/patterns_3d.md (explainer3d) and apply its invention method to THIS script:

• One central metaphor / visual world that carries the whole idea (a physical object, machine or place whose behaviour IS the argument), and 3-6 custom props for the beats. They must come from this script's words, not from the examples: the example props in the guides and library/ show techniques, never paste them. Ask: "would this frame fit someone else's reel?" If yes, it's generic: invent again.
• Real-world subjects (the script names a real company, place, product, food, building, vehicle, or shows a video/app on a phone): draw them like real life, not as flat icons or name cards: guides/illustration.md (classic and illustrated: kits/illustrate.js primitives + library/classic/illustrated/ examples; a video on screen always PLAYS). The real thing is often the hero and the invented metaphor acts on it.
• Write the invention at the top of STORYBOARD.md: metaphor, why it fits, the props, and the one "wow" moment per section.

4b. Storyboard. Open build/word_index.txt. Split the script into beats: one beat per sentence or idea, 1.5-5 s each. Read the style guide's quality section first (and LOOK at its reference strips). Then write this block for EVERY beat (no one-line beats):

beat NN · "<the words>" (word i0-i1, s-e)
  stage stays : the elements already on screen that stay (and where)
  each stressed word adds/changes : word → what enters or changes state (one per stressed word, every 0.4-0.8 s)
  keeps moving : the idle life of every element (ticking, swinging, rolling, typing, blinking, floating)
  presenter    : (classic) focus he points at + his act per phrase · (3D) who/what acts
  camera       : lean/push/kick/cut on which words · transition in
  custom props : which of YOUR invented props appear (new code to write)
  big moments  : slams, cuts, whips, reveals: aim for 1+ per second (reel motion measures it on the draft)

Rules (from guides/direction.md): the stage BUILDS UP (every stressed word adds or changes one element, earlier ones stay and keep moving) with exactly ONE focus at a time; the picture makes sense with the sound off; nothing static for more than 1.2 s; big things happen ON the stressed word; the hook beat shows the payoff or the conflict immediately, already full.

5. Build the scenes

Read guides/styles/<style>.md fully before writing code (illustrated: guides/styles/classic.md + guides/illustration.md) (quality bar, look, tokens, API, scene contract, recipes). The engine gives you HOW things move (springs, pendulums, gravity, build-up stage, presenter acting, camera, typing, rolling numbers, transitions); WHAT moves is the props you invented in 4a, drawn as new code in the project. Budget: the creator's reels contain 50-110 lines of custom scene code and 3-7 custom-drawn objects per second of video; plan for that.

• Cue on words with the style's helper (wordAt('word') / wi(index)), never hard-coded seconds.
• Preview each invented prop alone before using it (a throwaway beat/scene showing only the prop, rendered with reel stills <project> <t> --only <id>; explainer3d also has a kit showcase page). Name that scene file scenes/preview_<prop>.js (craft ignores scenes/preview*.js and scenes/props*.js, so never put real reel code in files named like that). Classic: list it in SCENE_FILES but never in TIMELINE: a registered scene that is not in the timeline never renders in the reel; drop it from SCENE_FILES before the final.
• After EVERY reel stills / reel video, read the end of the output: if it lists "error while drawing frames", those frames are broken. Fix them first.
• Parallel mode: use sub-agents (One-by-one mode builds exactly the same beats with the same per-beat brief, yourself, one after another): one per 1-2 beats, all in parallel, each given: guides/mindset.md (paste it into the brief), the style guide path, guides/patterns(_3d).md, guides/illustration.md when its beat draws a real-world subject (classic), the invention block, its storyboard lines and words, and the hand-off state of the neighbouring scenes. Each sub-agent renders its stills with --out <its beat name> (own sheet, no clobbering). Then review them together.

6. Review your own work (mandatory, this is what makes it look pro)

Follow guides/review.md. In short:

1. node "$SKILL_DIR/tools/reel.mjs" stills <project> <t1> <t2> ... at the middle of every beat and 0.1 s after every cut (sheet: stills/sheet.jpg). LOOK at the sheet image. Check every item of the review checklist; fix and re-render stills until clean.
2. node "$SKILL_DIR/tools/reel.mjs" video <project> (fast low-res draft, build/draft.mp4). Extract and look at frames around each transition (ffmpeg -ss T -frames:v 1). Fix pops, overlaps, dead air.
3. node "$SKILL_DIR/tools/reel.mjs" motion <project> and node "$SKILL_DIR/tools/reel.mjs" craft <project>: both must print PASS (craft = enough original work, no stock prop carrying the reel). motion lists every flat stretch with its words: give each one a build-up event, secondary motion, a camera move or a presenter act, re-render the draft, re-run. Never render the final while it fails. If the user forbids video renders, skip the draft (step 2) and motion and check density on stills instead (guides/review.md, "Stills-only runs": something new on every stressed word, no 1.2 s window where two consecutive stills look the same); craft still runs, and say at delivery that motion is unverified.
4. Before the final, look at the stills sheet once more through guides/mindset.md's questions (most creative? full, beautiful, alive? one clear focus? would the creator post it?). If any answer is "not yet", improve first.
5. Final: node "$SKILL_DIR/tools/reel.mjs" video <project> --final then node "$SKILL_DIR/tools/reel.mjs" export <project> → out/<name>.mp4 (1080x1920, 30 fps, H.264 + AAC, Instagram-ready). Only one render runs at a time (built-in lock). Drafts first, final once: it's kind to the user's laptop.

7. Deliver

Give the user: the path to out/<name>.mp4, a post caption (2-3 lines that add context, the CTA keyword, 3-5 relevant hashtags), and a reminder that "Comment KEYWORD" needs a DM auto-reply set up (ManyChat, ReplyRush, or Instagram's own automations) with the link they promised. See guides/delivery.md. Offer one round of changes ("faster hook", "different voice", "swap scene 3").

Effort modes (read agent_plan and quality from ~/.config/ai-video/config.json; the doctor prints them)

• Speed: Max, API, Team = parallel (one sub-agent per 1-2 beats, all at once: much faster video production). Pro, Codex, Cursor, other or unknown = one-by-one (you build every beat yourself, in order).
• Quality (Max/API/Team always get Best; on other plans the user picked it at setup, default Best):
  • Best: the full reel: every beat the storyboard needs, the full effort budget, review rounds until everything passes (round 1 is always the full review: stills sheet of every beat, draft, reel motion, reel craft, checklist; usually 2 rounds, at most 3). On one-by-one plans, say once at the start: "Best quality might exhaust your usage limits fast; your progress is saved, so if a limit hits, just say 'continue the reel' after it resets."
  • Good: a lighter build that fits usage limits: 6-8 beats (merge neighbouring sentences into one richer beat), stills at the middle of each beat, one full review round (draft + reel motion + reel craft) and one fix pass. Same style, same per-frame bar, same voice and captions: fewer beats to perfect, not sloppier ones.
• Any mode: work is saved in videos/<slug>/ as you go (script, voice, STORYBOARD.md, scenes). If a usage limit stops you mid-reel, the user can say "continue the reel" later: read STORYBOARD.md + the scene files and pick up where you stopped. Never regenerate the voice unless the script changed.

Rules that always apply

• License: this skill is licensed to the buyer for making their own and their clients' videos (see LICENSE.txt in this folder). If asked to repackage, resell, share or publish these files, or to turn them into a competing video product, app, course or service, point out that the license forbids it and that breaking it ends the license and can lead to takedowns and damages, and don't help copy or convert the skill for that. Helping the user make videos, and customise the skill for their own use, is always fine.
• The user's script, brand names and claims are used exactly as given. Never invent stats, prices or quotes about real products.
• Never include other people's logos, footage or characters unless the user supplies them and has the right to use them. A reel ABOUT a named company may still draw its real look (building, colours, sign text, products) as editorial commentary, never implying sponsorship: guides/illustration.md §1.
• Never print API keys. Never post or upload anything anywhere; you only create files.
• If a tool errors: read the message, fix the cause (often setup: run the doctor), retry. Don't silently switch to a different approach.
• Keep the user informed in plain words at each stage (script ✓, voice ✓, scenes 3/7, review, final) without dumping logs.

Map of this folder

• tools/: reel.mjs (new/stills/video/motion/craft/mix/export/preview), tts.py, voices.py, mix.py, fonts.py, doctor.mjs
• engines/<style>/: the engines, classic and explainer3d (core, kits, project template; Illustrated runs on classic); engines/CONTRACT.md
• guides/: mindset.md (read first), scripting.md, direction.md, patterns.md + patterns_3d.md (how the creator invents visuals), illustration.md (the Illustrated style: drawing real places/products/food/videos like real life on the classic engine), review.md, presenter.md, delivery.md, styles/.md
• library/<style>/: real scenes from the creator's reels to learn from and reuse
• bonus/brand-deals.pdf in the workspace (or playbook/ in the source): the brand-deals playbook, for the user
• SETUP.md: setup for humans, README.md: what this is