Content & Media Creation · nateherkai/hyperframes-student-kit
video-storytelling
Design and build the visual layer of a long-form talking-head video as one persistent world the camera moves through, instead of a sequence of separate graphics. Use when asked to edit a video, add motion graphics, design the visuals for a script, plan an edit, or fix an edit judged confusing, text-heavy, hard to follow, or "clearly made by an AI". Covers the persistent world, camera grammar, the spotlight rule, spatial open loops, ornament and token discipline, transcript timing, and the verification gates.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The root pathology to fix is "scene-based thinking": switching to a new graphic every few seconds forces viewers to reset their comprehension each time, while failure feedback manifests as vague critiques like "confusing / too cluttered" rather than specific defects.
.claude/skills/video-storytelling/SKILL.md
The failure this replaces is scene-thinking. … rather than as a specific defect.
What is happening here: Tracing the "AI feel / confusing visuals" back to structural decisions rather than individual graphic aesthetics, laying the foundation for all subsequent geometric and discipline rules.
One persistent world: A single space across the entire video that never resets; existing elements are never redrawn, moved, or relabeled; spatial grammar is locked down before building anything and maintained throughout.
.claude/skills/video-storytelling/SKILL.md
### One persistent world … An element, once drawn, is never redrawn, moved, or relabelled.
What is happening here: Preventing world resets serves as a prerequisite for downstream mechanics (the camera has places to go, spotlights carry meaning, and open loops stay open); in the reference implementation, left-to-right = progressing toward outcomes, top = humans and the sole warm color, bottom = system logs, with only a single semantic exception permitted (reversing playback for reopen rate).
The camera is the edit: Hard-cutting to a new graphic disorients the viewer, whereas moving within a static space incurs zero cognitive penalty; establishes three heights (World/Region/Detail) and adjacent movement rules.
.claude/skills/video-storytelling/SKILL.md
### The camera is the edit … Moving through a space that stays put costs them nothing.
What is happening here: Elevating camera movements into informational structure, accompanied by battle-tested rules earned through rework (framing framed as world-space bounding boxes rather than scale factors, reusing identical windows for identical intents, ensuring overlays are fully opaque before moving the camera, keeping label padding ≥60px from boundaries, and merging two sequential motions into a single gesture).
Attention is a spotlight: Only one element is fully illuminated at any given moment while previously drawn elements remain quiet yet legible; visual hierarchy stems from the bright-to-quiet contrast ratio rather than dimming the entire screen.
.claude/skills/video-storytelling/SKILL.md
**Exactly one element at full brightness at any moment. Everything else already drawn stays quiet but legible.**
What is happening here: Defines specific states and target brightness levels (active 200–235 / context 120–150 / spent 85–105, with labels never below 90), uniformly driven across every spoken beat via a lit() function; in the reference implementation, the v1 peak brightness was illegible at only 101/255, and the fix was boosting ink luminance rather than dimming further.
Open loops are spatial: Instead of saying "we'll return to this later", leave a visible, incomplete construct within the persistent world, selecting geometric topologies based on the script's shape (parallel items / deep flows / layers / comparisons / news / tutorials).
.claude/skills/video-storytelling/SKILL.md
Never say "we'll come back to this." Leave something visibly incomplete in the world and return to it.
What is happening here: Spatializing dramatic tension through a four-step mechanism: planting in the hook, recurring at each structural boundary, showing visible progress, and closing using the opening graphic; counters must be paired with 1–2 word descriptive names rather than bare numbers.
Element discipline: If it isn't spoken, don't draw it—every single shape must be a labeled element, a connecting line between labels, a focal subject in motion, or an ambient background, keeping on-screen text to around 20 words per section.
.claude/skills/video-storytelling/SKILL.md
### If it doesn't get a word, it doesn't get drawn … Nothing else.
What is happening here: Diagnosing "visual clutter" as unlabeled shapes sharing the same stroke weight and palette as meaningful shapes, forcing viewers to spend cognitive effort decoding noise; enforces strict visual budgets and "never stacking counter-example visuals directly onto the recommended solution".
A global token set is a hard constraint: stroke weights 1.5/2.5/4/7, font sizes 22/30/42/60/84, corner radii 10/22/40 (strictly superellipse n=2), five colors with five semantic meanings, zero ornament, strictly enforced by token linters that fail the build on violations.
.claude/skills/video-storytelling/SKILL.md
Full detail in `reference/design-system.md`. … Gate it with a token linter that fails the build.
What is happening here: Remedying the v1 pathology where "every decision was locally sound, but no decision was global" (18 stroke weights, 9 font sizes, many differing by a mere 0.2); design-system.md asserts the token rule as "the single most important rule", backed by qa-tokens.mjs failing on any deviation.
Build contracts enshrine real-world engineering failures into rules: one generator per section, shared modules locked against concurrent edits, SVG defs strictly namespaced before assembly, and renders strictly enforced via --workers 1.
.claude/skills/video-storytelling/SKILL.md
**Namespace the SVG defs before assembly.** … Cost in the reference build: 35 seconds of empty screen with every gate green. … `--workers 1` on render. Parallel workers make the video layer paint black.
What is happening here: Turning costly rework into automated checks—un-namespaced defs wiped out large areas post-assembly while all verification gates stayed green; multi-worker parallelism caused frames to render black; inserting breath pauses with hard cuts clipped vocal decay, resulting in perceived stuttering.
Verification gates are comprehensive, yet explicitly "gates cannot replace human eyes": motion smoothness must be verified across sequential frame strips, and every gate must be validated against known-failing negative controls.
.claude/skills/video-storytelling/SKILL.md
**Gates do not replace looking**, and gates that have never failed are not gates. … Motion smoothness is verified on contiguous frames, never on beat frames. … Validate every gate against a control … A seam gate that reports zero on a broken build is worse than no gate.
What is happening here: Identifies concrete defect fingerprints (adjacent tile jumps followed by multiple identical frames = front-heavy easing/dead stops; one motion halting right before another starts = should be merged into a single gesture; single-frame anomalies = pops), noting that the reference implementation's intro once passed all gates with such a glitch until caught in a single human viewing.
Audio auditing must extend to the acoustic layer, not merely the transcript layer: full-track dead-air scans, 1ms-resolution envelope forensics, and re-running ASR on the final rendered video to diff against expected text.
.claude/skills/video-storytelling/SKILL.md
**Audit audio at the acoustic level, not the transcript level.** … truncation cliffs and dead holes, not doubled words.
What is happening here: Explains why transcript-layer auditing is structurally blind to artifacts introduced by editing (reports clean while clients hear stutters); establishes correct breath-pause insertion (room tone + 40ms equal-power crossfades, never hard cuts).
2Core Capabilities
01Long-form visual layer design methodology: persistent world + spatial grammar + 3-height camera + spotlight rule + spatial open loops
02Selecting open loop geometries matched to script topology (parallel items / deep flows / layers / comparisons / news / tutorials), complete with a reusable working example (wall of slots)
03Portable geometric modules: slot materials, lighting definitions, and superellipse path generators ensuring consistent coordinate interfaces across section builders
04Tokenized visual design system (stroke / type / radius / 5-color semantic palette) backed by fail-on-violation linter gates
05Generator engineering discipline: per-section build_<id>.py writing isolated HTML, locks on shared modules, namespaced defs before assembly, and --workers 1 rendering
06Transcript timing discipline: synchronizing visual entrances to speech word starts (0.15–0.25s advance lead), auditing dead frames >1.5s, and breath insertions via room tone with 40ms equal-power crossfades
07Verification gate suite and filmstrip inspection: qa-tokens / no-crossfade / legibility / seamjump / deadframe / presence / integrate + sequential transition frame strips
08Clear demarcation from adjacent skills: explicitly distinguished from hyperframes-video-beats (which places overlay cards over the speaker, whereas this skill builds what the video is "about")
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | FFmpeg（转场窗口连续帧条带抽取，用于读运动缺陷） |
| cli | Node 门禁脚本族（使用者项目内生成的 qa-*.mjs / integrate.mjs，非随包分发）与 HyperFrames CLI |
| package | Python 几何/槽位模块（随包分发，供项目 section builder 导入） |
| package | 兄弟资源：仓库根 docs/STORYTELLING-WORKBOOK.md（中性练习表）与本 skill 的 reference/design-system.md |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Local script or command execution: (No executable CLI entry point inside the skill directory; the two .py files are geometric math modules meant to be imported by the user's project generators)
- 本地工作目录: File I/O and artifact output: Writes project-level compositions/<id>.html (generated via scripts/build_<id>.py; strictly mandates modifying generators rather than editing generated artifacts directly)
Audit Notes: The skill directory contains only SKILL.md + reference/ (one design system markdown file, plus a pattern directory with README.md and two .py files). The two Python files provide pure geometry math: wall.py defines slot/material and SVG defs constant strings, while geom.py contains only math and path construction. A full grep across the directory (*.md/*.py) reveals zero http requests, zero requests/urllib imports, zero os.environ access, and zero subprocess calls—meaning no network egress, no credential exfiltration, and no arbitrary subshell execution. Actions described in SKILL.md are strictly local build and validation steps: generating build_<id>.py and compositions/*.html, rendering frames, running local qa-*.mjs gates, inspecting frames via ffmpeg, and running npx hyperframes lint. The only notable operational risks are disk write volume (generators bake hundreds of timeline literals, requiring AST shifts rather than manual edits when timings change) and documented rendering constraints like --workers 1 (parallel workers cause rendered frames to turn black).
5Second-Pass Verification
- [ok] 两个随包 .py 是否真的无网络/无 env/无子进程（蓝档关键） — wall.py 仅 import os, sys 用于路径常量与 DEFS 字符串（os 未用于 environ/exec）；geom.py 仅 import math。全目录 grep 无 requests/urllib/socket/http/os.environ/subprocess/eval。结论：几何模块，无执行面。
- [discrepancy] SKILL.md 的门禁脚本是否真属本 skill（避免把项目内产物算作 skill 资产） — ［判定：口径澄清，非缺陷］SKILL.md 的命令写作 node scripts/qa-tokens.mjs、node scripts/build_<id>.py、node scripts/integrate.mjs——这些是使用者项目里生成的脚本，pin 仓库的 skill 目录内不存在（该目录仅 5 个文件）。本报告因此在 internal_assets 只列随包文件，并在 external_deps 标注门禁脚本属项目内生成物。
- [unlocatable] 参考实现的具体数字与事故能否在源码内定位 — SKILL.md 引用的大量参考构建细节（最亮像素 101/255、35 秒空屏、输入口 glitch、被听成 stutters 的 20-40ms 接缝、speaker 在屏约 40%）来自作者对一段私有参考构建的返工记录；pin 仓库内没有该构建的渲染/日志/qa 输出，故这些数字只作「文档声明」记录，不在结论中当已核事实。方法本身（规则名与门禁名）可在 SKILL.md 内逐条定位。
- [ok] 「门禁不能替代人眼」是否只是修辞（会不会把 qa 脚本当通过依据） — SKILL.md 明写 'Gates do not replace looking, and gates that have never failed are not gates.'，并要求每条门用已知会触发的 control 验证、在装配体而非 section 原型上验证、可读性必须看 960x540 降采样、运动必须读连续帧条带。规则自洽且可执行。
- [ok] 音频纪律是否与「剪辑不碰词」原则冲突 — SKILL.md 要求在句界插入 4–8 帧房间音（words never touched）、用 40ms 等功率交叉淡入接进尾音衰减、且插入式改动对转写是确定性位移（无需重转写）——与语速/词不被裁切的原则一致，属对反例（硬接造成 cliff）的显式修正。
6Verdict & Scenarios
Best for: Ideal for creators building scripted, long-form talking-head videos (news breakdowns, deep dives, comparative analyses, tutorials, listicles) who write their own code generators: teams that need to maintain viewer orientation across a 10-minute runtime, require portable open-loop geometries and a tokenized visual system, and embrace dual-track verification ("automated gates + visual inspection"). Also serves as a diagnostic manual for identifying why visuals feel "obviously made by an AI".
Not for: Not suitable for: (1) simple talking-head lower thirds or overlay graphics (use hyperframes-video-beats); (2) short-form or vertical fast-paced cuts (this skill is tailored for long-form persistent worlds); (3) creators looking for plug-and-play visual templates without writing generators or running test suites; (4) purely hands-off automated pipelines unable to perform manual visual and acoustic checks (this methodology explicitly rejects relying solely on test gates for sign-off).
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload video-storytelling.tar.gz
sha256:
Option B · Copy Guide for Agentaf02bf58b5fef932…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 0d30152a82.