video-spec-builder interviews you until you can describe a shot, then hands the file to someone else's renderer

The interview is the deliverable, the renderer belongs to someone else

The division of labour is stated plainly. This skill sits upstream and turns an idea into a script. A second skill, HyperFrames, sits downstream and turns the script into video. The output of the first is a Markdown file called video-spec.md, described as a shot by shot script, timed to the second, with every shot written out. The project is emphatic about the limit of its own offer: it will not shoot the video for you and it will not invent the idea, and it does one thing, which is to push you until the idea is something you can actually build. The workflow diagram in the readme shows the two stages stacked with the script file between them, and the text notes that you want both skills installed before you start rather than discovering the missing half at render time.

The ceiling is whatever HTML can draw

Before you write a single shot, the readme sets out what the renderer can and cannot do, on the grounds that this decides whether a script is worth the paper it is printed on. The renderer turns video from HTML, and that one fact is the root of everything: if HTML, CSS and code can draw it, it becomes video, and if HTML cannot draw it, neither can the pipeline. It is described as clean at text and layout work, covering title animation, captions, word by word highlighting, page layout, transitions, charts, user interface mockups and geometric animation. It cannot produce illustrations, so hand drawn characters, painterly visuals and cartoon figures are out, and writing code will not get you there. It cannot conjure live action or photorealistic images. It can synthesise a voiceover as a stopgap with an obvious machine tone. It will not compose background music.

It refuses the words premium and high-impact

The questioning has one rule that makes it different from a template. It refuses vague adjectives, naming premium and high-impact as examples, and keeps after you until you can describe real shots and real motion. Anywhere you go vague or skip something, it stops and pushes you to fill it in. Answer vaguely and it digs; miss something and it fills it in rather than leaving a hole. The readme names three situations where that earns its keep: you know the feeling but cannot describe the picture, you have an opening and an ending but never thought about the middle, and you have plenty of raw material with no order for it, whether that is a script, selling points or a pile of assets. In each case the output is the same artefact, and the point is that the artefact is written down shot by shot rather than held in someone's head.

The order of the interview is written down

The sequence is described as a real conversation rather than a form. It starts by pinning the basics: who the video is for, where it is going, how long it runs and the core message. Then it takes stock of the material you already have. Then it settles style and pacing and picks a visual theme. Last it calibrates, and the calibration step uses reference videos and counter examples. That last step is worth pausing on, because it sets an expectation the renderer cannot meet. The renderer cannot produce live action footage or photorealistic images, so reference videos are there to fix tone, pacing and structure rather than to be reused as material. Anyone arriving at this step expecting to hand over a clip and get it back inside the video is asking for something the downstream half will refuse.

Two install commands, and one flag that decides the scope

Installation goes through an external skills command, once for each half of the pipeline:

npx skills add heygen-com/hyperframes
npx skills add feicaiclub/video-spec-builder

Each command installs once and covers Codex, Claude Code, Cursor and the rest, so there is no per tool installation. Two scopes exist and the default is the narrower one: without a flag the skill installs into the current folder and only works in the project where you ran the command, while a global flag makes it available everywhere, which is the sensible choice if you make videos often.

npx skills add feicaiclub/video-spec-builder -g

There is nothing else to configure, since the launcher fetches a copy just to run it and leaves nothing behind, and the only stated requirement is Node 18 or newer. The author says the skill is used mostly in Codex and then Claude Code, and those are named as the two setups it works best in.

Editing one shot means checking whether the others moved

The second mode is for a script that already exists. With a video spec file in the project you say what you want in plain language, for example that shot three is too fast and the background music should be quieter. It then checks what you are actually after, looks at whether the change touches other shots, and updates the script. That dependency check is the part with substance in it, because a spec is timed to the second, so slowing one shot moves every boundary after it. Rendering is triggered with a slash command for the downstream skill, and in Claude Code the upstream one can also be called directly by name rather than only by talking to it. Neither path is scripted in a terminal: the whole surface is conversation inside the agent.

A repository of Markdown with no manifest and a directory called Full Code

The tracked root holds a licence, an English readme with a Chinese translation beside it, the skill definition file, and four directories for examples, references, templates and something called spec mono, whose purpose the visible text never explains. One worked example is checked in, a spec written for a space launch. There is also a top level directory whose name is two words with a space in it, which is an unusual thing to find in a repository root and suggests a dump rather than a package. No package manifest and no source directory appear at the root, and there are no tagged releases, yet the language detector reports JavaScript, so the classification is coming from somewhere other than the visible layout. The install path does not build anything locally either, it delegates to an external command. This is a prompt and template repository, and the artefact that matters is the skill file.

Editorial conclusion

Use it when the blocker is that you cannot articulate what you want, because that is the one job it does and it refuses to paper over the gap with adjectives. Skip it if you already have a script, since the editing mode exists but the value is all upstream of it. Two things to settle before you start. You need the downstream renderer installed as well, because this skill stops at the file, and the file is only as good as a renderer that draws from HTML, which rules out illustration, live action and photorealistic imagery before you write a word. And decide the install scope deliberately, since the default lands the skill in one project folder and the global flag puts it everywhere.

Frequently asked questions

Official sources

1. feicaiclub/video-spec-builder on GitHub
2. Issues
3. License: MIT
4. README