Agentchengfeng/chengfeng-videocut-skills

Cut Voice-Over

From a single video to a human-reviewed cut ledger (Cuts + EDL) without touching media files. Seven linear steps:

0  Ready      Readiness check via "Check Updates" (this Skill has no environment logic)
1  Setup      Real video → cloud word-by-word transcript → product creates project → start service → read back state
2  Correct    Dictionary fixes characters (general + user) → produce correction table
3  Mark       Read preferences & rules → five-pass scan, each pass finds one type, only logs rows
4  Summarize  Deletion summary table + repeated sentences table → self-verify by reading aloud
5  Review     Full submission → present both tables to user → open Studio for manual review
6  Retro & Handoff  Compare proposal vs final → archive three drawers → report four things

No media cutting: altering the ledger takes tens of milliseconds; cutting creates an irreversible file. When this Skill finishes, there are zero new videos on disk. The Skill handles semantic judgment and orchestration; the product Runtime is the sole writer of projects, Cuts, and Studio state.

The user only speaks in three places: continue or restart the same-source project (only when previously cut), Studio review, and completion confirmation. Everything else is one-way reporting without pausing for replies. The completion criterion for each step is its deliverable: no table produced means not done.

First read and execute the Business Skill Stage Contract. This document's steps map to contract stages as follows: 1=preflight+Product state readback, 5=proposal+Product CAS, review=project-level review binding. The three post-review stages (confirmation, execution, acceptance) belong to the export Skill.

Incidents behind each rule are in the Incident Log—rules in the main text, stories over there.

0. Ready

First execute the "readiness check" from Check Updates—whether skills are up to date and the Runtime is compatible; the plugin root is also located there (all <plugin root> references in this document substitute that literal path). Only proceed if "Ready" is returned; for "Needs New Session" or "Stop," follow its disposition (including the prohibition on creating custom alternative interfaces).

If the readiness result is runtime.kind=desktop-managed, it shares the same stable entry point and launchd/windows-task service as the CLI installation; continue directly without searching for Electron installation directories, installing a separate Bun/FFmpeg, or starting a second Runtime.

1. Setup: Real Input → Transcription → Product Project Creation

What it does: Submit the user's local real video and cloud word-by-word script to the product, atomically create the project, start the service, and read back the state.

# After cloud word-by-word transcription (generates transcript candidates in the task directory):
node "<plugin root>/scripts/videocut-cli.cjs" project create "<project directory>" --video "<video file in task directory>" --transcript "<word-by-word script in task directory>" --json

node "<plugin root>/scripts/ensure-running.cjs" --json          # Product declaratively ensures the daemon service (5190)

node "<plugin root>/scripts/videocut-cli.cjs" workflow get "<project directory>" --json    # Product state readback
node "<plugin root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json

Rules:

• Only accept real voice-over videos or existing real projects provided by the user; stop if no real media is provided, and never use examples or placeholder videos as substitutes
• Transcription must use the currently authorized cloud ASR; do not fall back to local ASR; if no cloud ASR is available, report missing_cloud_transcription_adapter, do not open Studio, and do not fabricate a transcript
• --video / --transcript must be real files within the task directory; do not pass aspect ratio—the product derives it automatically from the video's actual dimensions (Runtime 0.4.4+). Only add --aspect-ratio W:H when the user explicitly requests a specific aspect ratio
• For existing canonical projects, first inspect to confirm and reuse them; do not create a duplicate projectId; when the same video has been cut before, ask the user: continue where you left off, or start over (this is one of the three speaking points). project prepare is an idempotent compiler used only when resuming an interrupted process or when explicitly refreshing; if interrupted, simply rerun
• project create is the sole entry point: do not go through a media library, upload session, or another Skill; the Skill must not write project.json itself
• The service must be confirmed by the script with healthy=true, runtimeMode=launchd (macOS) or runtimeMode=windows-task (Windows), version compatibility, and URL canonical to 5190 before proceeding; on failure, pass through the structured error and stop, do not fall back to foreground, change ports, or kill unknown processes
• Both readbacks must refer to the same projectId and save the workflow stage along with Project / Cuts / EditList revisions; stop if missing or inconsistent

2. Correct: Fix Characters, Produce Correction Table

What it does: Before any deletion judgment, use dictionaries to correct transcription misheard characters—wrong characters make all subsequent judgments wrong; misheard characters are not redundant speech and cannot be fixed by deletion.

node "<plugin root>/scripts/videocut-cli.cjs" transcript dictionary "<project directory>" --dictionary "<plugin root>/references/ai-term-dictionary.md" --json

Use your file tools to check whether $HOME/.chengfeng-videocut/dictionary.md exists; if it does, run it again (transitional approach: CLI currently accepts only a single file, so run twice; it can only supplement, not undo, the previous pass—full multi-dictionary merging with user priority will come with a later CLI release):

node "<plugin root>/scripts/videocut-cli.cjs" transcript dictionary "<project directory>" --dictionary "$HOME/.chengfeng-videocut/dictionary.md" --json

Deliverable: Correction Table—merge the applied lists from both calls into a small table (original word → corrected to → context), report it to the user. You must review this table after correction—dictionaries can make wrong corrections without context; when you see a mistake, fix the dictionary, not elsewhere with patches.

Only when the dictionary cannot resolve the issue and the author has a script in hand, add one additional context alignment:

node "<plugin root>/scripts/videocut-cli.cjs" transcript align "<project directory>" --script "<voice-over script file>" --json   # Report only, no changes
node "<plugin root>/scripts/videocut-cli.cjs" transcript correct "<project directory>" --file "<correction file>" --json

Rules:

• Only change text, not timing, word count, or wordId—the product compares word-by-word timestamps; changes are rejected outright
• Only change phrasing, not meaning—truly said wrong and then repeated belongs to false starts/speech corrections, handled by deletion
• If the dictionary doesn't have it and the script can't confirm it, never guess: report it for the user to add to the dictionary. Inserting a fabricated word is worse than leaving a misheard word
• Preserve spoken Chinese as-is: if they say "叉" or "大模型," that's what they said
• The dictionary is a gate that must be passed for every transcription (the same audio transcribed twice can give different results; see the incident log)

Segment the script by punctuation: each word in the transcription carries punctuation; the script breaks at every comma into a paragraph, every period into a line; subtitles use the same punctuation, ensuring consistent breaks between both. Projects created before 2026-07-28 lack punctuation; run node "<plugin root>/scripts/videocut-cli.cjs" transcript regroup "<project directory>" --json to re-segment paragraphs (per-word verification of id/time/text remains unchanged, safe for already-cut projects); if punctuation is absolutely needed, re-transcribe—punctuation simply does not exist in old transcriptions.

3. Mark: Five-Pass Scan, Each Pass Finds One Type

What it does: Read the materials, then read the full playback order five times, each time with only one criterion. Carrying one criterion per pass yields much higher judgment quality than carrying six at once; each pass produces small, verifiable output.

First, read the materials:

node "<plugin root>/scripts/videocut-cli.cjs" transcript playback "<project directory>" --json

Then read $HOME/.chengfeng-videocut/cut-preferences.md with your file tools (user preferences, their word is final; if the file doesn't exist, the user is new; skip it).

Criteria in Semantic Deletion Rules (principles + cases). Priority: User preferences > User cases > General cases.

Pass 1  Redundancy       Repetition between sentences, within sentences (most objective: two identical utterances)
Pass 2  False starts & self-corrections   Said halfway, stopped, restarted with a different phrasing
Pass 3  Speech errors & retries   Wrong numbers, proper nouns, words, with correct retry following
Pass 4  English hesitation      Word / letter / syllable repetitions
Pass 5  Filler words & verbal tics   Most subjective, based on user preference density and tolerance

Each pass has a fixed action: consult cases for the current type → find one instance and log a row (wordIds + type + risk) → do not decide on other types. In subsequent passes, skip already marked words; resolve conflicts during summarization.

Rules:

• Judgment must use only transcript playback's playback order; never piece together from transcript.json yourself— "said twice" relies on adjacency in playback; self-assembling may misinterpret skipped IDs as missing content and incorrectly reject (see incident log)
• Deletion has only two states: "delete / not delete"; AI reasons do not form a third "suggest delete" state
• Speech errors, redundancy, false starts: default to delete the first occurrence and keep the last; long sentences, full sentences, branching retells must be high-risk review
• Ordinary pauses are not computed by the Skill: adjacent silence merging and natural-pause-v2 are handled deterministically by the product

4. Summarize: Two Tables, Act Only When Tables Are Ready

What it does: Merge the five-pass rows into two tables—this is the deliverable of this step and what the user will see.

Deletion Summary Table (per-item deletion decisions):

| # | Time   | Type           | Delete              | Remaining reads as        | Risk | Basis      |
|---|-------|----------------|---------------------|---------------------------|------|----------|
| 1 | 00:12 | Redundancy     | 这个功能呢          | 这个功能它其实             | Low  | Case R2   |
| 2 | 02:31 | Self-correction| 比如我就让他跟踪     | 比如我让grok跟踪           | High | Case R5   |

Repeated Sentences Table (sentences said multiple times; the word-by-word table cannot show "how many takes, which one is kept," which is exactly what users most want to verify):

| Sentence (start)      | Times said | Take kept      | Takes deleted  | Risk            |
|-----------------------|------------|----------------|----------------|------------------|
| 因为今天有什么…        | 3          | Take 3 00:08   | Takes 1, 2     | Low—three takes mostly identical  |
| 多数Agent能搜…        | 2          | Take 2 04:40   | Take 1         | High—two takes differ significantly, listen carefully |

Then self-read: read the full post-deletion text in playback order according to the table; revoke any row that doesn't read fluidly. This is the definition of review: the AI itself re-checks, not asking the user; uncertain = do not list (two states).

5. Review: Only Open Studio for Manual Review

What it does: Submit the full proposal, present both tables to the user, then open the product review page for the user to manually verify.

node "<plugin root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json              # Get Cuts' own revision
node "<plugin root>/scripts/videocut-cli.cjs" cuts set "<project directory>" --file "<proposal file>" --expected-revision "<current Cuts revision>" --json

The proposal only references stable wordIds:

{
  "schemaVersion": 1,
  "cutWordIds": ["word-12", "word-13"],
  "reasons": [
    { "wordIds": ["word-12", "word-13"], "kind": "repeat", "risk": "low" }
  ]
}

Submission rules:

• The proposal is the full conclusion of this round's judgment, not an incremental diff—cuts set uses replacement semantics; passing an incremental diff will silently discard the previous round's semantic deletions (see incident log); when submitting a proposal, do not read or manually merge initialization.baselineCutWordIds (the product automatically merges pause baselines)
• reasons are persisted as-is; the product will drop references to non-deleted words
• Do not directly write cut-selection.json, project.json, or event logs
• cuts get.data.revision is the Cuts revision; workflow get.data.revision is the project revision; never mix them up
• After successful submission, always check noLongerCut (words no longer marked for deletion this round): if nonzero and not an intentional rollback = you submitted an incremental diff, go back and resubmit the full set; also read it when it says "unknown"
• Then immediately run workflow get + cuts get again, confirm cut_review_ready and all three revisions; stop on any inconsistency; never directly write JSON or auto-overwrite
• After submission, leave <proposal file> in the task directory—step 6 retrospection needs it (reasons may be trimmed by the product after user editing, making post-hoc reverse lookup unreliable)

Then present the tables first, then open the page: send both tables to the user, then let them enter Studio with the tables in hand.

node "<plugin root>/scripts/ensure-running.cjs" --json                    # Idempotent ensure before opening
node "<plugin root>/scripts/videocut-cli.cjs" open "<project directory>" --json          # Get product-returned project URL

node "<plugin root>/scripts/ensure-studio.cjs" --url "<product project URL>" --view koubo --json                                  # Capability gate: confirm 5190 registered koubo view

Rules:

• Only when the gate returns ok=true, use the Codex built-in browser to open studio.url, then stop automatic progression and wait for the user to select words, restore, and save
• Before opening, strictly compare the productUrl's #project/<projectId> with the readback's projectId, and bind stage=cut_review_ready with all three revisions—ok=true only proves the product-side capability; it cannot replace project-level binding; on any inconsistency, re-readback
• studio_capability_missing: stop and explain version incompatibility; optionally suggest $chengfeng-report-bug; do not assume the new interface exists just because the URL contains ?view=koubo; do not fall back to old task panels
• Do not treat "open workbench" as the first step of the task; do not access old review.html, 8898/8899; do not control Studio DOM or directly manipulate media elements; do not create standalone audio tracks or placeholder subtitle tracks

6. Retro & Handoff: Never Discard User Edits

After the user completes review, read back:

node "<plugin root>/scripts/videocut-cli.cjs" workflow get "<project directory>" --json
node "<plugin root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json

Retrospection (transitional approach; will be replaced by the product's cuts diff command): Compare the <proposal file> saved in step 5 with the final cutWordIds read back:

• User restored (in proposal but not in final) = AI deleted incorrectly. Ask: which type did I get wrong, based on the reason I wrote in the proposal?
• User added (in final but not in proposal, and not in initialization.baselineCutWordIds pause baseline) = AI missed it. Ask: which type is this, and why didn't I recognize it? (The baseline is only used here to filter out pause words; still prohibited from merging it into the submission)

Archive three drawers:

• Taste differences → append to ~/.chengfeng-videocut/cut-preferences.md (Agent-maintained markdown, only append and rewrite its own section; create file if it doesn't exist)
• Proper noun errors → append to ~/.chengfeng-videocut/dictionary.md (two-column table, deduplicate before appending)
• Rule gaps → add an entry in the preferences file's "Cases Pending Upgrade" section; when the same type appears a third time, report to the user suggesting an upgrade to general cases (only modify the skills repo after human review)
• Zero differences: still record one line in the preferences file's project record: "Fully adopted"

Report four things: number of words deleted, seconds removed; current stage (should be cut_review_ready); project / Cuts / EDL three revisions; retro summary (proposal N items, adopted X restored Y added Z, one sentence on the main disagreement). Then tell the user the next step is export.

Do not show a confirmation card, do not execute cutting—the physical cutting confirmation card belongs to the export Skill; that card must freeze the revision at the moment the user presses confirm.

return_cut_review: First run node "<plugin root>/scripts/ensure-running.cjs" --json again, then return to the same Studio to continue review; do not trigger retrospection; retrospection is only done once at the final handoff.

Report grading: Product structured revision is API/readback PASS; real browser frame review is visual frame PASS; if no one actually listened, it is human listening UNVERIFIED; do not substitute with playback, DOM, screenshots, or media probes.

Recovery & Failure

• revision_conflict: Re-read the state, explain the user's recent edits, do not auto-overwrite
• runtime_unhealthy: Do not loop reinstalling
• service_identity_mismatch / service_port_conflict: Stop, do not fall back to foreground, do not change ports, do not kill unknown processes
• Page closed but service still running: Read the workflow and continue from the current state, do not create a new project
• Any failure must not report "the ledger has been written" as "already cut"—up to this point, no media files have been produced

Note: This Skill accepts local real video and cloud word-by-word script directly entering the product; this is the requirement of the contract preflight stage; the real existence of both is the prerequisite for all judgments.