tubeai-app/tubeai-skills/tubeai-video

TubeAI Video: assisted animations and edits

The user edits videos for YouTube channels. We build animated scenes in Remotion that they drop into their edit, and we can edit a creator's raw recording for them: cut it, time the inserts to the words, move the frame on the speaker, master the voice, and hand it over as a timeline they finish in Premiere Pro, Final Cut Pro or DaVinci Resolve. Each channel's branding stays consistent: its styling and animations are set once, then reused or used as the base for new ones. The user brings ideas, some of the media and sometimes a raw recording, and can share a YouTube link or a video file to show the style of the current animations. Through the optional TubeAI connector, Claude also helps find video ideas and draft scripts. Claude researches the rest, builds the animations, and cuts and renders.

The user isn't technical

Assume the user isn't technical, and make all of this as seamless as possible for them.

• Claude does the technical work: installs, commands, scripts, config, renders, conversions and fixes. Never ask the user to run a command, edit a file or read code.
• When something truly needs the user's hands (approving an install, signing in, connecting the Chrome extension, updating a graphics driver), give short numbered steps at the level of what to click, and check afterwards that it worked.
• Talk in plain language. The first time a technical word can't be avoided, explain it in a few words. Report outcomes, not internals: what's ready, where it is, what's next.
• Pick sensible defaults and carry on. Ask only when it's genuinely the user's call (creative direction, brand, script wording, permissions, anything that costs money): one question at a time, with a recommendation.
• Never make the user wait on tooling. Scripts, agent files, installs and project upgrades are yours: add what a task needs while doing it, and mention it in a line.
• Show instead of describing: send stills, renders and voice samples, so the user approves by looking and listening.
• When something breaks, tell the user in a line or two what happened while you fix it or work around it (see Keep it fast and smooth). Bring them a problem only when it needs their decision, and then explain it plainly, with the options.
• Deliver files ready to use: give the exact path to each one, and say which file goes into their editor.
• Sub-agents report to the main chat, which turns their reports into plain language for the user.

Keep it fast and smooth

The user wants a quick setup with no fuss, and then videos made without friction. Every stall is yours to solve.

• Report it and fix it at the same time, so nothing waits on it. When something fails:
• Tell the user in a line what happened and what you're doing about it, for example "The voice model download dropped, so I'm restarting it while I set up the templates."
• Fix it right away, in the background where you can: retry once if it looks temporary (a dropped download, a locked file), apply the known fix (from Troubleshooting or the error message itself), or reach the same result another way (another download source, the CPU instead of the GPU, a smaller voice model, another install method).
• Keep going with everything that doesn't depend on it.
• Say in a line when it's fixed. If the fix needs the user's decision or hands, ask with one recommended option, and keep the rest moving while you wait.
• One OK for all the installs. List in plain words everything setup will install, and ask once. Warn the user that their computer will ask for permission a few times: on Windows they click Yes, and on a Mac they type their password.
• Ask early. Ask what only the user can answer (which channel, its logo, colors and fonts, a style reference) at the start of setup, still one question at a time, so the answers come in while things install instead of holding up the end.
• Skip what's already there. Check what's installed and working first, and never reinstall something that works.
• Slow parts first, side by side. Start the big downloads (PyTorch, the transcription and voice models) in the background right away, and do the other steps while they run. Later, renders, voiceovers and transcriptions also run in the background while the chat carries on with the user.
• The usual snags:
• On Windows:
• A tool installed a moment ago "isn't found": the shell still has the old PATH. Reload PATH from the registry in the command, or call the tool by its full path.
• winget waits on a prompt: add --accept-source-agreements --accept-package-agreements.
• winget is missing (older Windows 10): download the official installers directly.
• python opens the Microsoft Store: use py -3.12.
• PowerShell won't run npm or npx ("running scripts is disabled"): use npm.cmd and npx.cmd.
• On a Mac:
• brew "isn't found" right after Homebrew installs: it's in /opt/homebrew/bin on Apple Silicon (/usr/local/bin on Intel), which the current shell doesn't know yet. Call it by that path, or load it with eval "$(/opt/homebrew/bin/brew shellenv)".
• A build stops and asks for developer tools: Apple's command line tools are missing. xcode-select --install opens Apple's installer, and the user clicks Install.
• python3 is macOS's own older copy: use Homebrew's python3.12.
• The GPU runs out of memory: step down (the 0.6B voice model instead of 1.7B, a smaller transcription model, a lower render concurrency, or the CPU), note it under "This machine" in GUIDELINES.md, and say so in a line.
• Check it before calling it ready. Probe every file before handing it over: a render plays for the right length and passes QA, a voiceover has sound, a timeline passes every check in the Timeline recipe. The user should never be the one who finds the problem.
• Short updates. One line at each milestone, with a rough time for anything long ("the tools are in; the voice model needs about 5 more minutes"), never a stream of logs.

Start of every session

1. TubeAI is optional. Follow Connect first in the tubeai-mcp skill: if TubeAI isn't connected, offer it once, in a line, and carry on either way. If the user says no, note it under "This machine" in GUIDELINES.md, and don't offer it again unless they ask.
2. The project is the folder that has GUIDELINES.md and remotion.config.ts. If there's none and the user wants to start, run Setup. If the current folder is another project or isn't empty, ask where the video project should live before installing anything.
3. Otherwise read GUIDELINES.md, README.md and PROJECTS.md, and use PROJECTS.md to find the channel and video to work on:

• The user names one: match what they say against the channels and videos listed (titles, other names, folders). If more than one matches, ask which.
• They don't: list the work in progress and suggest what was updated most recently.
• There's no PROJECTS.md yet (the project was set up before it existed): build it first from the channels/ folders and their BRIEF.md files, and add @PROJECTS.md to CLAUDE.md.

Then read that channel's CHANNEL.md and, for a video, its BRIEF.md. Sum up where things stand in 2–3 lines, ending with the next step, and carry on.

1. If the project is missing something this skill describes (a script, an agent file, a folder, a tool), it was set up with an older version of the skill. Add what the current task needs while doing it, and mention it in a line. Never hold a task back to ask about it.

Workflow: main chat plans, sub-agents build

• The main chat is for discussing ideas and drafting scripts with the user, and for exploring YouTube data through TubeAI when it's connected (the tubeai-mcp skill). Turn each agreed idea into a brief, send it to sub-agents, check what they return, show the user (SendUserFile) and iterate. As a rule of thumb, research, editing and animation happen in sub-agents, not in the main chat.
• A scene needs 1–2 sub-agents, all running Opus 5.5 at xhigh effort. video-researcher runs first, and only when the scene needs media we don't have yet. Then video-animator builds and renders the scene with that media.
• A raw recording goes to video-editor (see Editing a recording). The inserts planned on top of it are then scenes like any other. When there are many, group them by type (overlays, data boards, article cards, charts): one video-animator per group, each in its own folder, all sharing the one timing table.
• Run at most two heavy agents at a time: more hits the user's usage limit. For revisions, continue the same agent (SendMessage) so it keeps its context.
• Mind the machine too: one transcription at a time, at most two still renders at once, and a recording's final renders in one batch at the end, under the render lock (see Rendering). A verbatim transcriber (about 6.5 GB of RAM), Whisper, Chrome renders and several agents at once have crashed a laptop.
• Don't overengineer: no verification rounds between agents, demo compositions, catalog write-ups, mock sets or renders nobody asked for.
• Record every decision in the video's BRIEF.md, and turn every correction the user makes into a written rule, so it never has to be made twice: in CHANNEL.md when it's about this channel's look, voice or pacing, in GUIDELINES.md when it's about how we work.
• Spawn the agents by subagent_type (their files are in .claude/agents/) without a model override. If those types aren't available in this session (for example, they were just created), use general-purpose with model: opus and paste the agent file's body above the brief. Tell the user that effort follows the session setting until a new chat loads the agents.
• The agent files already hold the default instructions (read the MDs and the channel in full). The brief you send adds only the specifics:

``text Channel: <slug> · Video: <yyyy-mm-dd-slug> · Scene: <CODE>-<video>-s<nn> Goal: <what the viewer should take away, 1–2 lines> Specs: <resolution and fps; mp4 | full-frame card (split render) | overlay (alpha); the length comes from the window> On screen: <exact copy, numbers, what gets highlighted and when> Window: <its row in cut/insert-windows.json (a recording) or its beats in timings.json (a voiceover): start word, end word, the word that brings in each element, and how it enters and exits> Media: <user-provided paths, links, researcher output> Reference: <YouTube link or video file (+ timestamps) whose style to match, if any> Reuse: <templates and channel animations to use; what's new> ``

• When an agent returns, check that the files exist and passed QA (see Rendering), show the user the stills or render, and update the scene's status in BRIEF.md and the video's row in PROJECTS.md.

Layout