CapCut CLI — AI-Editable Video Draft Editing
A single CLI that reads and writes local CapCut/JianYing drafts directly — subtitles, timing, speed, volume, templates, long-form-to-shorts — with no API or server required.
Evidence shows strong safety design: every write is conflict-checked, atomic, with .bak plus rolling history snapshots and a `capcut restore` command; `--force-write` requires explicit user acceptance; `--dry-run` previews mutations; batch writes are transactional by default; Wikimedia downloads are license-classified with restrictive licenses refused unless `--force-license`; non-Wikimedia URLs refused before any network call. Deductions: writes directly to user project files (broad write surface, mitigated by backups); anim.sh hardcodes a macOS-only JianYing cache path with cross-platform behavior unverified; publisher identity unverified. No red-line risk found.
The repo ships a real CI workflow (Node 18/20/22 matrix, build+test+lint) plus a committed smoke-test suite (_test.sh) covering the skill's key paths — animations, ken-burns, masks, text-ranges, import-srt, --jianying namespace, Wikimedia refusal and the license classifier — with JSON-level assertions including negative (rejection) branches, so the static ceiling is lifted. Deductions: nothing was executed in this review; the type-detection test passes with a fake .jpg, indicating lenient validation; pitfalls.md itself flags the Windows effect-cache path rewrite as 'unverified', and the hardcoded macOS EFFECT_CACHE_BASE is a diagnosability gap.
Trigger conditions are explicit in the description (capcut, jianying, subtitles, draft_content., etc.); scenarios are clear (subtitles, timing, speed, templates, long-to-short); JianYing/Chinese namespace support is strong (--jianying, Chinese member-name slugs, Chinese docs, JianYing-first quickstart); core function is fully local with no dependency on overseas services (Wikimedia is an optional input). Deductions: some boundaries live in externally linked docs (e.g., JianYing encryption support); the first-open online effect-catalogue fetch is not adequately declared as an environment constraint.
Documentation is well layered (SKILL.md → references → scripts → assets progressive disclosure), MIT license explicit, versioned 0.22.0 with CI, changelog references, trademark disclaimer and demonstrated maintenance responsiveness. Deductions: SKILL.md self-describes as v0.11 while the repo is 0.22.0 — the skill lags the current command set (compile/diagnose paths), a versioning inconsistency; private project names like `knossos-recon` appear unexplained; the sponsor-tier governance model can fork docs from free functionality.
The value claim is clear: no API, zero runtime deps, output is a real CapCut/JianYing draft that stays editable — high marginal value over hand-editing JSON; tests assert structurally correct outputs (animation entries, keyframes, text segments). Scored at the static ceiling of 7: direct usability was not independently executed, and pitfalls.md itself warns that a valid JSON write is not proof an effect renders, so visual confirmation is still needed.
Primary material is auditable: committed test script, CI workflow, reproducible assertions, and pitfalls.md distinguishes 'verified (CapCut macOS 8.5.0 beta)' from 'unverified' claims — a good fact/inference separation. Deductions: no independent execution in this static review; key claims such as the 'empirically-verified effect_ids' rest on the author's account of a third-party project, with limited cross-source corroboration.
- Close the project in CapCut/JianYing before any write or your edits may be overwritten; recovery relies on .bak (one step) and capcut restore.
- anim.sh hardcodes a macOS-only effect cache path; cross-platform cloning to Windows is self-documented as unverified.
- SKILL.md self-describes as v0.11 while the repo is at 0.22.0 — the skill docs lag the current command set; publisher identity is unverified by FollowSkills.
- A valid JSON write is not proof an effect renders (pitfalls.md warns alpha keyframes do nothing); visually confirm in CapCut.
- First use of a not-locally-cached animation/effect requires CapCut to fetch resources from its online catalogue.
- --force-license bypasses the license refusal and puts copyright responsibility on the user; fixtures from versions ≤0.17.2 contain device identifiers — always run the latest version.
What does this skill do, and when should you use it?
capcut-edit is an Agent Skill wrapping capcut-cli, letting an AI assistant edit CapCut / JianYing project drafts from the terminal. It works directly on the local draft store's JSON files (e.g. draft_content.): JSON in, JSON out, with no uploads, no MCP server, no HTTP daemon. The result opens in CapCut with every track still editable — not a flattened export. It is an independent community project, not affiliated with ByteDance.
Reads and parses local CapCut/JianYing draft JSON (v0.11+ synchronizes every readable timeline target: draft_content., draft_info., draft_meta_info., template-2.tmp). Supports: batch subtitle text fixes, timing shifts, speed, volume, opacity, trim; SRT import/export, Whisper-powered karaoke captions, multi-language draft clones via translate; transitions, masks, intro/outro animations (fade, Ken Burns); cutting long-form into shorts stamped with a title and CTA; compiling an entire draft from a JSON spec (compile); low-res FFmpeg proxy previews (render); and capcut serve for JSONL-queue batch automation. Every write is atomic with a .bak backup and rolling history snapshots.
- Content creators with a backlog of raw long-form recordings who want AI to cut them into captioned short-video drafts for final human review and publishing in CapCut
- Subtitle or localization teams batch-correcting subtitle text inside existing projects, or importing SRT files into a JianYing project
- Automation operators driving bulk draft generation through n8n / Make / Coze via the capcut serve JSONL queue runner
- Podcast or talking-head producers auto-generating karaoke word-level captions with Whisper, or detecting fluffed retakes (detect-retakes)
- Template-driven teams applying saved text-style presets and layouts via compile specs to mass-produce new drafts
What are this skill's strengths and limitations?
- Zero dependencies, no server: JSON in/out against the local draft store, no project files uploaded
- Output is a real, editable CapCut/JianYing project with live tracks, not a flattened render
- Atomic writes with .bak backups, conflict checking, and a guard against writes while the editor is open
- JSON output by default (pipe to jq and scripts), plus -H human-readable and -q quiet modes
- MIT licensed, well documented (command reference, version support, Chinese quickstart), with CI and a test script
- Requires a local CapCut/JianYing desktop draft store; unusable where the desktop app doesn't exist
- render is only a low-res FFmpeg proxy preview, not CapCut's final render
- Reverse-engineers a proprietary format, so new app versions can introduce compatibility risk (though the project tracks versions actively)
- Some features depend on optional tools: Whisper, FFmpeg, ANTHROPIC_API_KEY (translate); without them the matching commands are unavailable
- The Wasm read-only sandbox mode is explicitly experimental
How do you install this skill?
- Install the CLI: npm install -g capcut-cli (or run without installing via npx capcut-cli <command>). Requires Node >= 18, built-ins only. Optional: Whisper (caption), FFmpeg (render), ffprobe (media metadata), ANTHROPIC_API_KEY (translate). 2. Place the skill folder at skills/capcut-edit/ (with SKILL.md). 3. Verify with capcut doctor to check installed media/transcription capabilities. Note: upgrade to 0.18.0+ — older versions had security issues (see #59 and the changelog).
How do you use this skill?
Triggers when the user mentions capcut, jianying, subtitles, video editing, or draft_content.. Typical flow: explore progressively (capcut info <project> -H for overview, capcut segments for timing, capcut segment <id> for detail), then batch-write, e.g.: echo '{"cmd":"set-text","id":"a1b2c3","text":"Fixed"}' | capcut batch <project>. Key conventions: close the project in CapCut before editing and reopen after; writes are transactional (one failure writes nothing); time formats include 1.5s, 500ms, +0.5s, 1:30; IDs match by the first 6+ chars of the UUID. Multi-command recipes should run as parameterized scripts in scripts/, not ad-hoc sequences.
How does this skill compare with similar options?
Unlike cloud-based video automation tools that re-encode footage, capcut-cli edits the local editable project itself; the final render and publish click stay in CapCut. The same author ships draftcat (Go, MIT) as a sibling project for governed AI pipelines. Related ecosystem projects include OpenChatCut and pyCapCut (whose material-registration bug capcut-cli's register --materials fixes). It is unrelated to any official CapCut API — the project explicitly requires none.