Module 3.1 — Skill Structure

📂 The folder `video-explicativo/`

Everything Claude needs to create an explainer video lives in one well-organized folder. Nothing more, nothing less.

💡 Main Concept

The folder video-explicativo/ is the complete skill: it contains the entry file (SKILL.md), the executable scripts (scripts/) and supporting references (references/). Claude accesses each layer only when needed — never all at once.

complete skill tree

video-explicativo/
├── SKILL.md                          ← entrada principal
├── scripts/
│   ├── composition-template.mjs      ← gerador de composição
│   ├── fetch-fonts.mjs               ← baixa .woff2 subset latin
│   └── narration-template.sh         ← gera WAVs com Kokoro
└── references/
    ├── pipeline.md                   ← passo a passo completo
    ├── house-style.md                ← identidade visual dark premium
    └── gotchas.md                    ← armadilhas e correções

✓DO

✓Keep all 7 files in the exact structure
✓Copy scripts to the video project before editing
✓Use SKILL.md as the entry point every time
✓Consult references/ on demand via links

✗DON'T

✗Edit the scripts directly in the skill folder
✗Ignore the reference files, thinking they're optional
✗Create extra files in the project root (index-vertical.html, backups)
✗Rename SKILL.md or change its location

📄

SKILL.md

Entry point

📁

scripts/

3 executables

📚

references/

3 supporting guides

🗂️

7 files

Minimum structure

📚 The 3 references

Each file in references/ has a single purpose and is loaded only when that specific knowledge is needed.

pipeline.md Step by step

The complete operational guide. It explains each of the 7 steps in the workflow in detail: project structure, how to write the script, generate narration with Kokoro, measure durations with ffprobe, build the composition and render it in two formats.

house-style.md Visual identity

Defines the premium dark that Nei uses in all videos: palette (#0D1321 bg, amber as the accent, cyan as the highlight), Sora 700–800 typography for headings and Inter for body text, JetBrains Mono for code. Formats: 16:9 → 1920×1080 and 9:16 → 1080×1920. Final CTA required: INEMA.CLUB.

gotchas.md Traps

Real problems already encountered: overlapping_clips_same_track (toggle data-track-index 1/3 for scenes, 2/4 for captions), gsap_exit_missing_hard_kill (add tl.set after fade-out), off-canvas decorative elements marked with data-layout-ignore, and use ffmpeg -nostdin in git-bash.

📊

Progressive disclosure design data

O SKILL.md points to the 3 reference files via relative Markdown links. Claude never loads all references at once — it opens only the file linked when that specific context is needed. This keeps the context window light.

⚡

Practical tip

Before starting any video, read the pipeline.md complete. It documents real cases that have already happened and prevents you from repeating mistakes that take hours to diagnose — especially the error involving ffmpeg -nostdin on Windows/git-bash.

🔀

pipeline.md

7 detailed steps

🎨

house-style.md

Dark premium amber

⚠️

gotchas.md

Real errors prevented

🔧 The 3 scripts

Each script in scripts/ is a template you copy into the video project and adapt — never edit it directly in the skill.

⚡

Golden Rule for Scripts

Scripts are templates — not directly executable. You copy for your video project (renaming as needed), then adapts it. The original in the skill remains untouched for the next video.

⚙️

composition-template.mjs

Main generator for the HyperFrames composition. Defines AUDIO[] with actual durations, CAPTIONS[], function sceneN() per HTML scene and anim(i,t) for GSAP tweens.

Copy as build-index.mjs

🔤

fetch-fonts.mjs

Downloads the Sora, Inter, and JetBrains Mono fonts from Google Fonts as files .woff2 subset latin, generating assets/fonts/fonts.css with @font-face local.

Run: node fetch-fonts.mjs

🎙️

narration-template.sh

Shell script that writes the files assets/txt/sN.txt and calls HyperFrames TTS with the voice pf_dora --speed 0.98 to generate assets/audio/sN.wav.

Copy as assets/narration.sh

narration-template.sh — excerpt

# Gera cada cena via HyperFrames TTS
for i in 1 2 3 4 5 6 7 8; do
  npx -y hyperframes tts "txt/s$i.txt" \
    --voice pf_dora \
    --speed 0.98 \
    --output "audio/s$i.wav"
done

# Mede durações com ffprobe
for i in 1 2 3 4 5 6 7 8; do
  d=$(ffprobe -v error \
    -show_entries format=duration \
    -of default=noprint_wrappers=1:nokey=1 \
    "audio/s$i.wav" 2>/dev/null)
  echo "s$i: ${d}s"
done

✓ DO with the scripts

✓Copy to the project before editing
✓Run node fetch-fonts.mjs before the first render
✓Fill in AUDIO[] with ACTUAL ffprobe durations

✗ DO NOT with the scripts

✗Use Google Fonts via CDN (lint fails: google_fonts_import)
✗Use estimated durations instead of those measured with ffprobe
✗Forget ffmpeg -nostdin on Windows (file not generated)

⚙️

composition

Main generator

🔤

fetch-fonts

Local WOFF2

🎙️

narration

pf_dora 0.98

📋

Templates

Copy, adapt

🔢 The 7-step SKILL.md workflow

SKILL.md defines a required sequence. Following it in order prevents rework — each step depends on the previous one.

1 Roteiro — writes SCRIPT.md

6–9 scenes, from first principles to advanced. Short narration per scene (≈100s of voice ≈ 1:50 of video). Expand acronyms in speech: "SKILL.md" → "SKILL dot M D".

2 Projeto — HyperFrames init

npx hyperframes init <nome> --example blank --non-interactive. Copy design.md (house style) for the root directory.

3 Fontes — downloads the .woff2 latin subset

node fetch-fonts.mjs → generates assets/fonts/fonts.css. Required: lint fails if you use a font CDN.

4 Narração — generates Kokoro WAVs

Voice pf_dora --speed 0.98. Measure durations with ffprobe. Template at scripts/narration-template.sh.

5 Composição — adapts the template

Copy as build-index.mjs. Fill in AUDIO[] with ACTUAL durations. Run: node build-index.mjs (16:9) e node build-index.mjs --vertical (9:16).

6 Validar — lint + inspect

npx hyperframes lint (0 errors) and npx hyperframes inspect --samples 16 (0 issues). Fix them according to references/gotchas.md.

7 Render — draft → high

Draft first to review, then --quality high. Generates renders/<nome>-16x9.mp4 e renders/<nome>-9x16.mp4.

🚨

Required order

Step 3 (fonts) MUST come before step 5 (composition), because the template imports assets/fonts/fonts.css that only exists after the fetch. Skipping this order causes a file not found error at runtime.

📝

Script → Render

7 fixed steps

⏱️

ffprobe

Actual durations

✅

lint + inspect

0 errors before rendering

🎬

16:9 + 9:16

Always both

🧠 Progressive disclosure in practice

The design of progressive disclosure is what makes the skill efficient: Claude loads only what it needs, when it needs it.

💡 How it works in Claude’s memory

Level 1 — Always in memory: only the name e description from the skill. Claude knows the skill exists and when to use it.

Level 2 — Loaded for the task: o SKILL.md complete, with all 7 steps and links to references.

Level 3 — Loaded on demand: each file in references/ only when that specific step is being executed.

📊

Why this matters (real numbers)

~2KB

Base SKILL.md

+15KB

references/ total

3×

lighter context

⚡

Repeatable default

This design works for any complex skill: a concise SKILL.md with explicit links to specialized references. When Claude performs step 6 (validate), it accesses gotchas.md. When it builds the composition, it accesses pipeline.md. Never both at the same time without a need.

✓ Correct SKILL.md design

✓Clear and specific description (the trigger for when to use it)
✓Lean workflow with links to detailed references
✓References organized by topic (pipeline / style / gotchas)

✗ Incorrect SKILL.md design

✗Put all the contents of references/ inside SKILL.md
✗Vague description like "create videos" without specifics
✗Mix visual identity rules with execution rules

🧠

Level 1

name + description

📄

Level 2

Complete SKILL.md

📚

Level 3

references/ on demand

⚡

Light context

Faster response

🎯 Nei's user pattern

Every video production by Nei follows firm conventions — they aren’t optional preferences; they’re the channel’s signature identity.

💡 Non-negotiable conventions

→ PT-BR required: all text, narration, and captions in Brazilian Portuguese. Acronyms expanded in the voice ("SKILL dot M D").

→ Dark premium amber: palette #0D1321 background, amber as the main accent, cyan for secondary highlights.

→ Always use two formats: 16:9 (1920×1080) for YouTube and 9:16 (1080×1920) for Shorts. Both in each project.

→ Always use the INEMA.CLUB CTA: last scene of every video is "CONTINUA EM INEMA.CLUB" — already included in the template.

default narration with final CTA

# Cena s9 — CTA INEMA.CLUB (incluída no template, não remover)
write s9 "Isso é conteúdo do INEMA ponto CLUB. Acesse: inema ponto club."

# Render — sempre os dois formatos
node build-index.mjs && npx hyperframes render \
  --quality high \
  --output renders/<nome>-16x9.mp4

node build-index.mjs --vertical && npx hyperframes render \
  --quality high \
  --output renders/<nome>-9x16.mp4

⚡

Nei's voice: pf_dora

The voice pf_dora with speed --speed 0.98 is the default voice for all videos. PT-BR alternatives available: pm_alex (male) and pm_santa (formal male). The first TTS run downloads ~340MB of model data — no API key, no espeak-ng.

🚨

The INEMA.CLUB CTA is non-negotiable

Scene 9 (CTA INEMA.CLUB) is already prebuilt in the composition-template.mjs. It must NEVER be removed. It's the channel signature and part of the brand identity. Adding more scenes? Insert them before scene 9, not after.

🇧🇷

PT-BR

Always, without exception

🌑

Dark premium

#0D1321 + amber

📐

16:9 + 9:16

Both required

🌐

INEMA.CLUB CTA

Always the final scene

📋 Module 3.1 summary

What you learned

✓The exact structure of the skill’s 7 files video-explicativo/
✓The purpose of each of the 3 files in references/
✓How each script works and how it should be used
✓The 7 required steps in the workflow and their order
✓How progressive disclosure keeps context lightweight
✓Nei’s non-negotiable conventions (PT-BR, dark premium, 16:9+9:16, CTA)

Facts to remember

→Default voice: pf_dora --speed 0.98
→LEAD = 0.5s · TAIL = 0.9s · FADE = 0.45s
→Fonts: Sora 700–800 / Inter 400–600 / JetBrains Mono
→Background: #0D1321 · Amber accent · Cyan highlight
→7 files total: 1 SKILL.md + 3 scripts + 3 references

Next module:

3.2 🎨 Premium dark house style

Dive into the visual identity: palette #0D1321, Sora typography, GSAP animations, and how amber and cyan create the premium mood in INEMA.CLUB videos.

←Back to Learning Path 3 Next Module→

📂 The folder video-explicativo/