agentleFS
FSBuilder-mayuresh93FSBuilder-mayuresh93/product-film-director/skills/story-architect/SKILL.md

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

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
  1. Distinctive:

    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 …

    line 54
  2. Very specific:

    Write on_screen for every beat.

    line 60
  3. Distinctive:

    Sentences you can say in one breath: If you run out of air reading it aloud, it is too long.

    line 67
  4. Distinctive:

    Never write what is already on screen: If the number is in the graphic, the voice says what it means, not what it is.

    line 71
  5. Distinctive:

    Avoid parentheses and em-dashes.

    line 94
  6. Very specific:

    Keep beat ids identical to shot ids.

    line 114

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

functionwhat it does
hookearns the next ten seconds. Concrete, specific, no throat-clearing
stakesmakes the status quo unacceptable — in their language, not yours
turnthe reframe. "The problem is not X, it is Y"
revealthe product, arriving as the answer to the turn, not as a product
proofhow it actually works, enough to be believed
objectionthe thing they are already thinking (risk, cost, rip-and-replace)
askwhat they do next, singular and concrete
closethe 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 works
  • references/voice.md — line-level craft, worked rewrites, and a list of phrases to strike on sight

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.