VN SKill for Windows

Engine selection for auto-captions:

| Engine | Model file | Size | Best for | | ------------------- | ---------------------------- | ------- | --------------------------- | | whisper_tiny | ggml-tiny.bin | ≈75 MB | Fast drafts, low resource | | whisper_base | ggml-base.bin | ≈148 MB | Good default balance | | whisper_medium_en | ggml-medium.en-q8_0.bin | 785 MB | High accuracy, English only | | whisper_medium | ggml-medium-q8_0.bin | 785 MB | High accuracy, multilingual | | whisper_turbo | ggml-large-v3-turbo-q8_0.bin | 833 MB | Best quality, multilingual |

Supported languages: auto en zh ja ko es pt ar hi id fr de ru it tr vi th pl uk nl sv fi ro cs hu he el bg hr sk sl lt lv et ms ta ur sw mk mi is hy az af

Denoise levels:

| Level | Use case | | ---------- | --------------------- | | low | Quiet background hum | | moderate | Default, general use | | high | Noisy environment | | veryHigh | Very noisy recordings |

Enable --pf (postfilter) for additional clarity at the cost of processing time.

2. Default Decision Rules

3. Response Format (MANDATORY — follow for every task)

Users interact through chat platforms (Discord, Slack, web) with no visible terminal. Send a message to the user at each key transition — when you start downloading, when you start processing, and when you finish. The user should never be left wondering what is happening.

3.1 Message Discipline

Only send messages that match the templates defined below. Everything else is internal reasoning and MUST NOT be sent to the user.

| Type of leak | Bad example | Why it's wrong | | --------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- | | Narrating actions | "Let me search for the file..." | User doesn't need to know how you find files | | Explaining decisions | "User didn't specify params, need to show options." | Internal logic, not a user message | | Referencing the skill | "According to the skill..." / "Per skill rules..." | Never mention the skill to the user | | Thinking out loud | "Now I will run compress-video..." | Just do it, don't announce internals | | Status tracking | "Options sent, waiting for reply..." | The user already sees the options | | Echoing raw metadata | "Video info: H.264, 720x968, 6.9 MB. ..." as a standalone message | Metadata belongs inside the options, not as a separate message |

3.2 Start Message — send IMMEDIATELY when you begin

As soon as you receive the user's request, send a message describing the first action you are about to take. If the input file needs to be downloaded from a URL/attachment, say so. If it already exists locally, go straight to the action.

File needs downloading:

> ⬇️ Downloading clip.mp4 — one moment.

After the download finishes, send the processing message:

> 🎬 Download complete. Starting compress-video (720p) — this may take a moment.

File already exists locally (cached from a previous request):

Skip the download message and go straight to:

> 🎬 Starting compress-video on clip.mp4 (720p) — this may take a moment.

If the CLI needs to be installed first:

> 🔧 VN Tools CLI needs to be installed first (one-time setup) — this may take a minute or two.

After installation, send the processing message as above.

auto-captions with a non-tiny engine:

Only ggml-tiny.bin is bundled. Other models download on first use. **Check whether the model file already exists** under the CLI's models/ directory.

| Engine | Model file | Download size | | ------------------- | ------------------------------------- | ------------- | | whisper_base | models/ggml-base.bin | ≈148 MB | | whisper_medium_en | models/ggml-medium.en-q8_0.bin | ≈785 MB | | whisper_medium | models/ggml-medium-q8_0.bin | ≈785 MB | | whisper_turbo | models/ggml-large-v3-turbo-q8_0.bin | ≈833 MB |

Model does not exist — mention the download in the processing message:

> 🎬 Starting auto-captions on meeting.mp4 (whisper_base). > ⚠️ *The whisper_base model (≈148 MB) will be downloaded on first use — one-time only, may add a few extra minutes.*

Model already exists:

> 🎬 Starting auto-captions on meeting.mp4 (whisper_base) — this may take a moment.

3.3 End Message — send AFTER processing finishes

One message that combines the result summary and the file delivery.

Success:

> ✅ Done — audio extracted. > Source: interview.mp4 · MP4 · 1920×1080 · 5 min 32 s · 120 MB > Output: interview_audio_20260408.mp3 · MP3 · 128 kbps · 5 min 32 s · 3.2 MB

Failure:

> ❌ Processing failed — the video file appears to be corrupted. > Error: Invalid data found when processing input

3.4 Preview delivery

Applies when the output file exceeds the platform's upload limit. Image and audio outputs are typically small — send directly. The preview flow below applies only to video.

Step 1 — Estimate preview parameters in one pass to avoid compressing twice. Target ≈80% of the platform limit for headroom:

target_size_kb = upload_limit_mb × 0.8 × 1024
target_bitrate_kbps = target_size_kb × 8 / duration_seconds

| target_bitrate_kbps | Resolution (-r) | | ------------------- | ----------------- | | ≥ 1500 | 480 | | 800 – 1499 | 360 | | 400 – 799 | 240 | | < 400 | 240 (cap at 400) |

Hard floor: never below 240p. If even 240p can't fit, skip the preview.

Step 2 — Send the preview with the summary in one message:

> ✅ Done — video captioned. > Source: meeting.mp4 · MP4 · 1920×1080 · 5 min 32 s · 120 MB > Output: meeting_captioned_20260409.mp4 · MP4 · 1920×1080 · 5 min 32 s · 85 MB > > 🎥 The full-quality file is too large to send here (85 MB, limit 25 MB). > Attached is a preview (360p, 4.2 MB). > 💾 Full-quality version saved at: C:\Users\you\Videos\meeting_captioned_20260409.mp4

If even 240p can't fit, skip the preview:

> ✅ Done — video captioned. Output is 850 MB — too large to preview. > 💾 Full-quality file: C:\Users\you\Videos\meeting_captioned_20260409.mp4

Upload failure (file was within limit): Retry once. If retry also fails:

> 💾 Upload failed after retry. File saved at: > C:\Users\you\Videos\output_20260409.mp4

4. Failure Handling

4.1 CLI install / upgrade failed

If the install script exits with a non-zero code or the CLI is still not found after running it:

1. Check the MSI log at %TEMP%\vn-tools-cli-install\vn-tools-cli-install-msi.log for details. 2. Common causes: - Network error — MSI download failed. Ask the user to check their internet connection and retry. - Antivirus / security software — may block msiexec or quarantine the MSI. Ask the user to temporarily disable it and retry. - Insufficient disk space — ask the user to free space and retry. 3. If retry also fails, provide the manual download link: > ❌ Automatic installation failed. Please download and install manually: > https://github.com/cawcut/skill-vn/releases/download/0.1.0/vn-tools-cli_0.1.0.0_windows_x64.msi

4.2 Whisper model download failed

If auto-captions fails because the Whisper model could not be downloaded:

User explicitly specified an engine (e.g. whisper_medium): do NOT silently switch. Ask:

> The whisper_medium model failed to download. Would you like to: > A. Retry downloading whisper_medium > B. Switch to whisper_tiny (built-in, no download needed, lower accuracy) > C. Cancel

User did NOT specify an engine (using default): automatically fall back to whisper_tiny and inform:

> The Whisper model failed to download. Switched to the built-in whisper_tiny engine — lower accuracy but works without downloading anything.

4.3 SRT file missing (add-caption)

If the user requests add-caption without providing an SRT file:

> Please provide the path to your SRT subtitle file.

Validate the path exists before running the command.

4.4 Invalid parameter values

The CLI enforces these constraints — validate before running:

| Parameter | Constraint | | ------------------------ | ------------------- | | compress-video -r | minimum 144 | | compress-video --fps | 1–120 | | compress-video -b | minimum 100 kbps | | compress-image -q | 0.0–1.0 | | denoise -l custom | requires -v | | cutout-video --feather | 0–100 | | cutout-video --expand | -20 to 20 |

If a value is out of range, tell the user the valid range and ask for a corrected value.

4.5 Generic failure

Summarise the error output in plain language. Suggest a next step based on the error content. If unresolvable, refer the user to § 6 Support.

5. Quick Examples

& ${vn-tools-cli} extract-audio "C:\Videos\clip.mp4" -o "C:\Output" -f mp3
& ${vn-tools-cli} extract-frame "C:\Videos\clip.mp4" -p custom -t 5.5 -o "C:\Output"
& ${vn-tools-cli} compress-image "C:\Photos\big.jpg" -q 0.8 -o "C:\Output"
& ${vn-tools-cli} compress-video "C:\Videos\raw.mp4" -r 720 -o "C:\Output"
& ${vn-tools-cli} add-caption "C:\Videos\clip.mp4" --srt "C:\Subs\clip.srt" --font-size 28 -o "C:\Output"
& ${vn-tools-cli} concat-video "C:\Videos\part1.mp4" "C:\Videos\part2.mp4" -o "C:\Output"
& ${vn-tools-cli} auto-captions "C:\Videos\interview.mp4" -e whisper_base -l en -o "C:\Output"
& ${vn-tools-cli} denoise "C:\Audio\noisy.wav" -l high --pf -o "C:\Output"
& ${vn-tools-cli} cutout-video "C:\Videos\person.mp4" --feather 5 -f mp4 -o "C:\Output"

6. Reference

For the full CLI options, all flags, and example invocations:

→ references/cli-reference.md

7. Support

> If you still need help after trying the suggested fixes, contact VN Tools support at vn.support+windows@ui.com.

8. Notes