story-new

Turn a context into a finished narrated video.

Arguments

Parse $ARGUMENTS as: slug context seconds orientation

• $0 = slug, lowercase and hyphenated, e.g. big-bull. Becomes the folder

under public/ and, in PascalCase, the composition id

• $1 = context: a file path, a URL already fetched, or the text itself
• $2 = length in seconds. Default 60
• $3 = landscape or vertical. Default landscape

If no arguments, ask what the video is about, how long it should be, and where it will be published.

Instructions

1. Check the pipeline is present, since the skills can be installed without it:

``bash test -f cli/generate.ts && test -f src/Root.tsx && echo present || echo missing ``

If missing, run the story-setup skill first. It fetches the project, installs dependencies, creates .env and verifies the keys. Everything below runs from the project root.

1. Read the story-telling rules before writing anything:

rules/story-formats.md to pick the shape, rules/narration.md for the script, rules/images.md for the prompts, rules/pitfalls.md for the checklist.

1. Pick the format from rules/story-formats.md and start from the matching

template in rules/assets/<format>/story.json. Copy it to public/<slug>/story.json and change slug and compositionId first.

1. Write the narration from the context:

- Scene count is roughly seconds divided by ten, clamped 3 to 10 - 24 to 32 words per scene - Numbers spelled as words; digits only on stat cards - Every fact traceable to the given context, nothing invented - Note any contradiction in the source and say which reading was used

1. Write the image prompts:

- Scene direction only. The house style lives in style.artPrompt - Two images per scene for movement, one for a calmer feel - Never name a real person. If the user supplied reference photos, add them to references and set reference on those images, putting the likeness clause first in the prompt - Image ids unique across the whole story, and outro.imageId must be one of them

1. Show the narration to the user and wait for approval. Voices and images

cost money; a wrong fact caught here is free.

1. Generate:

``bash npm run generate -- --slug <slug> ` This writes voices, images and the measured durationInFrames back into story.json`. Existing files are skipped, so reruns are cheap.

1. Preview or render:

``bash npm run studio npx remotion render <CompositionId> out/<slug>.mp4 --codec h264 ``

1. Verify before reporting: check the output exists and read its real duration

rather than assuming the planned one.

1. Report scene count, total duration, image count, output path and size, plus

any assumption made about an ambiguous fact.

Fully automatic alternative

When the user wants no review step and has OPENAIAPIKEY set:

npm run story -- --slug big-bull --context ./article.md --seconds 60 --render

This drafts with OpenAI, generates, and renders in one pass. Quality of facts is lower than a hand-written story.json, so prefer the reviewed path for anything that will be published.

Formats

Example usage

/story-new big-bull ./article.md 60 landscape /story-new repo-rate "Explain the repo rate to a first time borrower" 30 vertical /story-new fed-cut ./notes/fed.md