Remotion Skill for Claude Code: Finished Shorts From One JSON File, Checked Before Render

Remotion skill for Claude Code, open source and MIT licensed: Remotion Shorts Skill lets your agent turn a topic, an article, a dataset or a changelog into a finished vertical short for TikTok, Instagram Reels and YouTube Shorts. It also works in Codex, Cursor and OpenClaw.

The agent writes one JSON file of scenes. A bundled Remotion project lays out every word, times every scene, renders review sheets and then the MP4, and the agent can post it after you say yes. This post covers how to use it, then the parts that are code: how text is fitted, how timing is decided, and how the skill checks its own output before you see it.

npx skills add social-media-skills/remotion-shorts-skill -g -a claude-code -y

Repo: github.com/social-media-skills/remotion-shorts-skill

Frames from the two examples in the repo. Figures in the water short come from the USGS Water Science School; the Earth image is NASA's Blue Marble 2012. Both scripts were written by an AI agent with the skill; no endorsement by USGS or NASA is implied.

What is a Remotion skill?

A Remotion skill is an agent skill (a folder with a SKILL.md and supporting files) that tells a coding agent like Claude Code how to make video with Remotion, the React framework for programmatic video. Most Remotion skills teach the agent to write Remotion components.

This one works the other way round. The Remotion project is already written and tested, and the agent only writes the script. You get one job done well: kinetic-text shorts (big animated words, stat count-ups, top-N lists, quotes, launch and changelog videos) at 1080x1920.

How to use Remotion with Claude Code, step by step

1. Install the skill with the command above. Other agents: run npx skills add social-media-skills/remotion-shorts-skill and pick yours, or openclaw skills install @social-media-skills/remotion-shorts-skill.
2. Ask for a short. "Make a short about how much of Earth's water is fresh. Use real numbers." or "Turn this changelog into a TikTok."
3. First run only: the agent runs setup.mjs, which copies the Remotion project, installs pinned packages and downloads the headless browser Remotion renders with (1 to 3 minutes).
4. The agent writes short.json and runs node render.mjs short.json --stills to get review sheets in a few seconds.
5. You look at the sheets, ask for changes, then say "render it". You get an MP4, a cover frame and captions per app.
6. Posting is optional. The agent shows you the accounts, captions and privacy settings and posts only after a clear yes.

Here is the exchange from the water example in the README, shortened:

You:   Make a short about how much of Earth's water is fresh. Use real numbers. Ocean colours.
Agent: Using the USGS Water Science School figures. Review sheets are ready: 8 scenes, 22.3 seconds, no warnings.
You:   Looks good. Render it.

Why a template, not generated Remotion code

Coding agents can write Remotion components from scratch, and for a one-off motion piece that is the right approach. For shorts posted every week it causes problems. Each video is new code, so each video can have new bugs. Nothing checks that text stays out from under the app's buttons. And nobody decides how long a scene should stay up, so the timing is whatever the agent guessed.

This skill splits the job. The Remotion project is fixed: six scene types (hook, text, stat, item, quote, end), five themes and a layout engine. The agent writes only the script:

{
  "theme": "ocean",
  "footer": "Data: USGS. Earth image: NASA",
  "scenes": [
    { "type": "hook", "big": "2.5%", "text": "of Earth's water is fresh", "image": "earth.jpg" },
    { "type": "stat", "value": "96.5", "suffix": "%", "label": "is salt water in the oceans" },
    { "type": "stat", "value": "68.7", "suffix": "%", "label": "of the fresh water is locked in ice and glaciers", "highlight": "ice and glaciers" },
    { "type": "end", "text": "Save this for trivia night", "highlight": "Save this" }
  ]
}

The agent's effort goes into what each screen says, which is the part that decides whether people keep watching.

One safe zone for TikTok, Reels and Shorts

TikTok, Reels and Shorts all draw on top of the video: search and tabs at the top, the caption, username and music line at the bottom, like and share buttons on the right. Text under any of them is lost.

Only Meta publishes numbers (keep the top 14%, the bottom 35% and 6% on each side clear). TikTok ships overlay files and YouTube shows its safe area as an image. The template takes the strictest edge of the three on a 1080x1920 frame:

// src/theme.ts
export const SAFE = { top: 288, bottom: 672, left: 96, right: 192 };

That leaves 792x960 pixels for text. Centred text uses 192 px on both sides so it sits on the frame's centre line. Photos and backgrounds still fill the frame; only text stays inside.

Fitting text: the biggest size with balanced lines

calculateMetadata runs in the headless browser before any frame renders, so it can measure text with the real fonts. measureText from @remotion/layout-utils measures every word once at 100 px; widths then scale linearly, and the layout searches sizes from the scene's maximum down to a readable floor.

The biggest size that fits is not always the best. A seven-word hook at maximum size can come out as four lines with one word stranded on the last. So each candidate (a size plus a line count) gets a cost:

// src/layout.ts
const lonely = words.length > 2 ? lines.filter((l) => l.length === 1).length * 0.2 : 0;
const widow = lines.length > 1 && lines[lines.length - 1].length === 1 && words.length > 2 ? 0.1 : 0;
const cost = (max - size) / max + 0.3 * Math.max(0, lines.length - 3) + lonely + widow + 0.05 * ragged;

Bigger is better, more than 3 lines costs extra, a one-word line costs extra (more so on the last line), and ragged penalises lines of very different length. For each line count it binary-searches the narrowest measure that still gives that many lines, which balances them. Three details keep text inside the box:

• Highlight boxes have width. A highlighted run gets a coloured block that overhangs the letters, so its edge words are measured 0.12 em wider on each side.
• The punch has width. When the key word lands, the block springs to 1.04x around the centre of the safe box. Layout fits to the safe width divided by 1.04, so the punch never pushes a letter out.
• Numbers are measured as drawn. A stat like 96.5% sets the suffix at 0.62 em and the digits with tabular-nums, so the measurement uses the same parts.

A single word too wide for the screen at the smallest size is an error, not a warning. --force can override warnings but never puts text off screen.

Timing: how long each scene stays on screen

Each scene stays up long enough to read, and no longer:

const CPS = 17;        // characters per second
const PER_WORD = 0.3;  // seconds per word
const read = (s) => Math.max(s.length / CPS, countWords(s) * PER_WORD);
const needed = ENTRY + 0.4 * reveal + hold;

The numbers come from subtitle practice: BBC guidance of about 0.33 seconds per word and Netflix's 17 to 20 characters per second for adults, slightly faster here because the text is the whole picture. People read while the words rise into place, so only 40% of the reveal time is added on top. Stats get time for the count; the small line under a list item counts at 60%, because it is skimmed.

In practice a hook lands in 2 to 3 seconds, a stat in 2.5 to 4 and a list item in 2 to 3. The water example is 8 scenes in 22 seconds. With a bpm, every cut moves to the next beat, never an earlier one, so snapping cannot cut a scene short of its reading time.

Frame 0 is the thumbnail

TikTok and Reels show frame 0 in the profile grid, and it is the first thing a scroller sees. So the first scene is fully set on frame 0, and only the highlight wipe and the punch move after it. Every later scene starts already moving, so no cut lands on an empty frame.

Words rise from behind a mask instead of fading, so no frame shows grey, half-transparent text. The highlighted run is drawn twice: the normal colour underneath and the accent-text colour on top, clipped by the same edge as the wiping block, so the text is readable at every frame of the wipe.

Review sheets before the render

node render.mjs short.json --stills runs in a few seconds and writes:

• sheet.jpg: the last frame of every scene, with the safe area marked by a thin dashed line;
• cuts.jpg: frame 0 and the frames around every cut;
• cover.jpg: the hook once it has landed;
• report.json: the plan, line breaks and warnings.

The agent opens both sheets before rendering the video. Warnings stop the render with exit code 2: text too long for one screen, a hook over about 10 words, a highlight that is not in the text, a scene too fast to read, a short over 59 seconds (YouTube blocks Shorts over a minute worldwide if any copyright claim lands on them).

The sheets are Remotion compositions too: a grid of <Short> instances, each inside <Freeze frame={n}>. One gotcha if you build something similar: the sheet composition needs the same durationInFrames as the short, or frames past its length are clamped and every tile shows frame 0.

Sound without licensing problems

Silent text videos tend to look like low-effort templates, but music from a free library is a licensing risk on at least one of the three apps. The template ships its own sound effects, generated with ffmpeg's signal generators (no samples, no recordings): a low hit on the hook, a whoosh on each cut, a pop when a highlight lands and ticks under a count-up. They are MIT like the rest of the repo, on by default, and placed from the same timing the motion uses.

Rendering on ordinary laptops

The output is 1080x1920, 30 fps, H.264, yuv420p, BT.709, AAC with the moov atom at the front: a format all three apps accept. Machines with 8 GB of memory render 2 frames at a time; --concurrency 1 is there if a render is still killed. A 20-second short renders in under a minute on a recent laptop.

Setup is one command: node scripts/setup.mjs copies the project, installs pinned packages (Remotion 4.0.536) and downloads Chrome Headless Shell. Run it again after the skill updates and it refreshes the template, keeping a .bak of anything you changed. CI sets up a fresh project and renders both examples on macOS, Windows and Ubuntu.

Posting to TikTok, Reels and Shorts

Posting is optional and goes through WoopSocial, a social media API and MCP server for agents. Disclosure: the skill is maintained by Frank Heijdenrijk and the team behind WoopSocial. Setup for every agent is at woopsocial.com/agents.

upload.mjs sends the MP4 in parts with retries; the agent reads the TikTok account's allowed privacy settings, writes a caption per app, validates the post and posts only after a clear yes. Posting to several accounts, it makes a different version for each one, because Instagram stops recommending near-duplicate posts and YouTube treats mass-produced templated videos as inauthentic content. If you would rather not connect anything, you get the MP4 and the captions to post yourself.

FAQ

Do I need to know Remotion to use this skill?

No. The templates are done and the agent writes a JSON file. If you want to change the design, the project is a normal Remotion project: run npm run studio and edit src/Short.tsx.

Can Claude Code make videos with Remotion?

Yes. Claude Code can run commands on your machine, so with this skill it writes the script, runs the checks and renders the MP4 locally with Node. Rendering needs no paid API.

Does the skill edit existing video?

No. It makes new text-led shorts. You can put a photo or video behind any scene or the whole short; it is dimmed under the theme colour so the text stays readable.

Does it work in Codex, Cursor and OpenClaw?

Yes, any agent that can run commands on your computer. It needs Node 20+ and macOS 15+, Windows x64 or Linux with glibc 2.35+ (Remotion's own requirements).

Is Remotion free for commercial use?

The skill is MIT. Remotion has its own licence: free for individuals, non-profits and companies of up to 3 people; larger companies need a Remotion company licence, and rendering from scripts counts as automation. The skill says so before the first render. Current terms: remotion.pro/license.

Try the Remotion Shorts Skill

npx skills add social-media-skills/remotion-shorts-skill -g -a claude-code -y

Then ask your agent for a short about something you know well. Repo, both examples with their review sheets, and every rule with its source: github.com/social-media-skills/remotion-shorts-skill. Issues and pull requests are welcome.

More free skills from the same team at social-media-skills.com.