Communitygithub.com

Agentchengfeng/chengfeng-videocut-skills

The sole manager of the editing environment: readiness checks (skills up-to-date → Runtime compatible), skill update activation, and Runtime installation & health checks. Used when the user says check for updates, install editing environment, install player, check editing environment, is the editing environment ready, configure transcription credentials; business skills (cut talking-heads / subtitles / visuals / export) also call this skill's readiness check in step 0. Not used for editing, subtitles, visuals, export themselves, or project data migration.

What is chengfeng-videocut-skills?

This skill is the centralized environment manager for the Chengfeng VideoCut plugin ecosystem. It handles all environment logic in one place: checking if the installed skills bundle is the latest version, ensuring the Codex Runtime is installed and healthy, and performing safe, rollback-able skill updates. Business skills (e.g., for cutting talking-heads, generating subtitles, visual editing, and export) must call this skill's readiness check as their Step 0, keeping them free of any environment logic. The skill works on macOS and Windows 10/11, supporting both a desktop app path (which bundles Bun, FFmpeg, FFprobe, and Runtime) and a pure CLI path (requiring manual installation of Node.js ≥20, Git, and optionally Google Chrome and transcription credentials). It never modifies projects, opens Studio, or transcribes media; its sole purpose is to keep the environment correct and report any issues with structured diagnostics, stopping execution if the product cannot be used safely.

Works with~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Agentchengfeng/chengfeng-videocut-skills/tree/HEAD/plugins/chengfeng-videocut/skills/chengfeng-check-updates

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Check Updates (Environment Manager)

All environment logic is written exclusively in this skill: skills version, Runtime installation and health checks. Business skills call the readiness check below as their Step 0 and carry no environment logic themselves — if the environment strategy changes, only this file is modified.

This skill does not create projects, open Studio, or transcribe any media.

Readiness Check (Business Skills Execute Step 0 from Here)

Three steps, output one of three states: Ready / New Session Required / Stop.

1. Locate Current Plugin Cache (Read-Only)

Locate from the actual source file path of this skill provided by the host: the directory two levels up from this file is <plugin root>. Use file read tools to confirm that <plugin root>/.codex-plugin/plugin.json and <plugin root>/scripts/check-plugin-update.cjs both exist. If the path is unavailable, directory level is wrong, or files are missing, stop the update comparison with installed_identity_missing; do not call codex plugin list under the user's CODEX_HOME to guess, and do not search the entire disk.

In all subsequent commands, <plugin root> is substituted with this literal path (wrap the whole segment in quotes if it contains spaces). Command blocks must not use shell variables or command substitution — the assignment syntax of bash and PowerShell are incompatible. The check script reads the installed manifest, provenance, Marketplace exact revision, and bundle digest directly from its own cache; the check phase does not depend on user Marketplace CLI output.

2. Are Skills Up-to-Date

node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json

(The Marketplace name defaults to chengfeng-videocut; if the user has configured a different name, use that one.)

  • current → Continue to Step 3
  • update_available_confirmation_required → Show installed, candidate, and the four candidate fields: version, 40-hex snapshotRevision (B), 40-hex contentRevision (A), publisherChecksum (SHA-256). Stop and wait for user confirmation; after confirmation, go to the "Activation" section below. Activation success = New Session Required: the skill text is loaded at session start, so mid-session updates do not take effect in this session; ask the user to open a new session and then continue the task.
    • If legacyInstalledIdentity=true, this indicates a one-time compatibility migration from historical 0.10.5 to the new provenance format; still use the same confirmation gate, do not require the user to pre-modify the Marketplace ref.
  • marketplace_not_found / marketplace_source_untrusted / marketplace_ref_unsafe → The current user Marketplace is missing, the source is untrusted, or the ref is not an exact 40-hex pin; do not call user Codex CLI to fix, report and continue to Step 3.
  • installed_identity_missing / installed_identity_untrusted → The current cache identity cannot be safely read or attested; do not guess version, do not activate; report and continue to Step 3.
  • installed_context_mismatch → The actual cache path of this skill, Marketplace name, or explicit CODEX_HOME is inconsistent; do not search other caches, do not activate.
  • isolated_stage_failed / isolated_stage_schema_invalid / isolated_cleanup_failed → Temporary candidate staging, CLI schema, or temporary directory cleanup failed; user HOME is zero-written, report and continue to Step 3.
  • update_metadata_untrusted → The version + B + A + SHA-256 attestation does not hold; do not activate; report and continue to Step 3.
  • candidate_older_than_installed → Downgrade prohibited, report and continue to Step 3.
  • Network unreachable or other check error → Explain briefly to the user, then continue with the current Runtime check to Step 3 — a failed update check does not block work.

Normal checking only allows discovering candidates in a temporary CODEX_HOME using the official stable ref; do not call any codex commands against the user's CODEX_HOME, and do not write configuration, Marketplace, or cache. The version directories of the current cache must all be strict semver; lower versions may remain, but only the single highest semver precedence is considered active. If a tie exists at the highest position, return installed_identity_untrusted; do not pick by alphabetical order of directory names.

3. Is Runtime Compatible

node "<plugin root>/scripts/ensure-runtime.cjs" --install-if-missing --json
  • ready → Ready, business skills continue.
    • runtime.kind=desktop-managed indicates the desktop App has installed the bundled Runtime, Bun, FFmpeg, and FFprobe into the Product's unified managed directory; Skills reuse them directly without installing extra dependencies or starting additional services.
    • runtime.kind=managed/path/source are still compatible CLI installation sources; the subsequent business contract is the same.
  • missing: The script only prompts once "Installing from GitHub Release", and automatically re-runs after SHA-256 verification completes.
  • runtime_unhealthy, installation failure, or post-install doctor failure → Stop, report structured diagnostics. Stop means stop: do not continue the workflow with a self-made review page, player, timeline, or any alternative interface. Any output produced when the product is unusable is untrustworthy (real case: when the Runtime was missing, an Agent hand-crafted a "review desk" webpage whose review decisions were completely incompatible with the product's ledger format, making the user's work useless). The only correct action: present structured diagnostics to the user, guiding them to install or report an issue.
  • runtime_capability_missing → Stop: Runtime is healthy but below the contract requirements. Report the two version numbers and the difference, guide the user to confirm and then upgrade (the upgrade replaces ~/.chengfeng-videocut/app, project data is unchanged); do not touch the existing installation before user confirmation, prohibit falling back to old editing chains.
  • During the readiness check phase, do not start services, open Studio, or create projects.

Machine Prerequisites

Supports macOS and Windows 10/11, with two installation paths:

Desktop (recommended)
  Install and launch Chengfeng VideoCut at least once
  -> The App bundles Bun, FFmpeg, FFprobe, and Runtime
  -> The user does not need to add these tools to the system PATH
  -> Skills reuse the same service via the stable entry point at ~/.chengfeng-videocut/bin

Pure CLI
  macOS     brew install bun ffmpeg
  Windows   winget install Oven-sh.Bun Gyan.FFmpeg
            After installation, open a new terminal/session for PATH to take effect

Both paths still require Node.js ≥ 20 to execute Plugin scripts; exporting subtitles/animation still requires Google Chrome. Pure CLI users install these themselves; Windows users can run winget install OpenJS.NodeJS.LTS Google.Chrome. Missing items must cause a clear stop, not a silent skip.

Skills update identity self-attestation also requires Git; Windows users can run winget install Git.Git. If Git is not executable or cannot read the origin/HEAD/commit relationships of the official snapshot, the update check fails closed, but still proceeds to Runtime checking according to the rules above.

Cloud transcription additionally requires Volcengine credentials: node "<plugin root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.

For detailed protocol, see Runtime and Product Contract.

Skills Update: Inspect and Activate

Read-only inspection of the current Plugin cache: no network, no codex calls, no writes to the user's CODEX_HOME:

node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --inspect --json

On success, returns inspected_no_refresh, containing only the currently pinned Marketplace and cache identity; no remote candidate is generated.

Isolated check with network (user explicitly says "check for updates", or readiness check Step 2):

node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --json
  • current: Reports the installed and the latest published identity found in the temporary environment.
  • update_available_confirmation_required: Shows installed and candidate four fields: version, snapshotRevision (B), contentRevision (A), publisherChecksum; stops and waits for user confirmation.
  • legacyInstalledIdentity=true: This is a compatible historical 0.10.5 cache. It can enter the normal confirmation flow above; the legacy identity is bound by Marketplace exact revision, cache directory version, manifest version, and inventory digest together. Do not ask the user to change ref first, and do not invent a separate "migration successful" state.
  • marketplace_not_found / marketplace_source_untrusted / marketplace_ref_unsafe: The current user Marketplace is missing, untrusted, or not pinned to its own exact 40-hex revision; do not auto-change ref.
  • installed_identity_missing / installed_identity_untrusted: The current cache is unrecognizable or untrustworthy; do not guess the installed version.
  • installed_context_mismatch: The script execution location is not the single highest active cache of the current Marketplace, or the explicit CODEX_HOME does not match the HOME of that cache; do not guess across directories.
  • isolated_stage_failed / isolated_stage_schema_invalid / isolated_cleanup_failed: Only states that temporary staging, CLI JSON schema, or cleanup failed; do not imply the user's installation has been refreshed.
  • update_metadata_untrusted: The temporary snapshot lacks B, A, SHA-256/manifest re-computation attestation, or the identities from manifest, Marketplace revision, and provenance contradict each other.
  • candidate_older_than_installed: Downgrade from a newer local version is prohibited.
  • Any snapshot/parse/version error: Preserve structured JSON; user HOME userMutationPerformed=false.

The script only executes the official Marketplace CLI in a newly created temporary CODEX_HOME: first adds the discovery source with marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable, then within the same temporary HOME runs marketplace upgrade to materialize a snapshot, and uses plugin list to retrieve the candidate. The 40-hex B resolved from stable, the 40-hex A from provenance, the manifest version, and the re-computable SHA-256 together constitute the candidate. Git must also prove that the temporary Marketplace origin is the official repository, HEAD=B, A is an ancestor of B, the Plugin working tree is clean, and the Plugin sub-tree from A→B only changes provenance. The temporary directory is deleted after use. The user HOME Marketplace must remain at the previously confirmed exact B; not even a read-only codex command is called against it during the check phase.

On Windows, when resolving codex / git, first look up executable extensions via PATHEXT, then try the file without extension; .cmd / .bat are wrapped via ComSpec. This prevents a Unix codex shim in the same pnpm directory from shadowing codex.cmd.

Activation Only After Explicit User Confirmation

Confirmation must occur after the user has seen the exact candidate version, B, A, and checksum:

node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --activate --confirmed --expected-version "<shown version>" --expected-snapshot-revision "<shown B>" --expected-content-revision "<shown A>" --expected-sha256 "<shown package SHA256>" --json

The script must recreate the temporary CODEX_HOME, stage a candidate from stable again, and compare all four fields with --expected-*. If the candidate drifts between staging and comparison, or any parameter mismatch, return confirmation_mismatch; user HOME is zero-written. On pass, record the exact snapshot revision and cache identity before the update, then execute against the user HOME using only official commands:

plugin marketplace remove <market name>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <market name>

<B> must be the exact 40-hex snapshotRevision that was re-staged and confirmed by the user; stable, other branches, tags, short SHA, or any different ref returns marketplace_ref_unsafe. After upgrade, the script re-reads directly from the cache and verifies version + B + A + SHA-256; only when all match exactly does it return activated. On activation success, inform the user to restart Codex or open a new session. If --confirmed is missing, return confirmation_required; if any expected field is missing, different, or if the re-staged candidate drifted, return confirmation_mismatch; both keep user HOME zero-written.

Before entering the first write command, the script re-reads the user Marketplace and active cache with CAS. If different from the old identity saved before staging, return activation_state_changed; activation does not start and user HOME is zero-written. If any write transaction step fails, the script checks the post-condition of the Marketplace and cache:

  • activation_failed_no_change: After failure, the state still exactly equals the old identity; no rollback needed, userMutationPerformed=false.
  • activation_failed_rolled_back: Candidate activation failed, but the old exact revision and old cache have been fully restored.
  • activation_cache_locked_rolled_back: Failure was identified as cache/file handle lock, and old state has been fully restored.
  • activation_failed_rollback_incomplete: Rollback failed, or could not prove that both Marketplace and cache returned to the old identity; report the actual post-condition and stop.

Only if the post-condition has changed, use the saved old exact revision to execute the official remove → add --ref <old B> → upgrade rollback, and re-read the cache directly. None of these failure states may be reported as "already updated." Do not manually copy or delete caches to fake success; do not touch Runtime, projects, media, EDL, or Studio state.

User Says "Install Editing Environment / Install Player / Check Environment"

Run the full readiness check directly; after obtaining "Ready", run a full self-test and report results as-is:

node "<plugin root>/scripts/videocut-cli.cjs" doctor --json

Report: Runtime version and location, each doctor check result, how to fix missing items (machine dependencies guide installation; transcription credentials guide node "<plugin root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>). If runtime.kind=desktop-managed, explicitly state that Bun/FFmpeg/FFprobe come from the desktop bundle and do not require modifying the system PATH. After setup, tell the user: just say "Cut talking-heads" to start.

Boundaries

  • Plugin version and Runtime version are independent; minimum compatibility and Release targets are controlled by the runtime-requirements.json contract; do not hardcode any version numbers in this document.
  • stable is only used for temporary discovery; do not write it as a persistent ref in the user's installation, and do not refer to temporary staging, legacy cache, or local directory as an activated version.
  • During the check-update phase: zero Codex calls to user HOME, zero writes; activation with rollback can only start after the user has seen and confirmed version + B + A + SHA-256.
  • Do not publish, modify project data or media; the only write exceptions are official Codex activation after user confirmation and Runtime installation.
  • Do not search for Electron .app, NSIS installation directories, or pass Electron resource paths to business skills; the desktop App is responsible for writing the stable Product entry point; Skills only recognize that entry point.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Agentchengfeng/chengfeng-videocut-skills

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

Agentchengfeng/chengfeng-videocut-skills

把剪好的口播烧成一个成片文件:账本切片段、推近、字幕、HTML 画面层,一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。

Agentchengfeng/chengfeng-videocut-skills

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

Agentchengfeng/chengfeng-videocut-skills

给剪好的口播做字幕:直接用已有的逐词稿加账本算出剪后时间(不必导出、不必重新转录)、用词典和作者文稿改写听错的专名、按句子分屏、在 Studio 里逐屏复核。用户说做字幕、加字幕、改字幕、重新分屏、字幕不对时使用。不要用于删词剪辑、物理剪切、分镜动画或成片渲染。

Agentchengfeng/chengfeng-videocut-skills

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

Agentchengfeng/chengfeng-videocut-skills

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

Agentchengfeng/chengfeng-videocut-skills

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

Related Skills