CawCut VN

The single entry point for every local VN action. The skill owns the VN conversation and sequencing — whether to open a lightweight preview or build a rough cut — and the

cawcut vn

CLI owns draft file generation and app launching.

Skill files are English-only. Match the user's language in live replies via

reply_language

, but keep this file and its references in English.

References

Read references/capabilities.md before proposing an edit. It is the authority for supported
```
cawcut vn
```
operations, flags, and editing limits. Never promise an effect that is absent there.
Read references/install.md only when packaging, opening, installing, or troubleshooting delivery to the VN app.

Never edit VN JSON by hand. Use only documented

cawcut vn

commands.

Refusing what VN cannot do

references/capabilities.md

— its Not supported list and Common refusals table — is the boundary. Check the user's request against it before proposing a style or plan, say the refusal out loud in the user's language then, and never absorb it silently into a finished draft.

Name the missing capability plainly ("
```
cawcut vn
```
cannot remove or mute the audio a source video already carries — no flag does that"), never with a hedge.
Never let a refusal read as done: no success report for an effect the CLI never applied, no describing the source media as if it had been altered, no hand-edited JSON to fake it.
Offer the closest supported behaviour, or say the media must be prepared outside this skill and re-supplied as a local file. If nothing close exists, refuse outright instead of substituting another effect, and list whatever is left unimplemented in the edit plan (phase 7).

Asking the user

AskUserQuestion

is for choices, so every call needs at least two viable options. One option is not a question — state it in prose and carry on, never padding it with a placeholder. Skip the call when the user or an upstream skill already settled the answer, and use a numbered text menu only when the tool is unavailable or the choice exceeds its cap.

Bootstrap

Run this silently before the first

cawcut

operation in an AI session:

If a
```
cawcut
```
command already succeeded in this session, skip bootstrap.
Otherwise run only
```
cawcut upgrade check --json
```
. If an update is available, run
```
cawcut upgrade
```
. If the command is missing, ask the user to install it with
```
npm install -g @ubnt/cawcut
```
.
Never run
```
cawcut auth login
```
; VN operations are local.

Workflow

Follow the phases in order. Reuse facts already established by the user or an upstream skill; do not ask the same question twice.

0. Choose the VN action

This skill is the only place that decides what to do with VN, regardless of where the media came from:

The user invokes it directly (
```
/cawcut-vn
```
or an equivalent request) and supplies their own local image/video/audio files to edit. This is a first-class path, not a fallback — do not wait for or require an upstream skill's output.
An upstream skill (
```
cawcut-generate
```
,
```
cawcut-app-run
```
,
```
cawcut-avatar-video
```
,
```
cawcut-ad-video
```
) hands off unconditionally after delivering generated media — it does not pre-filter or ask its own VN menu.

Run
```
cawcut vn status
```
— see
```
references/capabilities.md
```
for exactly what counts as "usable".
If an upstream skill or the user already stated the action (preview-only, or editing), skip the question below and jump straight to the matching branch — this is the same decide-once guard used for every other handoff.
Otherwise ask with
```
AskUserQuestion
```
, localized to
```
reply_language
```
:
- When VN is usable, offer three choices: open a VN preview and import now (recommended for a quick look), enter the editing flow (build a rough cut), not needed.
- When VN is not usable (not installed, or below
```
VN_MIN_VERSION
```
  ), omit the preview choice — offer only enter the editing flow and not needed. Do not offer a choice that cannot succeed.

Branches:

Preview and import (only reachable when VN is usable): run
```
cawcut vn import <path_1> <path_2> ... --title "<name>" --open
```
with every supplied local path. Reuse a name the conversation already established (the user named the project, or an upstream skill delivered a titled result); otherwise name it yourself from what the files are. Keep it to a few words — this is the label VN shows in its project list, not a description. Report the project URL and asset count. Stop — do not continue into the editing phases below.
Not needed: end without running any
```
cawcut vn
```
command.
Enter the editing flow: continue to phase 1. This branch never depends on VN being installed — drafting and validating a rough cut is fully local and does not launch the app.

1. Inventory the supplied media

Before creating or changing a project:

Resolve every supplied path and classify it as image, video, music, or sound effect. Record known video and audio durations and meaningful content/order cues from the conversation, an upstream generation result when present, filenames, or available local inspection tools. Never invent unseen content.
Identify missing, unreadable, duplicate, or unsupported files immediately. Note here which videos carry their own soundtrack, and check the user's request against the refusal list while the inventory is fresh — an unsupported ask must be turned down now, not discovered at build time.
Summarize the usable inventory to the user when it affects the edit.
Do not generate replacement media. If generation is required, hand off to
```
cawcut-generate
```
or
```
cawcut-app-run
```
, then resume with their output paths.

2. Confirm the project shape

For a new project, explicitly ask the user to choose

9:16

16:9

, or

1:1

. Recommend one from the stated destination, but do not create the project until the user chooses. Also establish the title, intended platform/use, and target duration when they are not already known.

For a copy of an existing draft, preserve its aspect ratio unless the user asks for a new project; the CLI cannot change an existing draft's ratio in place.

3. Recommend feasible editing styles

Style

Use the inventory and intended use to recommend a style. Offer the recommended option first and at most two meaningful alternatives:

Clean narrative — chronological or semantic order, longer readable shots, restrained
```
dissolve
```
transitions. Use
```
fade-black
```
or
```
fade-white
```
only when a transition through color is intended. Fits explanatory or product footage.
Rhythm montage — shorter usable video ranges, stronger supported transitions, and planned music/SFX cues. Offer only when enough varied footage exists; beat detection and automatic beat sync are not supported.
Photo story — paced still images and
```
dissolve
```
transitions. Fits image-heavy sets.

Adapt these rather than forcing a label. Keep every proposal within the capability reference: no manual crop/reframe, overlays, speed ramps, styled typography, audio fades, or other unsupported operations.

Before continuing, use

AskUserQuestion

to let the user select the editing style, unless they already named or clearly described one. Put the recommended style first and label it recommended. Do not silently choose a style from the inventory or defer this choice to the final plan approval — but offer only styles this inventory can actually support, and when just one fits, say so in prose instead of firing a one-option question (see Asking the user).

Canvas fill mode and transitions

references/capabilities.md

for

--scale-mode

and transition naming — apply it, do not restate its reasoning here: default to

fill

, and only switch to

fit

when the user explicitly wants the complete source frame kept visible (call out the resulting letterbox/pillarbox space in the edit plan). Do not infer

fit

merely because the source and project ratios look similar — inspect their actual pixel ratios. Always name the exact canonical transition type; never write or invoke the deprecated

fade

alias.

A transition belongs to a boundary, not a clip (see capabilities.md → Transition model). Resolve "a transition on clip X" to X → X+1 and always write it that way. Never use

add-clip --transition

; append every clip first, then set each boundary with

set-transition --index N

4. Resolve music and sound effects

Treat background music and sound effects as separate decisions.

If neither is supplied and the user has not requested silence, ask whether they want to provide local BGM, local sound effects, both, or neither.
If one category is supplied, ask only about the missing category when it would materially improve the chosen style.
If the user wants audio, wait for exact local paths. This skill does not find, download, or generate audio by itself.
Plan audio timing only after the visual sequence and approximate duration are known. Do not claim automatic beat alignment.
When an audio source is longer than the intended placement, select and show a source range using
```
--trim-start
```
/
```
--trim-end
```
(see
```
references/capabilities.md
```
for exact trim /
```
--duration
```
semantics).
Added audio never replaces audio the source clips already carry. When any supplied video has its own soundtrack and the user expects their BGM to replace it, refuse that part here (see Refusing what VN cannot do) and state in the plan that both tracks will play together.

5. Resolve text

A supplied
.srt
is a separate path. When the user hands over one or more

.srt

files, do not ask the questions below — those cues already carry their own wording and timings. Confirm only the placement (whether to shift the whole block with

--at

), show the cue count and the resulting time span in the edit plan, and import with

add-srt

. Never retype, re-time, or re-word the cues, and never split a file into individual

add-text

calls.

Ask whether the user wants text on this edit — this is a plain opt-in question and belongs in the flow the same way phase 4 asked about music and sound effects. Use

AskUserQuestion

once the visual sequence and style are settled: Add text / No text. Skip the question only when the user already requested text or supplied text content earlier in the conversation.

If they decline, do not ask again — move on to phase 6 with no text.

If they opt in (or already requested text), gather only what implementing it needs: content, timing, and type (title/subtitle/caption). Do not invent wording, timing, or type the user has not given or approved — asking whether they want text at all is not the same as proposing what it should say.

Text is an overlay and never extends the main-track or project duration. Infer the intended placement from the user's wording; do not append an end-card clip by default:

"during the final N seconds", "in the video's last N seconds", or equivalent means overlay the text on the existing final visual clip;
"for N seconds after all shots", "append a standalone end card", or equivalent explicitly sequential wording means append a separate N-second visual clip, then place the text over that clip;
when the wording could mean either, ask one focused timing question before presenting the edit plan instead of choosing silently.

Only the second case authorizes an extra main-track clip. Never satisfy an explicit "after all shots" request by shortening or covering the preceding shot. Because the CLI cannot create a solid-color clip, require a supplied end-card image or hand off its generation when that separate clip is requested.

Font selection

Every text type has a default font and point size (see

references/capabilities.md

), but once text is confirmed, ask about the font too — do not leave it silent. Skip straight to resolving the font when the user already named or described one; otherwise use

AskUserQuestion

with:

Use the default (Recommended) — the type's own default font and point size; leave
```
--font
```
/
```
--font-file
```
/
```
--font-size
```
unset.
Show me some recommendations — run
```
cawcut vn fonts --json
```
and offer up to 4 candidates (label = family + style, closest to the chosen edit style first and marked (Recommended)).
I'll provide my own font — a font name, or a local file path via the tool's free-text "Other" option (pass it to
```
--font-file
```
).

Pass the user's point size through unchanged — it is the number VN's Font Size box shows, never a canvas-relative basis. Font flag semantics and portability are in

references/capabilities.md

. Whenever the edit plan includes text, list its font and point size (phase 7).

6. Confirm the cover

For a new project, explicitly confirm the cover choice before presenting the edit plan unless the user already specified it:

a supplied PNG used as an explicit photo cover via
```
set-cover
```
;
another local PNG the user will provide; or
VN's automatic first-frame cover.

Use

AskUserQuestion

for this choice. Recommend a suitable supplied image when one clearly represents the project; otherwise recommend the automatic first frame. Do not confuse a timeline opening shot with an explicit VN cover.

7. Present the edit plan and wait for approval

Before running

init

add-clip

add-audio

add-sound-effect

add-text

add-srt

, or

set-transition

, show a concrete plan containing:

project title, aspect ratio, selected style, cover choice, and estimated total duration;
ordered shots with source path and image duration or video trim range;
each transition as an explicit boundary
```
N → N+1: <type> (<duration>s)
```
, never attached to a single clip;
only when text was explicitly requested: title/subtitle/caption content with start time, duration, font, and point size (the same number VN's text panel shows in its Font Size box);
for a supplied
```
.srt
```
: the file name, cue count, any cues the parser will skip, the resulting time span, and any
```
--at
```
shift;
BGM and SFX paths with timeline start, source trim range, duration, and volume;
every request this plan does not implement, as a named refusal or a simplification — including one already refused earlier in the conversation. Never let an unimplemented effect sit in the plan as if it were covered.

A compact timeline table is preferred for multi-shot edits. After showing the complete plan, always use
AskUserQuestion
for the generation confirmation; do not ask for approval only in prose. Offer these choices, localized to the user's language:

Create from this plan (Recommended) — approve the displayed plan and begin draft generation.
Revise the plan — collect the requested changes, update the full plan, and call
```
AskUserQuestion
```
again.
Cancel — stop without creating or modifying a draft.

Only the first choice authorizes phase 8. Do not treat silence, an unrelated reply, or a previously stated general request to “make a video” as approval. This gate is important because the CLI appends clips and does not support delete, reorder, or in-place clip editing.

8. Build and verify the rough cut

After approval:

Initialize the draft, or copy an existing draft with
```
init --from
```
.
Add clips in approved order, using video source trim where planned.
Apply the approved explicit cover when selected. Add BGM and SFX with the approved timeline start and source trim, then set every approved transition with
```
set-transition --index N
```
(never
```
add-clip --transition
```
). Add text only when it was explicitly requested and included in the approved plan, and import an approved
```
.srt
```
with
```
add-srt
```
rather than replaying its cues through
```
add-text
```
.
Run
```
show --json
```
, compare the result against the approved plan, and correct any discrepancy that the CLI can express safely. A transition discrepancy is always correctable in place with
```
set-transition
```
(
```
--type none
```
to clear) — never rebuild the draft for a transition. If correction requires removing, retiming, replacing, or reordering a clip, create a fresh draft from the approved plan.
Run
```
validate
```
. Do not report completion until it passes. Never silently drop a failed asset or substitute an unsupported effect.

9. Ask whether to open VN

Only after

show

matches the plan and

validate

passes, run

cawcut vn status

again — do not reuse the phase 0 result, since the user may have installed or upgraded VN since then (or phase 0 never checked it, because they went straight into editing).

VN usable: tell the user the rough cut is complete and ask whether to open it in VN now.
- Yes: run
```
cawcut vn project pack --open --project <dir>
```
  . If the open fails, the CLI prints why and points at a route that works on that platform — relay that rather than retrying the same command.
- No: run
```
cawcut vn project pack --project <dir>
```
  so the
```
.vn
```
  deliverable is still ready without launching the app.
VN not usable: skip the question — there is no working choice to offer. Run
```
cawcut vn project pack --project <dir>
```
directly, and mention the VN download/upgrade link as an optional aside.

Report the draft directory,

.vn

path, duration, clip/audio/text counts, and any deliberate simplifications. Do not open VN before this final choice.

Handoff boundaries

Media can arrive two ways: the user supplies their own local files directly (treat this as the normal case, not an edge case), or an upstream skill hands off its generated output. When it is the latter, trust its valid paths, reuse any settled aspect, intent, or audio decisions, and trust a pre-decided action (preview vs. editing) instead of re-asking phase 0. In either case, still present the edit plan before timeline mutation.
A request to only preview a few files, with no rough cut, is phase 0's preview-and-import branch — it stays inside this workflow, it does not hand off elsewhere.
Keep commands, flags, and paths in English; converse in
```
reply_language
```
.

cawcut-vn

NPX Install

Tags

SKILL.md Content