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

score-film

Skill0 starsChanged 3 months agoMITView on GitHub

Chooses and generates the film's background music with Google Lyria on Vertex AI — reads the topic and beat sheet, proposes four or five scored directions with one recommended and the reasoning for it, then generates the chosen bed timed to the film's beats and fitted to its exact runtime, optionally auditioning candidates as 30-second clips first. Use when a film needs music, when the user asks for background music, a music bed, a soundtrack or a score, when choosing between musical directions, when the current bed is wrong for the subject, or when re-scoring a film after a re-cut.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Offer the ear when prose is not enough: If the user hesitates, says they cannot tell, or picks and then sounds unsure — stop and audition.

    line 34
  2. Distinctive:

    Do not ask the user what kind of music they want.

    line 41
  3. Distinctive:

    Read, in this order:

    line 44
  4. Very specific:

    Use AskUserQuestion to take the decision, with your pick first and marked (Recommended).

    line 97
  5. Distinctive:

    Not the default path: the film is normally scored straight from the written choice.

    line 113
  6. Very specific:

    Run with --dry-run first if you want to read the prompt before spending anything.

    line 175
  7. Distinctive:

    Does the bed change where the film changes?: If not, your cues were too many or too vague.

    line 190
  8. Very specific:

    Do not score before the voice exists: Every duration is a guess until narrate.py --align-shotlist has run.

    line 205

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Scoring the film

Music is the fastest way to change what a film means. The same ninety seconds of picture and voice reads as confident under a sustained low pad and as anxious under a pulsing ostinato. So this is not a decoration step at the end — it is a decision about register, and the user makes it, not you.

Your job is to narrow the field to a few real choices, say which one you would use and why, then generate it properly.

  read the film  →  propose  →  score  →  cut
   topic + beats     4–5 in     the pick   final-cut
                     writing    full-length

Propose four or five in writing, generate only the pick. One generation per film, about $0.30. Written options are free, so the narrowing happens on paper and audio is spent once, on the direction that won.

The cost of this is real and you should carry it rather than pretend otherwise: choosing music from prose is hard. Two consequences follow, and both are your job, not the user's:

  • Write the descriptions so they can actually be chosen between. Name the instruments, say what the bed does to this film, and describe the failure mode of each. "Ambient and calm" is not a choice; "a low pad with occasional piano, which would let the cost figures land in silence" is.
  • Offer the ear when prose is not enough. If the user hesitates, says they cannot tell, or picks and then sounds unsure — stop and audition. It is one command and six cents a clip (§3). Never let someone commit to a bed they have not heard just because the default path skipped it.

1. Read the film before proposing anything

Do not ask the user what kind of music they want. They will say "something corporate" and you will both be disappointed. Derive it, then check it with them.

Read, in this order:

  • script.json — the voiceover. The register of the writing is the single best predictor of the bed. Short declarative sentences want space; long subordinate clauses want something that holds still underneath them.
  • shotlist.json → beats — the argument's shape. Where does it turn? A film that goes problem → cost → resolution needs music that moves at those two points and nowhere else.
  • The subject itself — infrastructure, incident response, launch, customer story. references/directions.md maps subjects to directions.
  • look in the shot list — if the picture is cold and blue, warm strings will fight it.

Then form a view. You should be able to finish this sentence before you speak: "This film is arguing X to an audience of Y, so the bed should feel Z and must never do W."

2. Propose four or five, in writing

Rank the library at ${CLAUDE_PLUGIN_ROOT}/music/directions/ against the film and present four or five as prose — or write a new direction if nothing fits. Never dump JSON at the user.

For each, three things, because a description without all three cannot be chosen between: what it sounds like (name the instruments), what it would do to this film, and how it would fail. Then say which you would use and why, and name one you rejected and what picking it would have cost. A recommendation without a rejection is not a recommendation.

  1. Restrained Systems   ← recommended
       low synth pad, occasional single piano notes, almost no movement
       would let the cost figures land in silence and keep the film sounding
       like an engineering decision rather than a pitch
       fails by: being so still that a distracted viewer hears nothing at all

  2. Quiet Urgency
       pulsing low string ostinato, felt more than heard
       would make the outage sequence bite harder
       fails by: still pushing through the resolution beats, so the film ends
       sounding like the problem is ongoing

  3. Weightless Modern
       glassy sustained tones, wide and synthetic
       right for the agentic beats
       fails by: going cold under the human ones — there is no warmth in it

  4. Open Horizon
       warm strings opening in layers
       fails by: arriving before the film has earned it, which reads as a
       sales close

Use AskUserQuestion to take the decision, with your pick first and marked (Recommended).

If they hesitate, audition instead of guessing. Any of "I can't tell from that", a long pause, or a pick they immediately qualify — go to §3. Six cents beats a bed nobody is happy with.

Two rules that decide most of these:

  • The bed you notice is the bed that loses. A film's music is judged by whether the argument landed, never by whether the track was good.
  • Match the ending, not the opening. Almost everyone picks music for the first ten seconds. The last ten are what the audience leaves with.

3. Audition — when prose is not enough

Not the default path: the film is normally scored straight from the written choice. Reach for this when the user cannot decide, wants to hear the options, or when the film is important enough that a bed nobody has heard is a bad bet.

Generate real 30-second clips of the two or three in contention. Six cents each.

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/lyria_client.py" audition \
  --project "$GOOGLE_CLOUD_PROJECT" --outdir audio/auditions/ \
  --directions "${CLAUDE_PLUGIN_ROOT}/music/directions/restrained-systems.json,${CLAUDE_PLUGIN_ROOT}/music/directions/quiet-urgency.json,${CLAUDE_PLUGIN_ROOT}/music/directions/weightless-modern.json"

Pass the shortlist explicitly. Handing the whole directory is refused above three files — it spends four times the money to answer a question the written ranking already narrowed. --all overrides it if you really mean to.

Deliver the clips with SendUserFile and let them choose by ear. If they cannot listen right now, proceed with your recommendation and say clearly that you did.

4. Write the cues — three or four, no more

The reason to use Lyria 3 Pro is timestamp prompting: the bed can be told to change where the film changes. Add a music note to the beats that turn, in shotlist.json:

"beats": [
  {"id": "b1", "vo": "...", "music": "sparse, one sustained low note, almost nothing"},
  {"id": "b4", "vo": "...", "music": "a second voice enters underneath, still quiet"},
  {"id": "b7", "vo": "...", "music": "open up, warmer, the first real movement"}
]

A cue on every beat produces music that fidgets. Three or four in ninety seconds, at the moments the argument turns. lyria_client.py converts each into a [m:ss] cue and always appends a resolve instruction at the runtime mark.

Give the film one beat with no voice — two-thirds through, picture and music only, three to five seconds. That is where the cue you wrote actually gets heard, and it is the moment the film stops being a presentation. See final-cut.

5. Generate the bed

Lay the voiceover first. The bed is generated to the film's real runtime, and that runtime does not exist until narrate.py --align-shotlist has set the shot durations. Scoring before that produces a bed of the wrong length every time.

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/lyria_client.py" score \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --direction "${CLAUDE_PLUGIN_ROOT}/music/directions/restrained-systems.json" \
  --shotlist shotlist.json --out audio/bed.wav --write-shotlist

--write-shotlist patches audio.music, audio.music_gain_db and the prompt, negative prompt, model and seed actually used into the shot list — actually, not nominally: if the ladder dropped to a 30-second model, what is recorded is the 30-second prompt that model was sent, so re-running it reproduces this bed rather than a different one. The direction's own gain_db wins on a re-score. Then re-cut with final-cut — the assembler loops nothing, side-chain ducks the bed under the voice and normalises the mix.

Run with --dry-run first if you want to read the prompt before spending anything. On the default path a film costs one generation, about $0.30 — call it $1.00 allowing for the two or three rolls a bed usually takes. Auditioning adds six cents a clip on top.

6. Check it against the film, not on its own

Play the cut, not the track. Then:

  • Can you follow the tune while someone is speaking? Drop music_gain_db by 4 and re-cut. −22 dB is the start; −26 for a serious register, −18 for a launch film where the energy is the point.
  • Does the last phrase land, or does it stop? The script fades the final --resolve seconds (3.5 by default) for exactly this. Raise it to 5 for a slow ending.
  • Does the bed change where the film changes? If not, your cues were too many or too vague. Fewer, more concrete.
  • Does anything poke through? Percussion transients and melodic hooks survive ducking. Re-roll with the offending instrument added to the direction's avoid.

Rules

  • Instrumental, always. A vocal fights the voiceover and cannot be mixed around. The prompt builder states this explicitly and puts vocals in the negative prompt; do not remove it.
  • Never source music the user has not cleared. Generating it here is the point — do not go and find a track instead.
  • Lyria output carries a SynthID watermark and is subject to Google's generative-media terms. If the film is going somewhere with strict provenance rules, tell the user before you generate, not after.
  • Do not score before the voice exists. Every duration is a guess until narrate.py --align-shotlist has run.

When something is off

  • HTTP 403/404 on lyria-3-pro-preview — the project is not allowlisted for the preview model. The client walks down a ladder rather than dying: lyria-3-pro-preview → lyria-3-clip-preview → lyria-002, rebuilding the prompt for each rung and printing which one actually answered. Below the top rung the model can only write 30 seconds, so the bed is crossfade-looped to length and the timestamp cues are dropped — request preview access if the film needs its music to turn where the argument turns. --no-fallback fails loudly instead.
  • The bed sounds like a loop — it is one. That is the lyria-002 path. Raise --crossfade (on score as well as fit; 4–6 hides a seam that 2 does not), or choose a direction with less movement, which loops far more invisibly.
  • Bed and film are different lengths — the shot list changed after scoring. Re-fit rather than regenerating; in-place is fine, the script renders beside the file and swaps it in: lyria_client.py fit --in audio/bed.wav --out audio/bed.wav --runtime <new>.
  • "shot(s) N have no duration" — stop and run narrate.py --align-shotlist. Those shots count as zero here but not in the assembler, so the film comes out longer than the bed, the assembler loops it, and the resolved ending you paid for lands somewhere in the middle of the film.
  • ffmpeg failed — the log is at /tmp/lyria-ffmpeg.log.

References

  • references/directions.md — the direction library, what each one is for, how to write a new one, and the subject-to-direction map
  • references/lyria.md — models, API shapes, parameters, costs, auth and limits

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.