Aixcut

View saved version →

---
name: aixcut-basics
description: "Shared Aixcut MCP rules for context, read-before-write, stable refs, idempotency, async jobs, envelopes, and host boundaries. Load as fallback when no specialist Skill applies; do not use instead of a specialist workflow."
---

# Aixcut MCP Basics

Load with the relevant specialist Skill. Follow [language](references/language.md), [conversation guidance](references/conversation-guidance.md), and [ownership](references/model.md).

The release package supplies shared Core policy at [orchestration](../../references/core/orchestration.md) and [workflow boundaries](../../references/core/workflow-boundaries.md). Use these for phase budgets, Checkpoint recovery, state ownership and host fallbacks; live schemas and current user authorization remain authoritative.

Inspect `active_project_id`. If empty, ask for a Project name or `project_id`; never choose the first listed Project.

Read before writes; use returned refs. Reuse read evidence while Project, timeline, and revision are unchanged. Reread after writes, warnings, conflicts, or external changes; refresh before position-dependent commands.

Keep independent read calls parallel. Structural writes on the same timeline stay serial. Group the same action on the same track into one call using `items[]` or `targets`. Only the live Tool Schema decides what may be combined. Read affected views after each atomic batch.

Reuse `idempotency_key` only for identical, explicitly permitted retries. For `status_unknown`, confirm the receipt before taking any dependent write. For `async`, follow `job_id` and `next_action` until terminal. Business fields are in `result`; `noop` is final, `applied_with_warning` requires reporting warnings.

The Host handles OAuth; do not call `aixcut_login` first. Never use curl, direct database writes, invented server paths or results, bypass permissions, or expose tokens. Verify responses before reporting success.

## Intent and recovery contract

For every request use the short state machine `intent → inspect → plan → execute → verify → deliver`. Mechanical edits remain narrow: do not add voice, music, B-roll, Motion Graphics, or export unless explicitly requested. An assembly request may expand scope only after its `EditPlan` names the requested stages.

When a mutation returns `status_unknown`, preserve its original `idempotency_key`/`mutation_id` and query `aixcut_read(view="mutation_receipt")` with that identity. Treat `pending`, `unknown`, and `not_found` as unresolved until the receipt says `applied`, `duplicate`, `noop`, or `rejected`; never create a new key merely because a response was lost. Save a `Checkpoint` containing Project, timeline, revision, mutation identity and next action before leaving a recoverable stage.

Use the packaged Core executable `node <plugin-root>/scripts/workflow-host.mjs`. Validate the EditPlan before structural writes, attach `plan_context` to each planned mutation, and follow [executable workflow](references/workflow-host.md). After each atomic batch, create and save a Checkpoint with `save --directory <host-owned-workflow-directory>` and `{checkpoint}` on stdin; only `persisted: true` confirms cross-turn storage. On resume, inspect the current Project/timeline/revision first, then pass `{plan_id,current:{project_id,timeline_id,revision}}` to `resume --directory <same-directory>`. Follow `next_step`; never replay `completed_steps`. Without an available host-owned directory, the helper returns `persisted: false` and the workflow is not durable across sessions.

Use the default repair budget: at most one schema correction, at most two revision-conflict read/replan cycles, and at most two provider attempts for one generation target. Save a Checkpoint when the budget is exhausted and deliver the recoverable state.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-captions
description: "Create, edit, split, and style Aixcut captions and sync them with voice or speech. Do not use for voice synthesis or full assembly."
---

# Aixcut Captions

## Conversation guidance

State the caption task's current status and next step when useful. Continue safe work with the information already available. Ask only for a missing choice that materially changes the captions, and ask one question at a time. Distinguish an accepted update from captions verified by reading the Project back.

Caption content belongs to this Skill. Do not edit captions with the generic text Tool. The caption track may contain only real spoken words or user-provided subtitle copy. Visual annotations such as ingredient labels, arrows, callouts, titles, dashed or dotted circles, animated highlights, and Motion Graphs belong to their dedicated visual tracks and must never be represented as captions.

The caption track contains spoken or user-supplied subtitle copy only. Ingredient labels, arrows, callouts, titles, dashed or dotted circles, and Motion Graphs are separate visual elements; do not add them as captions or treat them as satisfied by subtitle text.

## Determine the caption source first

| Video type | Caption source | Action |
| --- | --- | --- |
| Narrated video (visuals + voiceover) | Transcript of the voiceover audio already placed on the timeline | Confirm the audio source has `transcript_status=available`, call `aixcut_caption(regenerate)`, then read the result back. |
| Talking-head video | The speech script/transcript | Captions may be derived from the speech track. |
| User supplied copy | The user's copy | Use that copy and align timing to the visuals or voiceover. |

Visual source clips usually do not have a usable transcript. For narrated videos, read the transcript for the voiceover audio. A saved voice script is not proof that transcription finished; do not copy the script and present it as ASR output.

## Short path

1. Read `aixcut_read(view="captions")` for current captions and stable refs. Also read `speech` or `timeline` to confirm the voiceover audio is placed.
2. For narration, reread the audio source's `transcript_status`. Regenerate only when it is `available`; if pending, wait and reread; report missing, outdated, or empty transcripts accurately.
3. Read `captions` again to confirm the count, first/last timing, and that generated text came from the transcript.
4. Before reporting captions complete, verify the caption track has no Motion Graph, `art-text`, or other visual annotation clips. Those elements must remain on their dedicated tracks.

## Choose the content language

Use the language the user requested for the finished captions, not the language of this Skill or the conversation by default. Preserve supplied wording unless translation is requested. If the user asks for translated subtitles, translate the source transcript into the explicit target language; if they ask for bilingual captions, preserve both languages in the requested format. Ask only when the target language is unclear and materially affects the result. Apply the shared language policy from `aixcut-basics`.

## Source rules

- A voice script is not ASR. Confirm the voiceover is placed and its transcript is `available`, then regenerate from the actual transcript.
- For a talking-head transcript, derive captions from the speech track; do not copy it manually.
- If neither source exists, create or confirm the intended copy with the user. Never invent captions.

## Timing

- Align captions to speech, not to visual cuts alone.
- Keep each caption to at most two lines. Split long sentences at punctuation or semantic boundaries.
- Do not leave gaps or overlaps between adjacent captions after splitting.
- If voiceover placement changes, rebuild or realign captions too.

## Writing and editing

- Replace the whole track with the set action; append new captions with the add action.
- Use the corresponding action for wo

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-documents
description: "Import a user-provided local document into an Aixcut Project library. Do not use for media assets or reading only."
---

# Import Project Documents

## Conversation guidance

State what is being imported and what happens next when useful. Continue when the document and target Project are clear. If the user must select or provide a file, say exactly what to do and what will let the import continue. Report imported only after confirming the result.

## When to use

`aixcut_document` is a local-MCP-only path. A hosted MCP server cannot read a path on the user's computer. Call it only when the MCP process itself has access to that path; otherwise call `aixcut_frontend` with `{"action":"prompt_add_document"}` and ask the user to choose the file in the Project Documents panel. Never send the computer path to the Tool.

- If the user only wants the document read, summarized, or used to answer a question, read it yourself and do not call this Tool.
- If no locally accessible path is provided, call `aixcut_frontend(action="prompt_add_document")`, wait for the user to choose the document, then call `aixcut_frontend(action="list_documents")` to confirm it appeared. Do not guess paths, scan directories, or fabricate content from a filename.
- Images, video, and audio are media assets. Use the `aixcut_frontend` media flow, not this Tool.

## Document content

| File type | `content` |
| --- | --- |
| Markdown, TXT, CSV, TSV | Optional. When omitted, the Tool reads the file directly. |
| PDF, Word, PowerPoint, Excel, HTML, RTF | Required. Read the file and provide its actual content as Markdown; the server does not parse these formats. |

- `content` must come from the file you actually read. Never infer it from the filename, invent it, or replace it with only a summary.
- Missing required content returns `MCP_DOCUMENT_CONTENT_REQUIRED`.
- If a text file is not valid UTF-8 (`MCP_DOCUMENT_ENCODING_INVALID`), read it and pass the text as `content`.
- Supported types are a fixed allowlist: Markdown, TXT, CSV, TSV, HTML, PDF, Word, PowerPoint, Excel, and RTF. Unsupported files such as ZIP or video return `MCP_DOCUMENT_MIME_UNSUPPORTED`; report that accurately and do not rename the extension to bypass validation.
- Preserve the source language and wording unless the user explicitly asks for a translation or rewrite. Apply the shared language policy from `aixcut-basics` when generating translated content.

## Call

The hosted MCP path does not support this call for a user-computer file. Use the browser-owned upload flow:

```json aixcut_frontend
{"action":"prompt_add_document"}
```

Read `aixcut_frontend(action="list_documents")` before opening the prompt to establish the existing document IDs. The action only opens the Project Documents upload entry. It does not upload or confirm a file. The user must choose the document; call `aixcut_frontend(action="list_documents")` and confirm the selected filename and document ID before reporting success. A stored document with `parse_status=parsing` still needs parsing; `error` means parsing failed. Poll only the document list while parsing and never reopen the upload prompt to check status. Do not pass `file_path`, `content`, or a local URL to this hosted action.

A local MCP process may use:

```json aixcut_document
{"action":"import","file_path":"/path-visible-to-the-mcp-process/notes/product-overview.md"}
```

```json aixcut_document
{"action":"import","file_path":"/Users/me/docs/quarterly-review.pdf","content":"# Quarterly Review\n\nActual document text in Markdown."}
```

- `file_path` must be an absolute local path. Relative paths return `MCP_DOCUMENT_PATH_INVALID`.
- `file_name` changes the name shown in the Documents panel; when omitted, the original filename is used.
- Add `mime_type` only when the extension is missing or incorrect.
- If `project_id` is omitted, the current Project is used.
- This Tool has no `idempotency_key`; do not add one. Duplicate de

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: aixcut-export
description: "Export an Aixcut Project as MP4, MOV, or WebM and check the page-based export status and result. Use when the user asks to export, render, download, or check an export. Do not use for editing, voiceover, or captions."
---

# Export from Aixcut

## Conversation guidance

State the export's current status and next step when useful. Continue checks and polling when possible. Distinguish queued, rendering, completed, failed, and unknown; report an export as complete only after its result is available.

There is one export path: the open Project page renders the timeline in the browser and downloads the finished file to the user's computer.

Local video is not uploaded in full. If it has audio, the browser may upload extracted audio for transcription; visual understanding uses on-demand `capture_source_frames` or `capture_timeline_frames`. Do not require a full cloud copy or server-side render job.

## Workflow

1. Call `aixcut_frontend(action="export_timeline")`. Pass `timeline_id` to export a non-current version; the page reads that timeline without changing the user's current tab. The call returns `export_id` and the actual `format`, `width`, `height`, and `frame_rate`. It does not return a file URL; the browser downloads the file.
2. Accepted does not mean complete. Wait for top-level `next_action.after_seconds`, then call `aixcut_frontend(action="export_timeline_status")` until `state` is `succeeded` or `failed`.
3. `succeeded` means the file was handed to the browser download flow. Report `file_name`, `byte_size`, `mime_type`, and `elapsed_ms`; do not promise a server download link.
4. If the user cannot find the file, check the browser download list and blocked-download notice before considering another export.
5. If the user wants a different format, resolution, or frame rate, submit one new `export_timeline` request. Only one export can run on a page at once; while one is active, query its status instead of submitting again.

Before export, bind the current inspected timeline revision and pass it as `expected_revision` to `export_timeline`. Run the packaged Core `workflow-host.mjs gate` with `{evidence,current:{project_id,timeline_id,revision},deliverable:"export"}` before submitting export. Report export success only if the page status succeeded and current structural evidence still passes the gate; this gate does not prove playback or listening.

The target Project page must be open and initialized. If it is offline or bound to another Project, ask the user to open the target page. If uncertain, call `aixcut_frontend(action="page_status")`.

Local media also requires browser file-access permission. If export or frame capture returns `CAPTURE_PERMISSION_REQUIRED`, ask the user to click anywhere on the Project page and retry the same request. Do not reimport the media.

## Error handling

| Error | Meaning and action |
| --- | --- |
| `MCP_EXPORT_ALREADY_RUNNING` | Do not submit again; call `export_timeline_status`. |
| `MCP_EXPORT_INVALID_INPUT` | Correct the format, dimensions, or frame rate and submit again. |
| `MCP_EXPORT_FAILED` | Explain `error_message`; retry once only with a justified parameter change. |
| `MCP_EXPORT_CANCELLED` | Report that the user cancelled the export. Do not retry as a system failure. |
| `MCP_FRONTEND_NOT_BOUND` | Ask the user to open the Aixcut Project page. |
| `MCP_FRONTEND_CLIENT_OFFLINE` | Do not reopen the Project automatically. Ask the user to open the target Project in this MCP session, then check `page_status`; retry export at most once after it is online. |
| `MCP_FRONTEND_PAGE_NOT_ACTIVE` | Ask the user to switch the online page to the target Project. |

## Boundaries

- Export does not change timeline content. Do not make unrequested edits.
- The finished file does not pass through MCP. Do not promise a later server link.
- For local media and asynchronous recovery, see `aixcut-timeline-editing`. For a full production workflow, see `aixcut-vi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-generation
description: "Generate images, videos, or music in Aixcut and track asynchronous jobs. Use for new visual or audio assets and generation progress. Do not use to edit existing media or assemble a complete video."
---

# Aixcut Generation

## Conversation guidance

State whether generation is being prepared, queued, running, or complete, and what happens next. Continue safe status checks when possible. Pause before an unaccepted cost or credits, or when a missing creative choice would materially change the result. Do not describe a submitted Job as a finished asset.

Generation creates a durable Job; it is not a synchronous operation.

## Short path

1. Confirm the target Project; read `aixcut_read(view="project")` if needed.
2. If generation may consume credits and the user has not accepted a quoted amount, call `aixcut_generate(action="quote")`. It does not create a Job. If the quote is nonzero, explain the amount and wait for the user's acceptance before submitting; pass the accepted amount as `accepted_quoted_credits`.
3. Submit using `aixcut_generate(action="submit")` only after required creative choices are clear and any quoted charge is accepted.
4. If the envelope returns `status: "async"`, retain its top-level `job_id` and use `aixcut_generate(action="get")` to read the durable Job; ClipOS runs accepted Jobs independently of polling or the browser connection. Never resubmit a queued or running Job.
5. Use top-level `next_action.after_seconds` for the next poll. Stop when top-level `terminal` is true.
6. Report `result.data.job.phase`: `waiting` (queued), `processing` (generating), or `finalizing` (publishing to the Project). Do not report only “in progress.”
7. After generation, place the result on a timeline when the user asked for it.

For multiple video versions, the assembly Skill first lists and duplicates timelines with `aixcut_timeline(action="list")`. `aixcut_generate` creates Project-level assets that can be reused by multiple `timeline_id`s. Place and verify the result on each requested timeline.

## Content language and prompt

Follow the user's requested content language and target audience for visible text, dialogue, lyrics, or other language-bearing parts of the asset. A prompt may be written in English for model reliability, but the prompt must still explicitly state the requested spoken/on-screen language when relevant. Do not silently translate the user's creative brief or switch the asset to English because this Skill is in English. Preserve the creative direction and wording unless asked to adapt it. Apply the shared language policy from `aixcut-basics`.

Resolve only the language choice relevant to the requested asset: visible text for images; dialogue and on-screen text for videos; lyrics for songs (instrumental music has no content language); and script language for voiceover. If the user says “song” but does not indicate lyrics or instrumental music, ask which they want before quoting or submitting. Do not ask about language for instrumental music.

## Generation types

- Generation Jobs use `kind=image`, `video`, or `music`; the server processes music as audio. To discover providers/models, `aixcut_generate(action="catalog")` also supports `kind=speech`. If `kind` is omitted from `catalog`, the server returns speech models by default.
- If the user does not specify a provider, use the server default. Override only on explicit request.
- Prompt, style, duration, and language-bearing content should follow the user's brief; do not rewrite the creative direction without reason.

## Asset source

Generation creates images, videos, and music in the Project library; it does not create Motion Graph source assets, import files, or perform post-production on existing audio. Do not use a generic video-generation Job as a substitute for an editable Motion Graph. If no supported MG asset or creation path is available, report that limitation rather than substituting captions. Use `a

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-known-errors
description: "Troubleshoot rejected Aixcut calls by stable error code. Use for Tool failures. Do not use for ordinary editing."
---

# Aixcut Error Recovery

## Conversation guidance

Explain what failed, whether work may have partially completed, and the next recovery step. Continue safe recovery when the error contract allows it. If user action is required, name it and state what to retry or inspect afterward. Never present an uncertain state as a success or a definite failure.

Use `error.code`, `error.type`, `error.retryable`, and `error.next_action` to choose recovery. Never branch on `error.message` text. A rejected response is not a successful edit.

## `next_action` kinds

| kind | Meaning |
| --- | --- |
| `none` | Recovery requires a user decision. |
| `resolve_input` | Correct the input or ref before retrying. |
| `retry` | Retry the same request after `after_seconds`. |
| `poll` | Poll the same `job_id`. |
| `receipt` | Confirm the original mutation with its original identity before dependent writes. |
| `open_editor` | Open the required page first. |
| `run_helper` | Run the specified local helper first. |
| `wait_then_read` | The action was accepted but is still running. Wait `after_seconds`, then call the specified read endpoint. Do not report completion or resubmit the action. |

## Input and contract errors

- `MCP_ARGUMENTS_INVALID`, `MCP_ARGUMENT_UNKNOWN`: A field is missing, has the wrong type, or is not allowed. Send only fields declared by the selected Tool Schema.
- `MCP_ACTION_INVALID`, `MCP_VIEW_INVALID`, `MCP_OPEN_TARGET_INVALID`: Use a supported action or view.
- `MCP_IDEMPOTENCY_KEY_INVALID`: Generate a new UUID v4 for `idempotency_key`.
- `MCP_ACTION_UNSUPPORTED`: Choose a Tool that supports the requested action.
- `MCP_LAYOUT_CLIP_UNSUPPORTED`: The target has no visual content. Layout applies only to video and image clips, not audio or text.

## Authorization and project context

- `MCP_SCOPE_REQUIRED`: The current grant lacks a required scope. Let the Codex Host reauthorize; do not bypass the scope with another Tool.
- `MCP_PROJECT_CONTEXT_REQUIRED`: No Project is active. Ask the user to select one or use `aixcut_open` to enter a Project.
- `MCP_PROJECT_NOT_FOUND`, `MCP_PROJECT_NOT_INITIALIZED`: Confirm the target Project before continuing.

## Mutation conflicts and uncertain state

- `MCP_PLAN_REQUIRED`: This mutation is protected by the plan guard. Read the current Project and timeline, build a fresh `plan_context` for the intended action, and retry; do not reuse a stale revision or broaden `authorized_actions` beyond the user's request.
- `MCP_PLAN_REVISION_STALE`: The Project changed after it was read. Confirm the original mutation receipt, reread the current timeline, and rebuild the plan; do not replay stale refs.
- `MCP_PLAN_SCOPE_CONFLICT`: The plan's Project/Timeline, refs, preserve/delete lists, or declared deletions do not match the mutation. Reread and rebuild the exact scope; do not remove protections just to make the mutation pass.
- `MCP_PLAN_ACTION_UNAUTHORIZED`: The action is outside `authorized_actions` or the mechanical plan's allowed operations. Do not broaden the plan; ask the user if the requested result requires additional scope.
- `MCP_TRACK_LOCKED`: The target track is locked. Read its current state. If unlocking is part of the user's authorized request, call `aixcut_track(action="update", locked=false)`, reread, then retry the intended clear/delete with a fresh `plan_context`.
- `MCP_MUTATION_SERVER_REJECTED`: Read the latest snapshot and regenerate the operation. Do not replay the old payload unchanged.
- `NLE_IDEMPOTENCY_CONFLICT`: The key is already bound to a different project, timeline, or action. Read the timeline and confirm whether the earlier write already achieved the intent before redoing. A same-key retry against the same target is reported as a replay instead, not as this error.
- `MCP_TRACK_ENSURE_NOT_APPLIED`: Read-back found

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: aixcut-login
description: "Check the current Aixcut MCP OAuth login state without opening a web page. Use only when the user explicitly asks to sign in, restore authorization, or check login status. Do not use for opening a Project or signing out."
---

# Check Aixcut MCP Login

## Conversation guidance

Report the verified authorization state and the next step in the user's setup. Keep MCP availability, Plugin installation, and Project readiness distinct. If authorization is missing, let the Codex Host handle OAuth and explain what the user will see.

Call `aixcut_login` once with `{}`. Success requires the envelope `status` to be `ok` and the business result `result.status` to be `authenticated`.

## Result handling

- **Already authorized:** the Tool returns `result.status="authenticated"`.
- **Authorization missing or expired:** the Codex Host opens the Aixcut OAuth page and resumes this call after completion. Do not operate the authorization page or call the Tool again.
- **Authorization denied, cancelled, failed, or timed out:** stop and report that login did not complete.

## Constraints

- This Skill does not handle page-opening requests. Use `aixcut-projects` for opening a page.
- Do not add `project_id` or any business argument to `aixcut_login`.
- For other Tools, the Codex Host resumes the original call when authorization is required; do not call `aixcut_login` first.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-mcp-logout
description: "Sign out of Aixcut MCP, revoke its OAuth grant, and clear the local credential. Do not use for the Studio website."
---

# Sign Out of Aixcut MCP

## Conversation guidance

Explain that signing out changes authorization and what the user will need to do before the next Aixcut operation. Report completion only after the logout action confirms it.

1. If the session is authorized and `aixcut_logout` is available, call it once with `{}` to revoke the server-side grant.
2. Whether the Tool succeeds, is unavailable, or reports that the session is already unauthorized, run `codex mcp logout aixcut` to clear the local credential. Never print or inspect credential files.
3. Report the two outcomes separately:
   - both succeed: Aixcut MCP is fully signed out;
   - server already unauthorized and local cleanup succeeds: Aixcut MCP is signed out;
   - only one succeeds: say which side remains and do not claim complete logout.

## Constraints

- Do not remove the MCP server configuration. Logout must preserve the `aixcut` server registration.
- If the Tool is unavailable or would open a new authorization page, skip it and perform only the local logout step.
- Do not call `aixcut_logout` more than once or automatically sign in again.
- Do not sign out of the Studio web session unless the user explicitly asks for that separate action.
- Never output, read, or copy OAuth access tokens, refresh tokens, or credential contents.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-projects
description: "List, create, open, switch, or exit an Aixcut Project. Do not use for timeline edits."
---

# Aixcut Projects

## Conversation guidance

State whether the user is selecting, opening, creating, or leaving a Project and what happens next. After an open or create request, verify the page and active Project state before saying the user is ready to edit. If a required choice is missing, ask one concise question and recommend an option.

## Open a page

Call `aixcut_open` once with the target that matches the request:

| Intent | Arguments |
| --- | --- |
| Open Studio | `{"target":"studio"}` |
| Open the Project list | `{"target":"project_list"}` |
| Create and enter a Project | `{"target":"new_project","title":"...","description":"optional"}` |
| Open a specific Project | `{"target":"project","project_id":"..."}` |

When later work needs the editor page (frame capture, page-based export, or asking the user to upload media), open the specific Project with `target="project"`. Opening Studio or the Project list does not bind editor actions to a Project.

After a successful call, immediately open the complete `result.browser_handoff.url` with Codex Desktop's official browser-opening capability. This Skill supplies the Codex opening arguments locally:

```javascript
{ target: { type: "browser", url: result.browser_handoff.url }, placement: "right" }
```

Preserve the URL and its one-time `session_token` exactly. Do not compose a plain Project URL or use `editor_url` for MCP session binding. Only pass the complete handoff URL to the host opening capability; do not print or persist it.

## After creating a Project

`new_project` creates the Project skeleton synchronously, including the default sequence, video/text/audio tracks, and an empty voice document. It can be read or edited immediately; the page itself may still be opening.

- `result.data.project_id`, `result.data.sequence_id`, and `result.data.project` identify the created Project and sequence.
- `result.page_open_requested: true` means the server requested that the page open; it does not prove the page is connected. A host opening result of `queued` also does not mean it is connected.
- Top-level `next_action` is usually `wait_then_read`. Wait about 5 seconds, then call `aixcut_frontend(action="page_status")` if the next operation needs the page.

Only confirm page presence when the next action needs it. Timeline reads/writes and voice script/settings writes do not require the editor page; voice rendering, frame capture, page export, and user-assisted upload do. Require `presence_connections >= 1` and confirm that the target Project appears in `pages`; a different online Project is not sufficient. If the target is absent, stop and ask the user to open or switch to that Project in this MCP session. Do not call `aixcut_open` again or treat `queued` as connected. Once the target is online, retry the original page action at most once.

## Returned data

- `studio` and `project_list`: `result.data.projects` and `result.data.total` describe the current Workspace directory and can answer a listing request directly.
- `project`: `result.data.project` is the same Project summary returned by `aixcut_read(view="project")`; do not read the same summary again.
- `new_project`: creates and initializes the Project synchronously; the returned `project_id`, `sequence_id`, and `project` are the creation result.
- `result.active_project_id` is the current MCP Project. `project` and `new_project` target that Project; `studio` and `project_list` only navigate and do not change it.
- If `active_project_id` is empty, never select the first Project by default. Ask for a Project name or `project_id`, then open that target.
- The page loads business data itself. Treat returned data as facts for this call, not as a replacement for later reads.

## Switch or exit

- When the user explicitly asks to leave the current Project, call `aixcut_exit_project` with no argume

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: aixcut-talking-head
description: "Edit speech-led videos such as interviews, courses, or podcasts, especially to remove mistakes and pauses. Do not use for music montages or full assembly."
---

# Speech-Led Editing in Aixcut

## Conversation guidance

State the current editing stage and next step when useful. Reuse the user's stated editing intent and continue safe inspection or cleanup. Pause only for a choice that materially changes the edit or an operation with important risk. Verify speech and caption state before reporting completion.

## Short path

1. Read `aixcut_read(view="source_lines")` in pages. The default is 200 rows; follow `next_offset` until `has_more=false` to get the full speech text and timing. Do not request all `word-time` data at once.
2. After identifying the lines to edit, use `selectors` with `include=["word-time"]` for word-level timing; request at most 50 rows per page.
3. Apply the requested edit with `aixcut_speech`.
4. Captions follow the primary speech track. When needed, synchronize or regenerate them with `aixcut_caption`.
5. Read back `timeline` or `speech` to confirm the result.

## Required order

Speech timing anchors downstream work. Keep this order:

1. Finalize speech structure: remove mistakes, filler, pauses, and repeated takes.
2. After speech is final, adjust visuals: add/remove B-roll or overlays.
3. After visuals are final, update captions so their timing follows the final speech.
4. Add music and sound effects last, fitting them to the final duration.

If an upstream stage changes, revisit dependent stages. Read back after each major stage.

## Speech actions

| Intent | action |
| --- | --- |
| Replace the full speech sequence | `set` |
| Insert new speech | `insert` |
| Remove a mistake, filler, or full line | `delete` |
| Replace a clip's source | `replace` (requires `source` and `target`) |
| Shorten a pause or trim a clip | `trim` |
| Restore the original speech | `reset` |

`delete` and `trim` accept `target` or `targets` and can process several ranges. Deletion or trimming changes later positions; reread after each structural change.

## Boundaries

- `aixcut_speech` edits only the primary speech track. Use `aixcut_clip` for B-roll and visuals, and `aixcut_audio` for music or sound effects.
- Do not use `aixcut_text` to edit captions.
- Use a fresh UUID for each batch. Do not reuse one key across distinct batches.

## Common misses

- Do not create captions before the speech edit is final; speech changes can invalidate caption timing.
- Reread after every structural speech change because later positions move.
- If visuals are replaced or trimmed, realign captions to the final speech rather than changing speech alone.

## Completion

Confirm the speech reflects the request, read-back positions are correct, and captions align. Report how many segments were removed and added, plus the new revision. Use `aixcut_review` when visual verification is needed.

## Semantic and natural speech gate

Select takes by semantic units: record a preserve list for negation, conditions, numbers, names, required steps and the intended claim. When multiple retakes exist, choose the complete correct take before removing filler. Keep natural breaths and meaningful pauses; inspect the audio seam at each join after trimming. Without listening evidence, seam quality remains unjudgeable. Optional B-roll, music and overlays remain off during mechanical speech cleanup unless requested. If a speech operation or transcript state is unknown, preserve its identity and read the current state before continuing; do not reapply the edit with a new UUID.

View saved version →

---
name: aixcut-timeline-editing
description: "Edit Aixcut clips, text, audio, tracks, canvas, and local imports. Do not use for voice scripts, full assembly, or export."
---

# Aixcut Timeline Editing

## Conversation guidance

State what timeline change is underway and what happens next when useful. Read current state and proceed when the request is clear and safe. Ask one question only when a missing decision materially changes the edit. If a local file or browser action requires the user, name the exact action and the condition for continuing.

Use the real MCP Tools. Do not use curl, hand-written JSON as a substitute for a call, direct database writes, or local files to reconstruct a result.

Voice, captions, and export have dedicated Skills: `aixcut-voice`, `aixcut-captions`, and `aixcut-export`.

## Minimal workflow

1. Read every view needed for the requested edit and use only stable returned refs; never guess IDs.
2. Create a fresh UUID v4 `idempotency_key` for each new write intent.
3. Call the narrowest Tool and action matching the intent.
4. Read affected views after a successful write; use `aixcut_review` when structure or visual placement needs confirmation.
5. Report the actual result fields when present: `status`, `mutation_id`, `operation_id`, `revision_after`, `created`, `removed`, `ref_map`, and `warnings`.

### Batching writes

- Send one call per action and track, not one call per element: pass the whole set through `items[]`, or every target through `targets`, in that single call. `aixcut_clip`, `aixcut_text`, `aixcut_audio`, and `aixcut_primary` accept lists.
- Never issue one call per clip, per label, or per segment when one supported call can carry the batch.
- Never merge different actions, different tracks, or different domains into one call; only the live Tool Schema decides what may be combined.
- Do not run structural writes on the same timeline concurrently.
- Reuse the last read while the timeline is unchanged; reread before a position-dependent command and after each atomic batch.

## Multiple timelines and versions

- For versions, A/B variants, aspect-ratio adaptations, or “keep the original and make another”, call `aixcut_timeline(action="list")` first.
- Create a new version with `aixcut_timeline(action="duplicate", source_timeline_id=...)`; use `create` only when the user explicitly wants a blank timeline.
- After selecting a `timeline_id`, include it in every later read, edit, capture, and review for that version. Do not mix refs across timelines.
- Do not create an extra timeline for a single-version request.

## Tool selection

| Intent | Tool |
| --- | --- |
| Read or review | `aixcut_read`, `aixcut_review` |
| Main video sequence | `aixcut_primary` |
| Voice segments | `aixcut_speech` |
| Video, image, or Motion Graph clips | `aixcut_clip` |
| Regular on-screen text | `aixcut_text` |
| Music, effects, or placed voice audio | `aixcut_audio` |
| Tracks | `aixcut_track` |
| Canvas or full cleanup | `aixcut_project` |
| Remote browser actions | `aixcut_frontend` |

Send only fields declared by the selected Tool Schema. `aixcut_speech` edits the main voice track; `aixcut_text` does not edit captions. After a structural change, reread before issuing a position-dependent command.

## Keep visual layers separate

- The caption track is only for text that follows spoken words. Ingredient labels, arrows, circles, callouts, titles, and other visual annotations are not captions.
- Add static or editable text annotations with `aixcut_text` on a non-caption text track. For an existing Motion Graph asset, add it with `aixcut_clip` on a video overlay track and set that item's `kind` to `motion-graph`; the default `video` kind rejects Motion Graph media. Never target a text or caption track with a Motion Graph.
- Before adding an annotation, read the track list and choose a track whose kind matches the asset. After the write, read back the clip kind and track. If placement fails or lands on the wrong

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-verification
description: "Verify Aixcut structure, timeline, voice, captions, and renderability. Read-only: never edit."
---

# Verify Aixcut Results

Apply the packaged shared [quality gates](../../references/core/quality-gates.md), binding each evidence item to the actual Project, timeline, revision and sampled interval.

For the `aixcut_review` view parameters and result fields, see [Review Action Reference](references/actions.md).

## Conversation guidance

Separate verified facts, unresolved checks, and the next step. Report only what the read-back or review confirms; if a check is unavailable, say what remains unverified and how to complete it.

Every write needs the verification appropriate to the request. A tool result of `applied` is not by itself a final conclusion.

After each atomic batch of structural writes, immediately read back every affected view before continuing. One call that carries the whole batch counts as one batch; do not reread between the items of a single batch. Timeline, audio or voice, and caption writes require rereading the affected `timeline`, audio or `speech`, and `captions` views so the returned refs and state are current.

## Short path

1. Read the affected view, such as `timeline`, `captions`, `speech`.
2. Call `aixcut_review` for structural checks.
3. Capture frames when the user needs visual confirmation.
4. Report what passed and what was not checked.

## Review scope

| view | Check |
| --- | --- |
| `project` | Overall Project structure and tracks. |
| `timeline` | Clip order, duration, gaps, and overlaps. |
| `timeline` plus `speech` read-back | Voice script, effective profile, and separate timeline placement. |
| `renderability` | Static structure, source availability, and valid duration. Do not apply removed server-renderer v1 limits. Canvases beyond the 4K UHD pixel budget produce a `CANVAS_HIGH_RESOLUTION` warning; do not change the canvas automatically. |

## Visual verification

Frame capture is conditional. It is required when:

- Any visual clip's position or size changes, or another visual is layered at the same time.
- A lower third, caption position, or caption visibility changes.
- The user asks whether something is obscured or how it looks.

Do not capture frames for timing-only edits (trim, split, move, or speed), volume, or fades when they do not change the visible composition; volume and fades use audio evidence instead. Skip timing-only frame capture only when the final visible composition is unchanged. If the edit changes which image is visible, subtitle placement, or the layer relationship at any sampled time, capture the affected timeline frames. Without actual playback or listening, volume and fades remain `unjudgeable`, not a quality pass.

### Capture procedure

- Use `aixcut_frontend(capture_source_frames)` for source footage and `capture_timeline_frames` for the timeline composition.
- `selections` contains 1–8 entries. Each entry must use exactly one form: `{"times_ms":[2000,7000]}` (up to 16 timeline points or 24 source points) or `{"start_ms":0,"end_ms":6000,"count":3}`. Do not mix forms within an entry.
- Capture 1–8 frames in one call and stop when sufficient; do not keep capturing.
- Pass `expected_revision` when the latest revision matters. `MCP_FRONTEND_TIMELINE_STALE` means the timeline changed; reread it before deciding whether to capture again.
- If capture returns `CAPTURE_PERMISSION_REQUIRED`, ask the user to click anywhere on the Project page, then retry the same request. Do not reimport media.
- Captured frames are temporary JPEG URLs. Provide usable links to the user when available; do not claim that the MCP server wrote them to the user's computer.

### Inspecting the composition

- Timeline capture results include a `composition` roster. Use it to map visible elements to refs rather than guessing.
- `composition.frames` gives each captured frame's `index`, `times_ms`, and visible items with ref, time range, track, and `vis

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-video-assembly
description: "Assemble a complete video by coordinating visuals, voiceover, captions, music, and export. Do not use for a single edit."
---

# Aixcut Video Assembly

Use the packaged shared [orchestration](../../references/core/orchestration.md) and [quality gates](../../references/core/quality-gates.md) as the common policy; keep browser handoff and local-file operations in their Codex specialist Skills.

## Conversation guidance

Keep the user oriented at each stage without turning the workflow into a fixed questionnaire. If the goal is clear, inspect the Project and media, then continue safe work. Pause only for a consequential unresolved choice, permission, unaccepted cost or credits, or overwrite/deletion risk. At handoffs, state what is complete, what is next, and whether the user needs to act.

This Skill owns the order and dependencies between stages; each specialist Skill owns its detailed procedure. A finished video must meet the user's visual, audio, and text requirements.

## Scope

Use this Skill for multi-stage work, such as turning source media into a 60-second promo with voiceover, captions, and music, or shortening a video and adding narration. For a single caption, clip replacement, or export, use the corresponding specialist Skill directly.

## Align before acting

Resolve only relevant decisions that are still missing; treat this list as a guide, not a questionnaire:

1. **Video goal:** duration, aspect ratio, platform, and use.
2. **Audio:** voiceover? Background music? Should music sit below original audio?
3. **Text:** captions? Should they follow the voice script or source speech?
4. **Media:** use existing assets or ask the user to upload more?
5. **Content language:** follow the language policy. Do not infer the finished video's language solely from the conversation language.

Keep spoken captions and visual annotations as separate requirements. Captions follow spoken words; animated ingredient labels, arrows, circles, and callouts belong to the corresponding visual moments. Verify both categories independently; one does not replace the other.

Visual annotations are a separate stage before caption generation. Classify each requested element as a spoken caption, static art text, or Motion Graph, place it on its dedicated track, and verify its clip kind and track before moving to captions.

If the user requests multiple versions, A/B, portrait/landscape, or platform variants, first call `aixcut_timeline(action="list")` and duplicate a timeline per version. Include each version's `timeline_id` in later reads/writes. Generated assets are Project-scoped and can be reused; do not regenerate them for each version.

Ask one concise question at a time. If the user requests uninterrupted end-to-end execution, use reasonable reversible defaults for non-blocking choices and report them. Still resolve choices that materially change the content language, incur an unaccepted charge, or risk overwriting existing work.

## Audio intent gate

Before choosing any audio action, read the Project, current Timeline, source audio and existing voice or narration, existing music, and each relevant source's `transcript_status`. Do not infer an audio request from the fact that this Skill is being used. Classify the request with these explicit states:

- `preserve-original`: keep the existing source audio or correct narration and do not create AI voice.
- `generate-voice`: the user explicitly requests new AI narration; enter the voice render flow.
- `replace-original`: the user explicitly requests replacing existing speech; render and place only the requested replacement range.
- `add-music`: the user explicitly requests background music or confirms a music choice; add a separate music track.
- `no-music`: the user explicitly says not to add music; do not generate or add one.
- `optional-music`: the user says music is optional, or does not mention music; default to no music and ask for confirmatio

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: aixcut-voice
description: "Write voiceover scripts, select a voice, synthesize speech, and optionally place it on the timeline. Do not use for music or visual assembly."
---

# Aixcut Voiceover

Follow the packaged shared [speech workflow](../../references/core/speech-workflow.md) for frozen recovery, per-child Job continuation and transcript boundaries.

## Conversation guidance

State whether the script, voice selection, rendering, or timeline placement is in progress and what happens next. Follow the requested content language and preserve supplied copy unless translation or rewriting is requested. Pause for consequential voice or script choices, unaccepted generation cost, or overwrite risk; verify the rendered and placed audio before reporting completion.

Voice scripts and voice profiles are stored in the Project Voice document. Rendered audio is linked back to its voice segments. Timeline placement is a separate optional step.

## Audio intent and evidence

Before rendering, read the current `timeline`, audio tracks and clips, source media transcription state, and existing voice segments or rendered voice audio. Use `aixcut_read(view="timeline")`, `aixcut_read(view="sources")`, and `aixcut_generate(action="speech_read")` as needed; do not infer intent from the presence of this Skill alone.

- If an existing source voice, speech, or narration is correct and the user only asks to edit visuals, timing, or captions, reuse the existing audio and skip voice render and placement.
- `speech_quote` freezes the selected paragraphs and price without submitting. `speech_submit` accepts that frozen recovery and submits generation; it does not replace original or source audio by default.
- Render and place only when the user explicitly requests new AI voice or explicitly requests replacing the original voice. A request to edit a timeline alone is not such a request.
- Before any placement, identify the target track and requested start/end range. Keep original speech, AI voice, music, and sound effects on their intended tracks; do not create a second human voice over a correct source narration.

## Workflow

1. Read the current timeline, audio tracks and clips, source transcript state, and existing voice before deciding whether rendering is needed. Call `aixcut_generate(action="catalog", kind="speech")` for current ready voice identities and selectable models, then `aixcut_generate(action="speech_read")` for ordered paragraphs and effective settings.
2. Use `aixcut_generate(action="speech_edit")` with `operation=add|update|delete|move` to update scripts or settings. These script and settings document writes do not require the Project page. Refresh the ordered draft before using paragraph numbers after conflicts or external edits.
3. Only for explicitly requested new narration or replacement, call `aixcut_generate(action="speech_quote")` with `segments` or `all=true`. Preserve its frozen recovery object and total credits; submit `aixcut_generate(action="speech_submit")` with exactly that recovery after the quoted charge is accepted.
4. Retain each per-paragraph operation identity and Job ID (`jobId`). Read each known Job with `aixcut_generate(action="get")` at returned intervals until terminal and published media are available. `submission_unknown` is not failure: retry only the identical frozen recovery, preserving operation identities. Never re-quote or generate a fresh identity to recover a lost response.
5. Place audio only if requested, using `aixcut_audio` and published media refs through `aixcut-timeline-editing`; confirm target track and range first. Submission has no placement flag and never clears an existing voice track. Read back timeline/audio and source transcript status. Report generation, placement, transcript and listening evidence separately.

Voice rendering uses durable Jobs after the user's accepted quote. A bound Project page is required for timeline preview, placement that needs browser media, frame cap

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.