# Reelkit > Short-form video, made by your coding agent. ## What Reelkit is Reelkit is a CLI and a skill for coding agents like Claude Code and Codex. Your agent plans the video and builds it in Remotion; Reelkit handles the rest: library assets, voiceover, images, short video clips and background removal. - Some steps have quotas. `reelkit whoami` shows what you have left. - Illustrations that your plan marks as generic, and anything you add with --share, go to the shared library for review. Other people can then reuse them. - Your own files, your plan and your video stay on your machine, and so does a reference video. Three things can leave it: - A file you share with `--share` goes to the shared library. - A video you send with `--cutout` goes to the server for background removal. It is deleted there when the job ends; the transparent result is kept in your private files. - A reference video's audio, never the video, goes to the server to be transcribed. The audio is deleted when the call ends, and the transcript text is kept. With `--no-transcript` nothing is sent. The shared library holds: - Images (`--kind image`): Illustrations and pictures that fill a scene. - Overlays (`--kind overlay`): Ready-made clips such as film marks and HUD frames, laid over the video. - Sound effects (`--kind sfx`): Short sounds such as whooshes and transitions. - Music (`--kind music`): Background tracks. - Components (`--kind component`): React code for a piece of motion design. It runs on your machine when you preview or render. - Clips (`--kind clip`): Short video clips. ## Install Requirements: Node 22 or newer, ffmpeg. 1. Check the requirements Reelkit needs Node 22 or newer and ffmpeg on your path. Optional: yt-dlp, only if you give `reelkit ref download` a link rather than a file (macOS: `brew install yt-dlp`, or `pipx install yt-dlp`). ```bash node --version ffmpeg -version ``` 2. Install Reelkit This one line is the whole install. It puts the `reelkit` command on your path. With pnpm, `pnpm add -g reelkit-cli` does the same. The skill installs itself: the first time you run `reelkit init ` or log in with `reelkit auth login`, Reelkit puts it into every supported coding agent it finds on your machine. ```bash npm install -g reelkit-cli ``` 3. Log in An account is free. When you log in yourself, run `reelkit auth login`: your browser opens on the approval page, you sign in there with an email link, and the command waits while you approve. An agent cannot wait like that. It runs `reelkit auth login --start`, shows you the link it returns, with the code already in it, and then runs `reelkit auth login --finish`. ```bash # you, in a terminal: your browser opens and the command waits while you approve reelkit auth login # an agent: show the link, then finish reelkit auth login --start reelkit auth login --finish ``` 4. Start a project This creates a folder named after the project, with `plan.json`, `assets/`, `src/` and `out/`. Then ask your agent to make a video in that folder. ```bash reelkit init ``` 5. Put the skill into your agents yourself (optional) You can skip this step: the skill, and a /reelkit-video command where the agent supports one, are already in place after the steps above. Run it to install or reinstall the skill yourself. Add `--agent ` to name one agent, or `--force` to replace a copy that is up to date. ```bash reelkit install ``` If npm prints a notice about esbuild's install script, the install still worked. Reelkit installs the skill for these coding agents: | Agent | Id | Skill goes in | Command goes in | |---|---|---|---| | Claude Code | `claude` | `~/.claude/skills/reelkit` | `~/.claude/commands/reelkit-video.md` | | Codex | `codex` | `~/.codex/skills/reelkit` | `~/.codex/prompts/reelkit-video.md` | | Cursor | `cursor` | `~/.cursor/skills/reelkit` | none | | Gemini CLI | `gemini` | `~/.gemini/skills/reelkit` | none | | Shared agents folder | `agents` | `~/.agents/skills/reelkit` | none | The skill's `SKILL.md` refers to files such as `reference/kit.md`. They are installed with the skill, into the agent's skill folder, next to `SKILL.md`. They are also in `/reelkit-skill.zip`, under `reelkit/reference/`. Installing by hand: unzip `/reelkit-skill.zip`, put its `reelkit` folder at the agent's skill path from the table, and move `reelkit/command.md` to the agent's command path (`~/.claude/commands/reelkit-video.md` for Claude Code, `~/.codex/prompts/reelkit-video.md` for Codex). An agent with no command path does not use `command.md`. ## How a video gets made 1. Inputs. The agent finds out what the video is about and collects what you have. It looks at each file you give it and registers it with a description of what it shows. You can also hand it a reference video, as a link or a file: it studies the structure, the pacing, the cuts and the words, and nothing from the reference itself goes into your video. Your files and the reference stay on your machine. What can leave it: a file you share with `--share`, a video you send for background removal with `--cutout`, and the reference's audio, sent to be transcribed unless you pass `--no-transcript`. 2. Look. You and the agent agree on one visual style for the whole video: one of ten ready looks, or your own. 3. Plan. The agent writes `plan.json`: three to eight scenes, each with narration, on-screen text and a treatment. `reelkit plan check` lists what to fix. Then the agent shows you the title, the length and every scene, and waits for a clear yes. 4. Voice. The agent picks a narration voice that fits the idea and the language. `reelkit assets voiceover --all` records every scene and reports the real length of the video. 5. Images and clips. For each illustration scene the agent searches the shared library first and pulls an image that fits. Only when nothing fits does it generate one. No two scenes share an image. A scene that needs footage gets a short video clip the same way. The agent can also remove the background from a clip or from your own footage, so the subject sits over something else. 6. Composition. The agent writes the Remotion composition in `src/Video.tsx` and reuses library components and sounds where they fit. `reelkit check` must pass before anything is rendered. 7. Preview. `reelkit preview` renders two test frames per scene. The agent looks at each frame for cut-off text, low contrast and empty frames, and fixes what it finds. Then it shows you the frames and waits for a clear yes. 8. Render. `reelkit render` renders `out/video.mp4` on your machine and prints the path. ## Command reference ### Account | Command | What it does | |---|---| | `reelkit auth login` | Log in to Reelkit. Run it yourself and your browser opens on the approval page; the command waits while you approve. An agent cannot wait, so it runs `reelkit auth login --start`, shows you the one link it returns (the code is in it), and then runs `reelkit auth login --finish`. | | `reelkit auth logout` | Log out and remove the stored token. | | `reelkit whoami` | Show your account, your quota and your contributions to the library. | Flags for `reelkit auth login`: - `--start`: Begin a login and return at once with one link that has the code in it. For an agent. - `--finish`: Finish a login begun with --start. It waits up to a minute and can be run again. - `--no-browser`: Do not open the browser; print the link and code only. ### Project | Command | What it does | |---|---| | `reelkit init [name]` | Set up a video project in a new folder named after it, or in the current folder when you give no name. | | `reelkit install` | Install or reinstall the Reelkit skill in your coding agents, and a /reelkit-video command where the agent supports one. Optional: `reelkit init` and `reelkit auth login` do it on their own. | Flags for `reelkit init`: - `--aspect `: The shape of the video: 9:16, 16:9 or 1:1. Flags for `reelkit install`: - `--agent `: Install for one agent: claude, codex, cursor, gemini or agents, or all. The default is every agent found on your machine. - `--force`: Reinstall even when the installed copy is up to date. ### References | Command | What it does | |---|---| | `reelkit ref download ` | Bring an existing video into the project as a reference, at most 10 minutes long. A link is downloaded on your machine with yt-dlp; a file is copied and needs nothing extra. The reference is saved under `refs//` and stays on your machine. | | `reelkit ref audio ` | Save the reference's audio as `refs//audio.mp3`, on your machine. Nothing is sent. | | `reelkit ref analyze ` | Measure how the reference is built and write `refs//breakdown.json`: the scenes (up to 40) with two sample frames each, the cuts and the pacing, the colours, the loudness, the tempo and the beats. All of that runs on your machine. For the transcript, the audio, never the video, is sent to the Reelkit server: the audio is deleted when the call ends, and the transcript text is kept. Transcription is counted in whole seconds against a monthly quota. | | `reelkit ref list` | List the references in this project, and which of them are analysed. | Flags for `reelkit ref download`: - `--redo`: Download a link again even if it is already in the project. Flags for `reelkit ref analyze`: - `--no-transcript`: Do not send the audio to the Reelkit server. Everything else is measured as usual, on your machine. - `--redo`: Measure again even if a breakdown exists. The audio is transcribed again too, and counts against the quota again. ### Assets | Command | What it does | |---|---| | `reelkit assets upload ` | Add one of your own files to this project. It stays on your machine and private unless you pass `--share`; with `--cutout` the video is uploaded to the Reelkit server to be processed. | | `reelkit assets search ` | Search the shared library by meaning. Each result shows how well it fits. | | `reelkit assets pull ` | Download a library item into this project. A component lands in `src/` and the command prints how to import it. | | `reelkit assets voices` | List the narration voices. | | `reelkit assets voiceover` | Record the narration from `plan.json`. | | `reelkit assets gen image [prompt] --scene ` | Generate one scene's illustration. It needs --scene. The prompt is optional and defaults to the one in the plan. | | `reelkit assets gen clip [prompt] --scene ` | Generate a short video clip for one scene: B-roll, or with --green a subject on green that is keyed out into a transparent clip, or with --cutout a normal clip whose background is then removed on the server. It needs --scene and takes minutes. Search the library first with --kind clip. | Flags for `reelkit assets upload`: - `--describe `: What the file shows. - `--footage`: Use this video as the footage to lay the motion design over. - `--green`: For a video of a subject on a green background: keeps the original and writes a copy with the green made transparent. Free, and it runs on your machine: nothing is uploaded. A green too dull to key is refused, and the command points to `--cutout`. - `--cutout`: Removes any background. This uploads the video to the Reelkit server, which removes the background and returns a transparent `.webm` that is saved beside the original. The upload is deleted when the job ends; the transparent result is kept in your private files on the server and shows on your account page. Up to 20 seconds a video, counted in whole seconds against a monthly quota, only when it succeeds. - `--resume `: With `--cutout`: keep waiting for a cutout that was already started. It does not upload the video or count against your quota again. - `--share`: Also send the file to the shared library. - `--kind `: The library kind, when sharing. - `--tags `: Comma-separated tags, when sharing. Flags for `reelkit assets search`: - `--kind `: Limit the search to image, overlay, sfx, music, component or clip. - `--limit `: How many results to return. Flags for `reelkit assets pull`: - `--scene `: Use the item as this scene's image or clip. - `--force`: Replace a component file that already exists. Flags for `reelkit assets voiceover`: - `--scene `: Record one scene. - `--all`: Record every scene. - `--redo`: Record again even if a recording exists. Flags for `reelkit assets gen image`: - `--scene `: Required. The scene the image is for. - `--redo`: Generate a new image even if the scene has one. Flags for `reelkit assets gen clip`: - `--scene `: Required. The scene the clip is for. - `--green`: Film the subject on green and key the green out into a transparent `.webm`. The keying is free and runs on your machine. When the generated green is too dull to key, the subject is cut out on the server instead: the command says so, and it uses seconds of the background-removal quota. - `--cutout`: Generate the clip as usual, then remove its background: the clip is uploaded to the Reelkit server and a transparent `.webm` comes back. The upload is deleted when the job ends; the result is kept in your private files. It also counts against the monthly background-removal quota. - `--seconds `: The length of the clip: 5 or 10 seconds. The default is 5. - `--share`: Also send the clip to the shared library, for review. Only for a generic clip. - `--redo`: Generate a new clip even if the scene has one. - `--resume `: Keep waiting for a clip that was already started. It does not count against your quota again. ### Build | Command | What it does | |---|---| | `reelkit plan check` | Validate `plan.json` and list what to fix or improve. A plan that names a reference needs that reference analysed first, and the check says when its scenes are much slower or faster than the reference's shots. | | `reelkit check` | Check the composition in `src/` without rendering it. | | `reelkit preview` | Render two test frames per scene into `out/preview/`. | | `reelkit render` | Render the video to `out/video.mp4`. | ### Flag on every command - `--json`: Print the result as JSON. Every command accepts it, and a failure exits non-zero with a one-line reason. ## Recipes ### A first video from an idea The sequence an agent runs: log in, set up a project, plan, record, compose, check and render. If you log in by hand, run `reelkit auth login` instead of the first three lines. ```bash reelkit auth login --start # show the person the link, and wait for them to approve reelkit auth login --finish reelkit init my-video --aspect 9:16 cd my-video # write plan.json reelkit plan check reelkit assets voices reelkit assets voiceover --all reelkit assets search "city skyline at night" --kind image reelkit assets pull --scene intro # write src/Video.tsx reelkit check reelkit preview reelkit render ``` ### An app demo from screenshots Register your real screenshots, list them in the plan and build the demo around them. Never generate app UI. ```bash reelkit init app-demo --aspect 9:16 cd app-demo reelkit assets upload ./home.png --describe "Home screen with the weekly summary" reelkit assets upload ./checkout.png --describe "Checkout screen after choosing a plan" # write plan.json and list the uploaded ids in each scene's userAssetIds reelkit plan check reelkit assets voiceover --all # write src/Video.tsx reelkit check reelkit preview reelkit render ``` ### Make one like this Give the agent a video you like and it builds a new one with the same structure and pacing. You need the right to download any video you point it at, and downloading from some platforms can be against their terms; a file already on your machine is the simplest path. Reelkit takes structure and pacing from a reference, never its footage or music. ```bash reelkit init like-this --aspect 9:16 cd like-this reelkit ref download ./example.mp4 # a link works in place of the file; it needs yt-dlp # ask the person first: the next line sends the reference's audio to Reelkit to be transcribed reelkit ref analyze # look at the frames in refs//frames/ and read refs//breakdown.json # write plan.json, with the reference's id and what you took from it in its reference field reelkit plan check reelkit assets voiceover --all # write src/Video.tsx reelkit check reelkit preview reelkit render ``` ### Reuse a library sound and component Search the shared library before writing anything new, then pull what fits into the project. ```bash reelkit assets search "whoosh" --kind sfx reelkit assets pull reelkit assets search "animated counter" --kind component reelkit assets pull reelkit check ``` ### Change the script and re-record Edit the narration in `plan.json`, validate it and record the changed scene again. ```bash # edit the scene's narration in plan.json reelkit plan check reelkit assets voiceover --scene intro --redo reelkit check reelkit preview reelkit render ``` ## The skill (SKILL.md) The `reference/*.md` files it names are installed with it, and are in `/reelkit-skill.zip`. --- name: reelkit description: Produce short-form and explainer videos from an idea plus the user's own screenshots, logo, clips or footage. Searches a shared asset library first, generates only what is missing, and renders locally with Remotion. Use when the user wants to create, edit or assemble a video, turn an app or idea into a demo, or make a promo. --- # Reelkit You make the video. The `reelkit` CLI gives you the tools: it holds no model and makes no creative decisions. You write the plan and the motion code yourself, check them with the CLI, and show the user your work at two checkpoints before anything is rendered. Every command takes `--json` for machine-readable output and exits non-zero with a one-line reason when something is wrong. Read the reason and act on it. ## Setup (once per machine, then once per video) 1. `reelkit whoami`. If it says you are not logged in, run `reelkit auth login --start` (it returns at once and never opens a browser; plain `reelkit auth login` would wait for a person and block you). Show the user the link it prints (the code is already in it) and wait for them to say they have approved it, then run `reelkit auth login --finish`. If that says it is not approved yet, ask the user again and re-run it. (Plain `reelkit auth login` opens a browser on the user's machine when run in a terminal; `--no-browser` stops that. Still prefer `--start`.) 2. Run `reelkit init --aspect 9:16` (`16:9` or `1:1` for other shapes), then work in the folder it prints. The folder holds everything: `plan.json`, `assets/`, `src/` (your composition and any components you pull), `out/`. ## The loop ### 1. Inputs Find out what the video is about and collect what the user has. Ask for nothing you can infer. For each file the user gives, look at it, then register it with a description of what it shows: `reelkit assets upload ./logo.png --describe "Acme logo, white wordmark on blue"` Add `--footage` for a video the motion design should be laid over. User files stay on this machine. A video of someone or something on a plain background can be made transparent: `--green` keys a green background locally for free, and `--cutout` removes any background on the server (the video is sent to Reelkit, so ask first; see `reference/clips.md`). If the user points at an existing video ("make one like this", a link or a file), it is a reference: you learn how it is built and make something new in that spirit. Read `reference/references.md`, then `reelkit ref download ` and `reelkit ref analyze `, and look at the frames it saves. Take its structure, pace and motion; never its footage, music or words. A link is fetched on the user's machine and they are responsible for the right to download it; ask before running `reelkit ref analyze` without `--no-transcript`, because the audio (never the video) is sent to Reelkit to be transcribed. ### 2. Look Read `reference/styles.md` and agree the video's look with the user: one of its looks, or their own. If they already described what they want, match it and confirm in one sentence. Ask anything still open in one message, each question with a default. If any on-screen text will be Hebrew, read `reference/hebrew-rtl.md` now: it changes how words may enter and how lines are written. ### 3. Plan Read `reference/scriptwriting.md` and `reference/scene-treatments.md` (and `reference/clips.md` if any scene might be a video clip). Write the chosen look into the first scene's `notes`. Run `reelkit assets voices` and choose a voice that fits the idea, audience and language. Write `plan.json`: ```json { "title": "string", "aspect": "9:16", "mode": "motion", "voiceId": "an id from reelkit assets voices", "pace": "normal", "scenes": [ { "id": "hook", "narration": "the words spoken in this scene", "treatment": "motion-graphic", "onScreenText": ["up to three short items"], "imagePrompt": null, "clipPrompt": null, "shareable": false, "imageTags": [], "userAssetIds": [], "notes": "visual direction for yourself when you write the code" } ] } ``` - 3 to 8 scenes. Scene ids are short, unique, lowercase with dashes. - `treatment` is `motion-graphic`, `illustration`, `clip` or `footage-overlay`. With footage, `mode` is `"footage"` and every scene is `footage-overlay`; otherwise `mode` is `"motion"` and no scene is. - `imagePrompt` is set only for `illustration` scenes, with 3 to 6 `imageTags`. Set `shareable` to true only when the prompt is fully generic: no brand, product, person or detail specific to this user. - `clipPrompt` is set only for `clip` scenes (a generated or reused video clip is the scene's picture; the rest of the scene uses `imageTags` and `shareable` as an illustration does). Clips are scarce: most videos have none or one or two. - `userAssetIds` lists the ids of the user's files shown in that scene. - `pace` is `slow`, `normal` or `fast`. - When the video follows a reference, add `"reference": { "id": "", "take": ["fast cuts every ~1.2s"] }` (1 to 6 notes on what you took). Run `reelkit plan check`; it prints the estimated length to tell the user. Fix everything under "Fix these". Act on "Worth improving" unless you have a good reason not to. **Checkpoint.** Show the user the look, the title, the estimated length, and each scene's narration, the exact on-screen text and one line on the visual, in plain words about what they will see. Wait for a clear yes. A question or a comment is not approval: answer it and ask again. ### 4. Voice `reelkit assets voiceover --all`. It records each scene and prints the real length of the video. If the user wants a different voice, change `voiceId` in `plan.json` and run it again with `--redo`. ### 5. Images and clips Read `reference/asset-reuse.md`. For each illustration scene, search first: `reelkit assets search "" --kind image` Each result starts with a match percentage: how likely it is good enough to reuse. Pull the best result (`reelkit assets pull --scene `) when its match is 60% or more and, reading its description, it fits the scene. Otherwise generate: `reelkit assets gen image --scene `. Never give two scenes the same image. For each clip scene, read `reference/clips.md`, then search `reelkit assets search "" --kind clip` and pull a 60% match (`reelkit assets pull --scene `), or generate: `reelkit assets gen clip --scene ` (add `--green` for a green-screen subject). It waits for the clip, which takes minutes; check what is left with `reelkit whoami`. ### 6. Composition Read `reference/kit.md`, `reference/remotion-composition.md`, `reference/motion-design.md` and `reference/captions.md`. - Search the library before writing a component: `reelkit assets search "" --kind component`. To use one, `reelkit assets pull `: it lands in `src/` and the command prints the import line and an example. - Read `reference/sound-design.md`, then find the few sounds the video needs: `reelkit assets search "whoosh" --kind sfx`, `reelkit assets pull `. The pull prints how to reference the file. - Before writing a new component, read `reference/component-authoring.md`. - Write `src/Video.tsx` and any component files beside it. `Video.tsx` may import only `react`, `remotion`, `reelkit/kit` and sibling components (`./Name`). - `manifest.json` is the exact object passed to `Video` as the `manifest` prop. Media is referenced as `urls[path]`, where `path` is the file's path in the project, such as `urls[scene.voiceoverKey]` or `urls["assets/lib//clip.mp3"]`. Run `reelkit check` and fix every error until it passes. Then `reelkit preview` (the first preview on a machine downloads a browser once and can take a minute) and look at every frame in `out/preview/`: each scene has two, `early` (30% into the scene) and `late` (90%), so look at both frames of each scene. Look for: text cut off or overflowing, text overlapping other text or the captions, text too small or too low-contrast for a phone, an empty or broken frame, content hidden behind another layer, and any number, price or quote on screen that is not in the plan. A frame is one moment: an element mid-animation is not a problem, but anything that should be fully on screen by the late frame and is not is. Fix real problems and preview again. Go round at least twice, and finish with the studio test in `reference/motion-design.md`. You only ever see frames, never the moving video, so the frames are your eyes: look at every one. And whoever built a video is the worst judge of it. If you can start a separate agent, give it only the user's original request and the preview frames (not your explanations) and ask for a score out of 100 per scene, a list of flaws, and a concrete fix for each, in numbers ("raise the title 60 px", "hold the label 0.4 s longer"). Fix, preview, and have the same reviewer look again until every scene passes 90. If two rounds leave a scene under 70, stop and show the user the gap instead of spending more rounds. **Checkpoint.** Show the user the preview frames (both of each scene). Wait for a clear yes. For changes, edit the code, `reelkit check`, `reelkit preview`, and show them again. ### 7. Render `reelkit render`. Give the user the path it prints. If the render fails, read the error, fix the composition, and run `reelkit check` before rendering again. ## Rules - Search before generating. Reuse beats regenerate. - Never generate app UI. Use the user's real screenshots. - The user's own files are private. Do not pass `--share` unless they ask you to contribute a file. - Pass the user's facts through unchanged. Never invent a number, statistic, price or quote. - Keep components driven by props, not hardcoded, so they can be reused. - One stage at a time. Do not write composition code before the user has approved the plan, and do not render before they have approved the preview. - Never say a video is done without having looked at its frames and checked that the file exists. - If a command reports that a quota is used up, tell the user what ran out and when it resets. Do not work around it. A message that says to wait a minute or an hour ("Too many searches", "Too many uploads started") is a throttle, not a used-up quota: wait and retry once instead of stopping. - Reply in the user's language.