| 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/):
- manual/_shared/00-quickstart.md — 5-minute zero-to-export walkthrough
- manual/_shared/01-workspace-layout.md — where the files live
- manual/_shared/03-cli-reference.md — every command you can call
- manual/_shared/04-ui-control.md — how to make the Studio dance for the user
- 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.mdswap-clip-source.mdgenerate-i2v-batch.mdapply-platform-preset.mdadd-subtitle-overlay.mdburn-subtitles-asr-aligned.md — ASR gives right timing / wrong text → substitute the ground-truth script (captions generate --script), burn a lane at exportdecouple-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 fillgenerate-cover.md — native 中文 title/subtitle/logo poster via the image endpoint, then self-check the pixelsingest-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 onevent-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>
git checkout pre-skill-rewrite-snapshot -- skills/autoviral/modules
mv skills/autoviral/modules skills/<new-sibling-skill>/scripts
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.
