AGENT INTEROP · EDITABLE PROJECTS

The Skill Should Travel. The Video Project Should Stay Editable.

An Agent that can produce an MP4 has completed a render. It has not necessarily completed an edit. The harder standard is to preserve the timeline another person can reopen: clips still have identities, captions still point to voiceovers, source offsets still describe the original media and every change remains inspectable. Timeline Studio's video-editing Skill is being packaged for Codex, Claude Code, Copilot and Gemini CLI around that standard. The surfaces differ, but the project contract does not. One Skill chooses among a versioned command runner, a visible browser workflow and a portable .timeline archive without pretending those paths have identical guarantees.

The Skill Should Travel. The Video Project Should Stay Editable. visual guide

CHECKLIST

Practical review checklist

  1. 01Keep the editable .timeline archive as the primary deliverable; treat the rendered video as an output of that project.
  2. 02Route work by capability instead of assuming every Agent surface can execute the same commands.
  3. 03Dry-run command plans and reject stale base revisions before changing an existing project.
  4. 04Give every operation a stable ID so a retry cannot move or rewrite the same clip twice.
  5. 05When browser automation is required, describe it as UI operation and verify visible state rather than claiming determinism.
  6. 06Inspect sound as well as track geometry, including embedded video audio, separated source audio, voiceovers and music.
01

A Skill is the portable part, not the illusion of one universal runtime

Codex, Claude Code, Copilot and Gemini CLI do not share one execution environment. They expose different filesystem access, browser control, approval models and installation conventions. A useful Skill therefore cannot be a long prompt that assumes a particular button, shell or hidden API exists everywhere. Timeline Studio keeps the transferable layer focused on editorial rules: preserve the user's brief, inspect media before changing it, keep the main visual sequence coherent, treat captions and audio as timed clips, save before destructive work and verify the reopened result. Those rules travel. The Skill then discovers which execution path the current environment can actually support.

02

The first routing decision is local repository or hosted editor

When the source repository is present and the task concerns unpublished code, evaluation or a local project, the Skill starts the local editor and reads the URL Vite actually prints. It never assumes port 5173, because a busy development machine may select another port. When no repository is provided or the user explicitly wants the website, it treats video-editor.ai-creator.top as the canonical hosted editor and inspects the visible UI before planning. This distinction protects two different truths: local work must reflect the branch being developed, while public workflows should reflect the version users can reach.

03

The command runner earns priority by offering stronger guarantees

Before reaching for browser control, the Skill inspects package.json for a real Agent command script. Timeline Studio now exposes npm run agent with inspect and run subcommands for existing .timeline archives. That path is preferred when every requested operation is registered because it can address stable clip IDs directly, validate finite second-based timings and return structured results. A browser can reproduce many of the same visible actions, but it cannot promise the same idempotency or transaction boundary. Choosing the command runner is not about avoiding the interface; it is about using the highest-fidelity contract the current operation supports.

04

A JSON plan separates editorial intent from transport

The plan envelope declares schemaVersion, project path, baseRevision, dryRun state, an ordered operation list and output artifacts. Each operation carries its own ID and typed arguments. That representation is deliberately transport-neutral: the CLI uses it today, and a future MCP server should call the same registry rather than implement a second editing engine. The React interface can eventually dispatch the same commands. If all three surfaces share reducers and validation, moving a voiceover in a terminal, through MCP or with a pointer will preserve the same linked-caption behavior instead of producing three subtly different project states.

05

Revision checks stop a polite Agent from overwriting newer work

A plan is written against a known project revision. If another person or process edits the archive before the plan runs, baseRevision no longer matches and the command engine returns REVISION_CONFLICT without applying the batch. This is optimistic concurrency in a form that makes sense for creative work. The Agent does not need to lock the project for the duration of its reasoning, but it must prove that the assumptions it inspected are still current before writing. The correct response to a conflict is to inspect again and recompute the plan—not to quietly force an old arrangement over a newer human decision.

06

Operation IDs make retries safe

Agent workflows encounter timeouts, interrupted shells and ambiguous download events. A caller may not know whether a command finished and may send it again. Timeline Studio records appliedOperationIds inside project.json. When the same operation ID appears in a later plan, the engine skips it and returns the existing revision instead of moving the clip twice. This idempotency belongs in the project rather than in one terminal session, so it survives archive handoff. The rule is simple but consequential: an operation ID identifies one editorial intention, not merely one request attempt.

07

Transactions protect linked media relationships

The first command registry is intentionally narrow. It can move serialized voiceover clips, update caption text and timing, and unlink or relink captions to audio. Moving a voiceover also shifts its linked captions by the same delta. A multi-operation plan is applied to a structured clone, and one invalid clip or range rejects the batch without changing the input project. This matters more than command count. Video state contains relationships that a naïve file rewrite can break: caption timing, source-media offsets, track order, asset identity and audio linkage. A small registry with atomic behavior is a better foundation than a broad list of commands that can leave half an edit behind.

08

Dry run turns an Agent proposal into something reviewable

Setting dryRun to true applies the plan in memory, returns before-and-after project summaries and writes no archive. The current summary reports revision, calculated duration, aspect ratio, track counts, prior operation IDs and warnings such as missing serialized voiceover clips. It is not yet a frame-accurate visual diff, but it makes a useful boundary visible: a plan can be validated and inspected before it becomes a file. As command coverage grows, the same mechanism can expose duration changes, affected clips and validation warnings without forcing the user to trust a paragraph describing what the Agent intends to do.

09

The browser remains a compatibility path, not a failure

The command runner does not yet import media, generate speech, run automatic captions, assemble every visual layer or render the final video headlessly. Those operations remain available through the local or hosted browser editor. The Skill switches to an ordered checklist of visible actions and expected outcomes, prefers named controls over coordinates and saves a .timeline archive before destructive batches. It does not invent stable IDs or describe UI automation as deterministic. Browser control is valuable precisely because it reaches the product users have today; honesty about its focus, drag and file-picker limitations keeps that value from becoming a false guarantee.

10

The .timeline archive is the handoff between channels

A .timeline file is a ZIP archive containing project.json and its media entries. The command runner replaces versioned project metadata while preserving archived media bytes, and a human can reopen the result in the editor. This makes the archive more than a save file. It is the boundary object shared by a coding Agent, browser session and editor user. The MP4 answers 'what did this project render today?' The archive answers 'what decisions produced it, and can we change them tomorrow?' Cross-channel work becomes credible when each surface returns the same editable object rather than its own irreversible output.

11

Verification must cross the same boundaries as execution

A successful JSON response proves that a state transition passed its validations; it does not prove that a final video looks and sounds right. The Skill therefore reads the project summary again, checks ordering and track placement, previews the opening, each cut, caption boundaries, overlays and final frame, and listens for audio behavior. Embedded video audio must be distinguished from an explicitly separated source-audio lane. For export, the container, dimensions, duration, decoded frames, visible overlays and a real audio track all need evidence. When browser download events are ambiguous, the filesystem artifact and media decoding decide whether the job succeeded.

12

Capability boundaries belong in public documentation

The Skill ships focused public pages rather than one enormous manual: an overview of what Agent editing means, installation guides for Codex and Claude Code, reproducible workflows, an exact command reference and comparisons with FFmpeg, CapCut and Remotion. The routing rule is to answer one question with one page instead of loading everything. Just as important, current-capabilities.md lists what is still missing: broader reducers, richer inspection, persisted undo checkpoints, headless media probing and rendering, and an MCP transport over the shared registry. Publishing those gaps prevents a future promise from outrunning the implementation.

13

Multi-channel does not mean multi-truth

The long-term architecture is not four Agent-specific video editors. It is one project model, one command registry and several ways to reach them. Codex or Claude Code may reason from a repository, Copilot or Gemini CLI may begin from another terminal context, and a browser user may finish a visual decision manually. Their tools can differ, but clip identity, time units, validation and archive semantics should not. That is the useful meaning of a multi-channel Skill: the instruction package travels to the Agent, the execution path adapts to reality, and the editable project remains the stable source of truth.

REFERENCE

Frequently asked questions

Which Agent environments is the Skill designed for?

Its project package targets Codex, Claude Code, Copilot and Gemini CLI, while keeping the editorial workflow independent of one vendor-specific runtime.

Does every Agent use the same execution path?

No. The Skill prefers the versioned command runner for registered operations and uses the local or hosted browser editor for capabilities the runner does not yet expose.

What can the command runner currently edit?

The first registry supports moving voiceover clips, updating caption text and timing, and unlinking or relinking captions with optional audio alignment.

Why does a plan need baseRevision?

It prevents an Agent from applying an edit to a project that changed after inspection. A mismatch returns a revision conflict without modifying the archive.

Why keep operation IDs in the project?

They make retries idempotent across sessions: a previously recorded editorial operation will not be applied a second time.

Is the rendered MP4 the final source of truth?

No. The portable .timeline archive preserves project metadata and media so a person or another Agent can reopen and continue editing the work.