# Build Capcut Editable Project

> Build, inspect, validate, resize subtitles in, and safely install editable CapCut desktop projects from an approved edit manifest, SRT, song, photos, videos, and a CapCut sample project. Use when a user asks for a CapCut-editable version of a rendered recap video, needs missing-media diagnosis or relinking preparation, wants smaller CapCut subtitles without changing timing, or wants to continue refining a CapCut draft. Initially calibrated for macOS CapCut v8.9.1; require a fresh sample project before adapting another version.

- Skill: `haodao-culture/build-capcut-editable-project` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add haodao-culture/build-capcut-editable-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haodao-culture/build-capcut-editable-project/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: haodao-culture (https://skillmd.com/u/haodao-culture)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/haodao-culture/build-capcut-editable-project

---


# Build CapCut Editable Project

Create versioned, recoverable CapCut drafts while treating CapCut's undocumented project format and media database conservatively.

## Safety Rules

1. Read [references/capcut-8.9.1.md](references/capcut-8.9.1.md) before building, repairing, or installing a project.
2. Never edit a draft in place when it is the user's only working copy. Clone to a new version.
3. Never install or replace `root_meta_info.json` while CapCut is running.
4. Back up the live root metadata immediately before installation.
5. Do not claim media is online merely because JSON validation passes. Confirm by opening the project in CapCut; use Link Media if the private media database does not recognize generated IDs.
6. Preserve approved SRT timing exactly unless the user explicitly requests timing changes.
7. For a CapCut version other than macOS v8.9.1, first obtain a small sample draft containing one photo, one video, one text clip, and one audio clip. Build and open a 30-second test before making a full project.

## Choose the Workflow

- For a new editable project, use **Build from manifest**.
- For a project that opens with missing media, use **Diagnose and relink**.
- For subtitles that are visually too large, use **Resize subtitles**.
- For a user-edited CapCut project that needs further work, copy it to a new version, inspect and validate it, then continue from that copy.

## Build from Manifest

1. Confirm the editorial inputs are approved:
   - timeline TSV
   - photo and video index TSV files
   - synchronized SRT
   - final audio
   - title card, if the manifest uses `title`
   - rendered reference MP4
2. Ask the user to create a four-track sample project if no compatible template is available.
3. Quit CapCut and snapshot its live `root_meta_info.json`.
4. Create a flat media pack with:

   `node scripts/build_media_pack.mjs <template-or-existing-draft_info.json> <new-media-pack-directory>`

   Add any new timeline or reference media not present in that source draft before building, or build the media pack after creating a first offline draft and rebuild using the pack.
5. Create a JSON configuration using [references/project-config.md](references/project-config.md).
6. Run:

   `node scripts/build_from_manifest.mjs <config.json>`

7. Validate the offline output:

   `node scripts/validate_project.mjs <output-project-directory>`

8. Review `AI_BUILD_REPORT.json`. Confirm duration, main segment count, subtitle count, media paths, mirror equality, and chapter labels.
9. Install only after all offline checks pass:

   `zsh scripts/install_project.zsh <output-project-directory> <CapCut-draft-root> <root-meta-snapshot> <patched-root-meta>`

10. Open CapCut and confirm:
    - project appears in the library
    - timeline opens
    - media is online
    - audio and lyrics remain synchronized
    - reference track is hidden

## Diagnose and Relink

1. Run `validate_project.mjs` on the affected project.
2. Compare every missing path with the media pack. Do not rewrite paths by basename if duplicate basenames exist.
3. If JSON paths exist but CapCut still reports missing media, treat this as a private-database registration issue. Use CapCut's Link Media command and select the media-pack directory.
4. If the user provides a working CapCut revision, copy it to a new version before further automated edits. Preserve CapCut-assigned local material IDs.

## Resize Subtitles

1. Quit CapCut.
2. Copy the project to a new version and update its project name/path registration separately.
3. Run:

   `node scripts/resize_subtitles.mjs <copied-project-directory> <scale>`

   A scale of `0.6` changes 15-point text to 9-point text while preserving cue timing and position.
4. Validate all mirrors and visually check representative long lyric lines in CapCut.

## Handoff

Report:

- project name and installed path
- CapCut version used for calibration
- segment, subtitle, and duration totals
- media-pack path
- validation result
- whether CapCut itself has been opened successfully
- any remaining Link Media or manual style work

Do not describe an offline JSON-only result as a confirmed working CapCut project.