A skill that interrogates a fuzzy video idea until it becomes a script

A director in skill form, aimed at the actual hard part

video-spec-builder is a Claude Code, Codex and Cursor skill built on a specific observation about making a video: the hard part is rarely the rendering, it is figuring out exactly what you want before anyone can render anything. The author states that plainly as the project's origin, and the skill is built entirely around closing that gap. Tell it "I want to make a video," and rather than attempting to produce something immediately, it takes over the conversation the way a director would, asking who the video is for, how long it runs, what single line the viewer should walk away with, and which shot is actually carrying the weight of the idea.

The skill's own description of its scope is unusually precise for a creative tool: it will not shoot the video and it will not invent the idea for you. What it does is push and stay with you until a fuzzy idea becomes something concrete enough to actually build. That is a narrower and more honest claim than most AI creative tools make, and it matches the actual output: not a video, but a structured shot-by-shot script, timed to the second, ready to hand to a separate rendering skill.

Refusing vague words until they become real shots

The clearest illustration of how the skill works is what the README says it does when a user reaches for a word like premium or high-impact: it refuses to accept the word as a description and keeps asking until the user can describe an actual shot, actual motion, something concrete enough to put on screen. That is the correct response to exactly the kind of language that feels like a creative direction but gives a renderer nothing to act on, since no rendering step, human or automated, can turn premium into a specific camera move or a specific piece of on-screen text.

The same interrogation style is applied to structural gaps rather than only vague adjectives. If a user has a strong opening and ending but never thought through the middle, or never considered that a section could use captions or that visuals could cut to the beat of a music track, the skill is described as raising those possibilities rather than silently leaving the gap for the user to discover later during rendering, when fixing it costs more. Pushing on both vocabulary and structure, rather than only one, is what separates a genuine director's brief from a form with blanks to fill in.

Two skills with a hard boundary between them

The project is explicit that it is only the upstream half of a two-skill pipeline. video-spec-builder turns a conversation into a structured script file; a separate, downstream skill called HyperFrames turns that script into an actual rendered video. The two are installed separately and used in sequence, and the README states directly that a prospective user needs both installed before starting, since a finished specification with nothing to render it is only half the workflow.

Keeping the interrogation-and-writing skill and the rendering skill as two separate, independently installable pieces rather than one fused tool is a sound architectural choice. The two are genuinely different disciplines, one is closer to conversational interviewing and structured writing, the other is closer to a rendering engine, and separating them means either half can be improved, replaced or used independently without disturbing the other. It also means the specification format itself, the plain markdown script the first skill produces, is the actual interface between the two, legible and editable by a human at any point in the process rather than trapped inside one opaque tool.

An honest limit stated up front: HyperFrames renders from HTML

The README does something genuinely useful for anyone about to invest a conversation's worth of effort into a detailed script: it states the rendering engine's core constraint before you start, rather than letting you discover it only after the script is finished and rendering fails. HyperFrames renders video from HTML, and that single fact is described as the root of everything the renderer can and cannot do. Whatever HTML, CSS and code can draw, it can render into video; whatever those cannot draw, it cannot render either.

That is a meaningful and specific boundary rather than a vague disclaimer, and it changes what a user should actually write into their script. Text animation, layout work, and anything expressible as a web page's visual language sit comfortably inside what the renderer is built for. A shot that depends on live-action footage, physical camera work, or visual complexity beyond what HTML and CSS can express is not something this pipeline was built to produce, and knowing that before spending an hour in the interrogation-driven scripting conversation is worth far more than discovering it at the rendering step.

Installing both skills, and the scope decision worth making deliberately

Installation for both the renderer and the spec-builder goes through the same skills package manager, one command each, and each command covers every supported agent at once rather than needing a separate install per tool:

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

The default install scope is project-level, meaning the skill only activates inside the project directory where the install command was run, and the README offers a global flag for anyone making videos often enough to want the skill available everywhere without reinstalling per project:

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

Choosing project-level by default is the more conservative and generally correct choice for a skill package manager, since it means a skill installed for one specific video project does not silently become active inside every other unrelated project on the same machine. A user who makes videos often enough to want it everywhere has to make that choice deliberately with the global flag, rather than it being the default a casual first-time user has to opt out of.

What to weigh before adopting it

The project also supports iterating on an existing script rather than only starting from scratch: telling it a specific change, such as slowing down one shot or swapping the background music, triggers a check for whether that change would affect other shots before the script file is actually updated, which is the same discipline a careful human editor would apply rather than making an isolated edit that quietly breaks continuity elsewhere in the script.

The project is MIT licensed, permissive and allowing commercial use, and reports 976 stars, 119 forks and three open issues, with the last push on 2026-05-18. The README states the author's own primary usage is inside Codex, with Claude Code as the secondary environment, which is worth knowing if you plan to use it inside Cursor or another supported agent, since the most battle-tested experience is specifically in those first two.

Before adopting it, three steps in order. Install both skills together, since a finished specification with no renderer to hand it to accomplishes nothing on its own. Decide between project-level and global installation deliberately based on how often you actually make videos, rather than defaulting to global out of convenience. And read the HTML-rendering constraint before investing a full scripting conversation into a video concept that depends on visual complexity a web page cannot express, since that single fact determines whether the finished script will actually be renderable at all.

Editorial conclusion

video-spec-builder fits anyone who has a video idea but cannot yet describe it in concrete shots, and its refusal to accept vague adjectives or leave structural gaps unaddressed is a genuinely useful discipline applied to a step most creative tools skip entirely. Splitting the conversational scripting work from the HyperFrames renderer keeps the two disciplines separate and the resulting video-spec.md legible and editable on its own, and stating plainly that the renderer can only draw what HTML and CSS can express is the kind of upfront honesty that saves a full scripting conversation from ending in a video that cannot actually be rendered. Install both skills together before starting, choose project-level or global installation based on how often you actually make videos, and keep the HTML-rendering constraint in mind while scripting so the finished specification is one HyperFrames can actually turn into a video.

Frequently asked questions

Official sources

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