filmcraft-harness

FilmCraft Harness (built-in execution channel)

This skill is the FilmCraft skill suite'ssole execution implementation: first-time installation, native command sessions, native editing workflows, desktop sessions, and task-level sessions all converge in this directory scripts/ .filmcraft-use、filmcraft-cli and the various domain skills are thin documentation skills—they provide scenario guidance, plan examples, and reference contracts; actual execution always goes through this skill's entry points.Before executing any FilmCraft command, first set HARNESS_DIR to the directory containing this SKILL.md (the absolute path actually loaded by the host); do not assume the current working directory is the skill directory. User-level installations may be located at ~/.agents/skills/filmcraft-harness, project-level at .agents/skills/filmcraft-harness, and plugins may be located in their skills/filmcraft-harness or the host cache directory; the path actually loaded by the host takes precedence.

Six entry points

Entry point	Purpose
scripts/bootstrap.py	First-use installer: downloads and verifies the locked FilmCraft artifact, returns JSON executable; versions and digests are governed by scripts/runtime.lock.json .
scripts/cli.py	Native forwarding CLI: after installation verification, directly chains to the locked executable (--version、commands --json、describe , etc.); project reading and editing must provide an independent root argument before -- .
scripts/commands.py	Native command entry:list / describe / check / run executes the craft-command-plan/v1 plan; output is always JSON.
scripts/workflow.py	Native editing plan executor: creates a short film with subtitles from existing footage, with automatic installation, collection, save-and-reopen, export, and decode verification.
scripts/desktop.py	Fixed desktop installation entry: verifies the signed app identity and registers the local bridge; launch and GUI editing acceptance are recorded separately.
scripts/task_session.py	Task-level JSONL session entry: launches one editor instance, checks, saves, and reworks each plan; exits only when the task ends.

Usage

Domain skills (filmcraft-use , etc.) provide scenario guidance and plan examples; execution paths always use this directory's HARNESS_DIR/scripts/. Public workflow.py and commands.py run must explicitly provide --read-root READ_DIRECTORY --write-root WRITE_DIRECTORY(repeatable); the root must be an existing canonical real directory, authorized by the user/host. The installation scope is the user data directory; sudo is not required:

: "${SKILL_DIR:?请先设置为本 SKILL.md 的实际所在目录}"
python3 -I -B "$HARNESS_DIR/scripts/bootstrap.py"

Native command direct connection and command directory query (output is always JSON):

python3 -I -B "$HARNESS_DIR/scripts/cli.py" -- --version
python3 -I -B "$HARNESS_DIR/scripts/commands.py" list --filter <关键词>
python3 -I -B "$HARNESS_DIR/scripts/commands.py" describe COMMAND_ID

Native editing plan (plan and example files are taken from the corresponding domain skill directory):

: "${READ_ROOT:?Set READ_ROOT to an existing independently authorized directory}"
: "${RUNTIME_HOME:?Set RUNTIME_HOME to an existing independently authorized directory}"
: "${WRITE_ROOT:?Set WRITE_ROOT to an existing independently authorized directory}"
python3 -I -B "$HARNESS_DIR/scripts/workflow.py" --plan PLAN.json --output /absolute/new-result \
  --read-root "$READ_ROOT" --write-root "$WRITE_ROOT" --runtime-home "$RUNTIME_HOME"

Task-level sessions (consecutive operations share the same FilmCraft instance) and desktop installation are described in task_session.py --help and desktop.py --helprespectively; permission boundaries are enforced by scripts/execution_permissions.py , and native subprocesses run within the macOS system sandbox. For specific tasks, first read this skill's task template, and execute according to the corresponding inputs, first task, failure boundaries, local revisions, and verification.

Relationship between domain skills and this harness

• filmcraft-use: complete task routing and delivery contract; execution still goes through this harness.
• filmcraft-cli With each scenario skill (setup/project/media/timeline/audio/subtitles/color/motion/export/multicam/transcript): scenario knowledge and parameter contracts; execution still goes through this harness.
• In domain skill documentation, SKILL_DIR refers to the domain skill's own directory (used to read its examples/、references/); script execution paths are all replaced with this directory HARNESS_DIR/scripts/。
• Execution contracts (command directory, parameter contracts, and skill routing) are found in each domain skill's references/command-usage.md and command-reference.md; this skill's references/ stores an execution contract snapshot (command-coverage.json、native-command-snapshot.json）。