autoviral

name	autoviral
description	Operator manual for the AutoViral creator workstation. Use when the user is editing video / image / poster content in AutoViral and you (any CLI agent — claude, codex, kimi, aider, gemini) need to know how to drive the Studio UI, mutate compositions, and coordinate with the user. NOT a taste/editorial skill — bring your own.

AutoViral Operator Manual

You are a CLI agent running inside the AutoViral Studio terminal panel. The user has opened a workspace at /studio/${AUTOVIRAL_WORK_ID}. You see the Studio preview + timeline to your right; the user is watching what you do.

You drive AutoViral via the autoviral CLI on your PATH. It is the agent-agnostic bridge — any of you (Claude, GPT, Kimi, Gemini) talks to the Studio through the same commands.

Read by work type (the manual is co-located, not one flat list)

The manual is split into a cross-type core plus a per-content-type subtree, so an agent editing a 图文 carousel is never force-fed a whole chapter of video composition schema (and vice-versa). Check work.type (autoviral whoami → the work's type, or the ${AUTOVIRAL_WORK_ID} work's work.yaml), then read the matching set:

Always read (cross-type core — manual/_shared/):

1. manual/_shared/00-quickstart.md — 5-minute zero-to-export walkthrough
2. manual/_shared/01-workspace-layout.md — where the files live
3. manual/_shared/03-cli-reference.md — every command you can call
4. manual/_shared/04-ui-control.md — how to make the Studio dance for the user
5. manual/_shared/05-conventions.md — naming, units, gotchas

Then read the deliverable schema for THIS work's type:

• short-video (composition.yaml) → manual/video/02-composition-schema.md — tracks, clips, keyframes, the data you mutate via autoviral clip ...
• image-text / 图文 (carousel.yaml) → manual/carousel/02-schema.md — slides, layers (discriminated union), bg, the data you mutate via autoviral carousel ...

When stuck, run autoviral docs <topic> to print any section — topics are the subdir paths, e.g. autoviral docs _shared/03-cli-reference, autoviral docs video/02-composition-schema, autoviral docs carousel/02-schema. autoviral docs with no topic concatenates the whole manual (all subtrees).

Aesthetic / taste decisions are NOT in this skill

AutoViral has no opinion on what makes a video good. It stays small by deferring to two flavors of sibling skill — invoke them on demand from the terminal or chat:

• Taste / craft — editorial-pro, viral-hooks-zh, lyric-video, etc. Tells the agent what to make: brand briefs, palette guidance, hook templates, platform-specific grammar.
• Engineering / process — mattpocock/* (to-prd, to-issues, triage, diagnose, tdd, handoff, caveman, prototype, zoom-out, grill-me, improve-codebase-architecture, write-a-skill, find-skills). Tells the agent how to collaborate.

This manual only documents how to operate the tool; what to operate it toward is the sibling skill's or the user's job.

(Note: hyperframes is NOT bundled and is no longer auto-installed. Per ADR-001, AutoViral now owns the editing layer itself and absorbs hyperframes' high-ROI techniques as native capability. Install hyperframes explicitly via npx skills add heygen-com/hyperframes if you want to use it directly.)

Recipes for common tasks

Recipes are partitioned by content type — recipes/video/ and recipes/carousel/. Read the partition that matches work.type.

recipes/video/ (short-video):

• crossfade-between-clips.md
• swap-clip-source.md
• generate-i2v-batch.md
• apply-platform-preset.md
• add-subtitle-overlay.md
• burn-subtitles-asr-aligned.md — ASR gives right timing / wrong text → substitute the ground-truth script (captions generate --script), burn a lane at export
• decouple-narration.md — one continuous locked-voice VO track over silent picture (never trust i2v embedded voice)
• beat-cutting.md — cut ~4–5s beats at native speed, one dedicated visual per phrase, no setpts slow-mo fill
• generate-cover.md — native 中文 title/subtitle/logo poster via the image endpoint, then self-check the pixels
• ingest-youtube.md — turn a YouTube URL into a 中文 short via the one-shot autoviral ingest youtube pipeline

recipes/carousel/ (图文):

• restyle-all-slides.md — restyle every slide/headline at once (globals PUT vs per-layer set-layer loop). This is also the template for new content-type recipes.

Contracts

contracts/ is the wire-level surface you can rely on:

• error-codes.md — exit codes you should branch on
• event-stream.md — every WebSocket event the Studio UI consumes (useful for power users and future MCP shims)

When in doubt

Run autoviral ask "<question>" --yes-no to consult the user via a modal. Never silently make destructive changes — render, file deletions, multi-clip swaps, anything that costs API spend or takes >10s of compute should ask first.

Environment contract (quick reference)

The terminal panel injects three env vars; if any are missing, the CLI exits non-zero with a clear message:

Var	What it holds
AUTOVIRAL_WORK_ID	The :workId segment from /studio/:workId
AUTOVIRAL_PORT	Backend HTTP port (default 3271)
AUTOVIRAL_CWD	~/.autoviral/works/${AUTOVIRAL_WORK_ID}

The CLI exits with code 2 if AUTOVIRAL_WORK_ID is unset, so autoviral whoami is a safe smoke test from any prompt.

Where the old scripts went

Before the 2026-05-14 agentic-terminal refactor, this skill carried both editorial taste content (rubrics, brand briefs) AND workstation-infrastructure scripts (subtitle burn-in, beat detection, smart crop, CLIP-based asset search, AI image generators). All of it was deleted from skills/autoviral/ to keep this skill scoped to "operator manual" only.

Nothing is lost. The full pre-refactor tree is preserved in the git tag pre-skill-rewrite-snapshot. To re-package any of it as a sibling skill:

git show pre-skill-rewrite-snapshot -- skills/autoviral/modules/<subpath>
# or to materialise into a new skill:
git checkout pre-skill-rewrite-snapshot -- skills/autoviral/modules
mv skills/autoviral/modules skills/<new-sibling-skill>/scripts
# then write a SKILL.md for the new sibling and unstage anything you don't want

Server endpoints that depended on those scripts (/api/audio/beats, /api/works/:id/rubric/:module, burnSubtitles(), buildClipIndex) now return 410 Gone or stub { stub: true, reason: "..._removed_in_refactor" } instead of crashing. They'll come back automatically if a sibling skill re-provides the scripts and you re-wire the server import paths.