agentleFS
sugarforeversugarforever/boring-video-studio/skills/boring-video/to-narration/SKILL.md

to-narration

Skill186 starsChanged 22 days agoMITView on GitHub

Use when writing or revising spoken narration from complete, lineage-valid video beats, including scripts that must remain open to later visual direction.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write narration in natural, easy-to-say language.

    line 13
  2. Distinctive:

    Read it aloud or estimate at the user's known speaking rate.

    line 38
  3. Very specific:

    Before presenting NARRATION.md or any later revision, follow ../boring-video/references/markdown-review.md.

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

To narration

Turn BEATS.md into NARRATION.md: the spoken version of the approved article and video structure. This pass changes language for the ear; it does not establish the author's argument for the first time.

Process

  1. Read BEATS.md, its approved content/ARTICLE.md source, the cited evidence needed for accuracy, and the resolved voice sources recorded by the article. Recompute the article approval digest and beats artifact digest; require them to match the stored article approved_digest, beats source_digest, and beats artifact_digest. Load every applicable writing-style skill or document that is available. Preserve each beat's job, claim, and handoff.
  2. Write narration in natural, easy-to-say language. Use concrete subjects, actions, and changes to make events clear, so listeners can follow and understand the account as it unfolds. Preserve the author's voice while adapting reading prose into speech.
  3. Let visuals carry visible structure, comparison, and transformation. The narration supplies meaning the image cannot communicate alone.
  4. Mark paragraph-to-beat boundaries without adding visual instructions. Put unresolved pronunciation or factual questions in an Open checks section.
  5. Write NARRATION.md:
---
source: BEATS.md
source_digest: sha256:<BEATS artifact_digest>
content_source: content/ARTICLE.md
content_digest: sha256:<ARTICLE approved_digest>
artifact_digest: sha256:<digest>
status: draft
target_duration: ...
---

## B01 — Title

<a id="b01-p01"></a>
Spoken paragraph.

Compute artifact_digest as SHA-256 of the complete narration file after removing only the artifact_digest: line. Downstream stages must recompute it before use.

  1. Give every paragraph a stable <beat-id>-pNN anchor. Preserve anchors when rewriting that paragraph; assign a new anchor when inserting one.
  2. Read it aloud or estimate at the user's known speaking rate. Revise until every beat fits its budget and the full draft fits the target.

Every material fact, viewpoint, and conclusion must trace through its beat to the approved article. When speech needs content the article does not establish, immediately return content/ARTICLE.md to status: draft and revise it there; return content/TOPIC.md to draft too when the change affects a locked topic decision. Renew the approvals defined by those upstream files, update BEATS.md to match, and only then use the content in narration. BEATS.md has no separate approval state in this workflow.

Before presenting NARRATION.md or any later revision, follow ../boring-video/references/markdown-review.md. Present the authoritative Markdown for inspection without starting or replacing HyperFrames' later voice-review loop.

The draft is complete when it is ready for visual planning, every material sentence traces to both a beat and the approved article, no later visual has been prematurely prescribed, and the Markdown review completion criterion is satisfied. The shared HyperFrames project owns review timing and the voice-ready narration version once /to-scenes begins.

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.