Skip to main content
skill CX Codex

sk-narration — Claude Code skill for scripts and voiceover

sk-narration — a Claude Code skill that writes or edits short-video scripts, generates voice tracks, and runs narration checks. It activates for script, pronunciation, pacing, or voice changes and narration lint errors.

MIT ★ 204 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add howznguyen/shorts-kit --skill sk-narration -a claude-code
Open on GitHub

What sk-narration does

The skill edits src/videos/<id>/narration.json, generates speech, and checks the result with bun run lint <id>. It follows the video’s flow file to arrange lines into scenes and link factual claims to their IDs. English uses edge by default, while Vietnamese uses vieneu; a user-selected engine stays in place, and ElevenLabs is an optional alternative.

For recorded audio, it runs bun run ingest and bun run cut, then places the spoken lines into scenes. It handles fillers and retakes, and asks about unclear transcript segments. A script edit requires another bun run tts <id> run, or voice.json will still reflect the previous script. Vietnamese synthesis requires vieneu to be installed; setup commands are available in the README.

What it helps with

  • draft lines for a short video
  • correct pronunciation or pauses in generated speech
  • regenerate a voice track after script edits
  • remove fillers and retakes from a recording
  • run narration lint and inspect its warnings

Example prompts for the agent

  • Write a short-video script in src/videos/<id>/narration.json.
  • Fix this name’s pronunciation and regenerate the voice track.
  • Process my recording, transcribe it, and remove the filler words.

How to install sk-narration

1Skills CLI (Vercel)

npx skills add howznguyen/shorts-kit --skill sk-narration -a claude-code

2Manually: put the files in place

~/.claude/skills/sk-narration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sk-narration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sk-narration

How do I install sk-narration in Claude Code?

Run npx skills add howznguyen/shorts-kit --skill sk-narration -a claude-code. The skill file is at ~/.claude/skills/sk-narration/SKILL.md.

What does sk-narration do?

It drafts and edits short-video scripts, creates voice tracks, and runs narration checks. It can also process recorded speech, including transcription and cuts for fillers or retakes.

Which voice engines does sk-narration use?

It defaults to edge for English and vieneu for Vietnamese, with ElevenLabs as an optional engine. Vietnamese synthesis requires vieneu to be installed; its setup commands are in the README.

Source text

SKILL.md · MIT
---
name: sk-narration
description: Writes or edits the spoken script of a short in src/videos/<id>/narration.json, generates the voice track with bun run tts (by default Edge for English, VieNeu for Vietnamese; ElevenLabs optional), and runs the machine lint. Use when the user says "write the script", "change this line", "fix the pronunciation", "it reads too fast", "add a pause", "re-run TTS", "change the voice", or when lint reports narration errors. Also the recorded-voice path (bun run ingest, bun run cut): "use my recording", "make it from my video", "I filmed myself", "transcribe this", "cut the ums", "remove the retake", or a .mov/.mp4/.mp3/.wav file given as the voice. Steps 5, 6 and 7 of sk-pipeline.
---

# sk-narration: script, TTS, lint

**Announce:** "Using sk-narration for <id>."

Rules: §1, §3, §3b, §3c (`docs/soul/01-voice-and-structure.md`), §4
(`docs/soul/02-narration-engine.md`), the flow file in `docs/flows/`, numbers in
`docs/soul/thresholds.json`. The § wins over this file.

## Where to edit

Only `src/videos/<id>/narration.json` (schema in
`docs/making-a-video.md`). **Never hand-edit `voice.json`**: it is generated and
carries a hash of the script it was made from.

## A recorded voice (`voice.engine: "recorded"`, §5j)

There is no script to write: the lines come from the recording.
`docs/visuals/talking-head.md` holds the rules; in short:

1. `bun run ingest <id> <file> --lang <code>`; pass `--prompt` with names and terms
   said in the take. Read the review it prints.
2. Edit `cuts.json`: fillers, retakes (keep the **last** attempt), false starts, a
   call to action at the end (`tail`). Every cut has a reason; never cut a word to
   change a sentence's meaning.
3. Ask the user what was actually said wherever the review shows `?`, a number, a
   name or `⟪words missing?⟫`. Put each fix in `spelling` (whole phrase → what was
   said). Never retype `text` and never edit `transcript.json`.
4. `bun run cut <id>`, listen to `public/audio/<id>/voice.mp3`, then move whole
   line objects into the flow's beats and add `fact` (or `"claim": false`).
5. `bun run lint <id>`. Writing-style rules only warn here; the fix is a cut or a
   re-take, not a rewrite.

## Steps

1. **Read the flow file** for this video's `flow`: its beats become scenes, its
   "Traps" are mistakes already made once.
2. **Write scene by scene.** Each line is one idea; a line stating a fact carries
   `"fact": "f-xxxx"`. Hook: a number or claim in the first seconds, without
   giving away the final answer (§3c). Last line of each scene pulls into the
   next. End on the turn that negates what the viewer believed, then a share line
   tied to the content, not a logo or "follow for more" (§1).
3. **Read §3c (tension) before TTS**, not after. Re-recording costs more than
   re-reading.
4. **Write for the engine (§4).**
   - Pauses come from **full stops**. Commas, colons and dashes are nearly silent
     to TTS engines; where the viewer needs a breath, end the sentence.
   - Write numbers the way they should be spoken; put the display form in
     `spelling` (caption-only) and respellings in `pronounce` (spoken-only).
   - Silence between lines and scenes comes from `pause.line` / `pause.scene`,
     not from punctuation tricks.
5. **Engine default by language** (§4, "Pick the engine by language"): when the
   user has not chosen an engine, use English → `edge`, Vietnamese → `vieneu`, and
   say which one you used. It is a default, not a rule: an engine the user picked
   stays. If `vieneu` is not installed, give them the setup commands from the README.
6. **Generate the voice:**
   ```bash
   bun run tts <id>            # whole script in one request, word timestamps
   bun run tts <id> --force    # re-synthesise even if the hash matches
   ```
   The whole script is read in one pass so intonation carries across sentences;
   per-line synthesis sounds like a list.
7. **Listen to the whole track.** TTS engines can repeat or loop a phrase, and
   that passes every numeric check. Machines count words; only ears catch rhythm.
8. **Lint:**
   ```bash
   bun run lint <id>
   ```
   0 errors, and read every warning. Duration against `maxDurationSeconds` and
   `targetDurationSeconds`, sentence length, banned phrases, fact references all
   come from `thresholds.json`.

## Rules that bite silently

- **Changed `text` means run `bun run tts <id>` again.** Scene lengths and
  captions come from `voice.json`; a stale one drifts with no error on screen.
- **Scene length is never set by hand.** It comes from the real voice track.
- On-frame text must not repeat the line being spoken (§7); that is the caption's job.

## Verify

- [ ] `flow` and `visual` set; every fact id resolves
- [ ] `voice.json` newer than the last edit to `narration.json`
- [ ] whole track listened to, no loops, numbers pronounced right
- [ ] `bun run lint <id>` 0 errors, warnings read

Next: wording polish with `sk-style` if lint flags §3b, else `sk-scene`.

© howznguyen · MIT · howznguyen/shorts-kit

Similar skills

SKILL.md skills catalog →
document-to-narration jwynia document-to-narration converts written articles and Markdown files into video narration scripts with unified TTS audio and word-level VTT timestamps. CX Codex +1 1,000installs find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs design-taste-frontend Leonxlnx The design-taste-frontend Claude Code skill sets design rules and checks for websites. It activates for new pages, redesigns, and requests to fix a generic-looking site. CX Codex +1 802,600installs grill-me Matt Pocock grill-me interviews you about a plan or design to expose gaps and sharpen decisions. Use it before implementation starts. CX Codex +1 1,424,476installs grill-with-docs Matt Pocock The grill-with-docs skill interviews you about a plan or design and creates ADRs and a glossary along the way. Use it when decisions need sharper definition. CX Codex +1 1,219,756installs

From the same set10

The whole set →
sk-brief sk-brief — a Claude Code skill that shapes a short-video idea into a brief, choosing a story flow and visual types. It checks image licences before any script is written. CX Codex +1 ★ 204repo stars sk-style The sk-style Claude Code skill polishes spoken scripts for short videos while keeping their meaning intact. It activates on requests to tighten wording, improve flow, or remove AI-sounding phrases. CX Codex +1 ★ 204repo stars sk-render The sk-render Claude Code skill renders short videos to MP4, normalizes audio, and prepares the file for upload. It activates for render and export requests, loudness fixes, or reports of broken output. CX Codex +1 ★ 204repo stars sk-facts The sk-facts Claude Code skill checks factual claims and records research in a fact ledger. It starts when a claim, number, source, or media licence needs checking. CX Codex +1 ★ 204repo stars sk-handoff sk-handoff — a Claude Code skill that prepares a finished short for upload with a cover, encoded video, caption, and pinned comment. It runs on requests to make a thumbnail, write copy, add credits, or prepare the post. CX Codex +1 ★ 204repo stars sk-scene The sk-scene Claude Code skill builds and fixes short-form video scenes in Remotion. It activates for requests to create shots, adjust captions or motion, and check layouts. CX Codex +1 ★ 204repo stars sk-promo The sk-promo Claude Code skill builds ads, launch films, and feature teasers in vertical or landscape formats. It takes a video from the initial brief through storyboard checks and delivery. CX Codex +1 ★ 204repo stars sk-pipeline The sk-pipeline Claude Code skill guides a narrated vertical short from the initial idea to upload-ready files. It activates for new videos, editing supplied footage, or resuming a project. CX Codex +1 ★ 204repo stars

Project sponsors

Companies that keep this analytics open