story-architect
Skill0 starsChanged 3 months agoMITView on GitHub
Turns decks, docs and a rough message into a film's story spine — the beat sheet, the on-screen counterpoint and the spoken voiceover script, timed to a target runtime. Use when writing or rewriting the narrative for a product film, explainer or launch video, when a script needs tightening to length, or when a cut feels like a list of features rather than a story.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- LordVayron/video-factorytheir own version, first seen Nov 15, 2026
- Tivaphe/hermes-worldbible-skillstheir own version, first seen Oct 20, 2026
- design1online/author-ittheir own version, first seen Jul 13, 2026
- NeuraCerebra-AI/story-architect-skilltheir own version, first seen May 18, 2026
- HashLips/agent-skillstheir own version, first seen Apr 21, 2026
- RandomNest/aivideo-production-skillstheir own version, first seen Feb 20, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- LordVayron/video-factory★ 67same name
- HashLips/agent-skills★ 29same name
- RandomNest/aivideo-production-skills★ 15same name
- design1online/author-it★ 2same name
- NeuraCerebra-AI/story-architect-skill★ 0same name
- Tivaphe/hermes-worldbible-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- final-cutSkill
- make-filmSkill
- score-filmSkill
- shot-designerSkill
- shot-reviewSkill
- veo-renderSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 54
The picture is not an illustration of the voice: If the VO says "alerts pile up" and the screen shows alerts piling up, you have made a …
- Very specific: line 60
Write on_screen for every beat.
- Distinctive: line 67
Sentences you can say in one breath: If you run out of air reading it aloud, it is too long.
- Distinctive: line 71
Never write what is already on screen: If the number is in the graphic, the voice says what it means, not what it is.
- Distinctive: line 94
Avoid parentheses and em-dashes.
- Very specific: line 114
Keep beat ids identical to shot ids.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Story architect
Your job is the spine. Not the words yet — the shape. A product film fails in the outline, and no amount of beautiful footage rescues a film that is a list.
Output is script.json plus the beats block of shotlist.json.
Read first, write second
Go through everything the user gave you before drafting a line. You are looking for four things, and they are usually already in the material:
- The one sentence. What is true after this product exists that was not true before. If you cannot say it in a sentence, the film has no spine.
- The cost of the status quo, in the audience's own terms. Not "inefficiency" — the 3 a.m. call, the eleven tabs, the quarter that slipped.
- The turn. The thing that makes this different from the last four tools they bought. There is usually exactly one, and decks bury it on slide 14.
- The proof. Numbers, architecture, governance — whatever makes it credible rather than aspirational.
Note where each came from. Every beat records its source (slide number, doc
section, or director if you invented it). Anything marked director must be
approved by the user before it is rendered — that is how you stay useful without
putting words in their mouth that they cannot defend.
The shape
Eight functions. Most films use six. Each beat does exactly one, and two adjacent beats never do the same one — if they do, one of them is redundant, cut it.
| function | what it does |
hook | earns the next ten seconds. Concrete, specific, no throat-clearing |
stakes | makes the status quo unacceptable — in their language, not yours |
turn | the reframe. "The problem is not X, it is Y" |
reveal | the product, arriving as the answer to the turn, not as a product |
proof | how it actually works, enough to be believed |
objection | the thing they are already thinking (risk, cost, rip-and-replace) |
ask | what they do next, singular and concrete |
close | the one sentence, said plainly, once |
The default 90-second shape: hook · stakes · turn · reveal · proof · proof ·
objection · ask/close. Eight beats, ~11s each. That is the film. Deviate when the
material demands it, not to fit more in.
The one rule about what's on screen
The picture is not an illustration of the voice. If the VO says "alerts pile up" and the screen shows alerts piling up, you have made a slideshow with extra steps. Give the picture the counterpoint: the VO says alerts pile up, the screen shows one person alone in a lit office at 3 a.m. and the room around them dark. The viewer joins the two, and that joining is the entire pleasure of film.
Write on_screen for every beat. It is a note to the shot designer about what the
viewer feels, not a shot description — that comes next stage.
Writing the voice
This gets spoken, not read. That changes everything.
- Sentences you can say in one breath. If you run out of air reading it aloud, it is too long. Read every line aloud. Yes, actually.
- One idea per sentence. Subordinate clauses are for documents.
- Nouns and verbs. Adjectives are where corporate video goes to die.
- Never write what is already on screen. If the number is in the graphic, the voice says what it means, not what it is.
- Vary the rhythm. Long, long, short. The short sentence is where you put the thing you want remembered.
- No "we're excited to", no "in today's fast-paced", no "seamlessly", no "leverage", no "unlock", no "revolutionise". These read as noise to an executive audience and actively cost you credibility.
- End on a full stop, not a cliffhanger. The last line is the one sentence.
Pacing: 2.3–2.6 words per second is comfortable narration. At 2.5 w/s a 90-second film is about 200 words of VO after you allow for the silences. That is much less than people expect — roughly 25 words a beat. Cut accordingly, and cut whole beats rather than compressing every beat into breathlessness.
Writing for the synthesiser
The scratch voice is TTS, and the real recording will be timed against it, so write for both:
- Spell numerals: "twenty to thirty percent", not "20–30%".
- Space initialisms so they are read as letters:
A P I,I T,S L A. Leave acronyms that are said as words alone:SaaS,NEO. - Punctuate for breath, not for grammar. A comma is a beat.
- Avoid parentheses and em-dashes; they do not survive being spoken.
script.json
{
"lead": 0.55,
"tail": 0.95,
"beats": [
{"id": "01", "vo": "I T operations today runs on people absorbing complexity."},
{"id": "02", "vo": "One failure fans out into a hundred alerts."}
]
}lead is the silence before each line — the viewer must see the shot before being
told about it. tail is the silence after, so the line lands before the cut.
Together they set the film's pulse; 0.55 / 0.95 is a calm executive register.
Tighten to 0.35 / 0.6 for something punchier.
Keep beat ids identical to shot ids. That is what lets narrate.py re-time the
whole film from the script alone.
Mark where the music turns
While the spine is fresh, add a music note to the three or four beats where
the argument actually turns — in shotlist.json, on the matching beat:
{"id": "04", "vo": "...", "music": "a second voice enters underneath, still quiet"}score-film converts each into a timed cue for the music model, so the bed
changes where the film changes rather than somewhere near it. Write what the
music does, not what is on screen. Do this now and not later: you are the only
stage that knows where the turns are, and a cue on every beat — which is what
happens when someone adds them afterwards — produces music that fidgets.
Then show your work
Present the beat sheet to the user as prose, not JSON — a numbered list of what happens, with the VO line under each, and the runtime estimate. Ask for a yes. This is the cheapest possible moment to change the film, and the last moment where change is free.
References
references/patterns.md— six proven spines (problem/reframe, day-in-the-life, before-after, the objection film, the launch, the vision) and when each worksreferences/voice.md— line-level craft, worked rewrites, and a list of phrases to strike on sight
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

