The Kestroll skill

---
name: kestroll
description: Use Kestroll's AI video editor through the kestroll CLI — find specific moments, edit videos, render final cuts, and manage the media library. Trigger when the user mentions "kestroll", asks to edit/cut a video, find a moment in footage, create social assets, add captions to a video, analyze the content/transcript of a video, or search their footage library.
skill_version: 09_22_2026
---

# Kestroll

## What Kestroll is and your role

Kestroll is an AI video editor. The user uploads source footage (interviews, podcasts, Riverside recordings, etc.) into a media library, and edits are expressed as **compositions**: YAML timelines that describe which source clips play when, in what layout, with which person tracked. A composition has `elements` (clips with `source_start`/`source_end` from the asset and `composition_in`/`composition_out` on the output timeline) and a `canvas` (aspect ratio). Layouts are kept simple: full-frame, 2×1, 2×2, or 3×1 splits.

**Live guidance beats this file.** `kestroll tools describe <tool>` returns the current input schema plus usage guidance, while `kestroll --help` shows the latest cli commands.

## Why Kestroll?

Kestroll offers you several video-editing specific advantages:

1. **Detailed Search**: use the `search` tool to find moments by transcript or visuals by querying the detailed metadata embeddings.
2. **Asset Data** Every uploaded asset is indexed by a robust AI-analysis pipeline providing rich data about each asset. You can view the data for an asset using the `get_asset_data tool` such as moment-by-moment summary, people that appear in it, transcript, scene-by-scene layout, metadata, and other custom user data. You can also inspect a frame visually using the tool, or easily delegate to a video understanding agent to answer questions about it.
3. **Visual Editing**: Kestroll presents a video editor UI that the user can use to easily watch and edit the edited composition. This makes it easy to collaborate, fine-tune and iterate quickly.
4. **Export**: Kestroll allows you to export your compositions as XML so you can continue it in another NLE, or else export as an mp4 (converting the YAML preview using ffmpeg on the Kestroll servers).
5. **Editing Utilities**: Some common editing utilities are available to you through the Kestroll CLI, such as tracking a person as they move throughout a clip, auto-clipping silences and filler words, duplicating compositions, syncing assets based on timecode or transcript, adding styled captions, and more with a single tool call.
6. **Generative Abilities**: You can generate images, videos, or motion graphics directly into the Kestroll media library.

## Auth and setup

- `kestroll login` — authenticate through the browser. Verify with `kestroll me`.
- Credentials live in `~/.kestroll/auth.json`. `kestroll logout` revokes the session.
- There are no API tokens or token env vars — browser login only.
- If a command described here is missing from your installed CLI, run `kestroll update`.

## General Workflow

When given a request, you should usually begin by checking if the needed assets are in Kestroll using the search tool.
If not, upload them using `kestroll upload`.

Then, read the relevant docs using the docs tool to understand the correct YML schema for what you want to accomplish.
Then implement using the tools provided to you, both `kestroll tools` and any other tools you may have available to you.

## Calling tools

The bulk of your work should be done through tools.

```bash
kestroll tools list                                  # compact metadata for every available tool
kestroll tools describe <tool>                       # input schema + live usage guidance
kestroll tools call <tool> --input '<json>'          # also accepts @file or - (stdin)
kestroll tools calls get|wait|cancel <call-id>
```

- **Describe before first use.** Before calling a tool for the first time in a session, run `kestroll tools describe <tool>` and follow its usage guidance and schema exactly.
- Stdout contains exactly one JSON value; progress goes to stderr. A call envelope has `session_id`, `call_id`, `tool`, `status`, and either `result` or a structured `error`.
- Exit codes: validation, transport, and auth failures — and `failed`/`cancelled` calls — exit nonzero. A domain error returned by a tool handler is still a `completed` result: inspect the result and recover; zero exit does not mean the operation succeeded.
- `call` waits for a terminal result by default. For long-running work (builds, exports, processing), pass `--no-wait` and poll with `tools calls get <call-id>` or block with `tools calls wait <call-id>`. `await_processing` is a deferred tool — it parks as `waiting` until processing finishes.
- Pass `--request-id <id>` to make retries idempotent — reuse the same id when retrying a mutating call after a transport failure.
- **Timecodes are always zero-padded `HH:MM:SS.mmm`**, copied straight from tool output — never raw seconds. Use that shape in tool inputs and when reporting moments to the user.
- **When calling tools, refer to assets by their exact absolute path (in Kestroll, not the local path)**

## Links to the Web App

- **Show the user the composition by providing the item URL**: Results contain web links: a composition reference becomes a markdown link to its project in the web app, and an asset reference becomes a link to the media library directory with that asset selected. **Include these links when you report results to your user** — they are how the user opens what you made in the browser.
- The url of the main app is `https://app.kestroll.com`.

## Getting files in and out

To get assets in an out of Kestroll:

```bash
kestroll upload <local-path> [kestroll-path]        # ingest local footage (dirs OK)
kestroll download <kestroll-path> [local-path]      # add --recursive for folders
```

Kestroll paths may be absolute (`/Footage/clip.mp4`) or root-relative. After an `export_composition` call completes, download the rendered MP4 with `kestroll download`. To look up an asset's full path, use the `search` tool. After uploading new footage, it must be processed before editing — use `asset_processing`, and `await_processing` to wait.

## Tool map

Run `kestroll tools list` for the authoritative set (availability varies per organization). Broad shape:

- **Read / discovery**: `search`, `get_asset_data` (transcripts, metadata, frames), `folders`, `people`, `collections`, `match_moments`, `preview_composition_frame`, `inspect_tracked_faces`, `web_search_assets`, `docs`, `await_processing`.
- **Editing**: `artifact_editor` (create, view, and edit compositions and collections by authoring YAML), `transcript_editor`, `duplicate_composition`, `export_composition`, `verify_scene_framing`, `independent_review`, `presentations`, `image_generator`.
- **Library / ops**: `edit_asset_data`, `move_assets`, `project`, `sync_assets`, `unsync_assets`, `asset_processing`, `file_intake`

## Parallel work with subagents

If your harness supports subagents or parallel tool calls, use them for fan-out work: reading transcripts across many assets, hunting candidate moments per asset, gathering metadata for a large folder, or verification passes. Each subagent runs the same CLI — pass the session id explicitly (`--session <id>` or the `KESTROLL_TOOL_SESSION` env var) rather than relying on the saved current session.

Parallelize **read-only** work freely. Keep **mutating** work (composition edits, exports, library changes) in a single lane: the session tracks which artifact versions have been viewed, and concurrent edits to the same artifact will conflict.

## Use the docs tool — don't work from memory

The `docs` tool lists, searches, and reads Kestroll's docs. These docs were written for you, use them! Any time you have a question about the correct way to do something in Kestroll, search the docs rather than guessing.

- **Before authoring or editing composition YAML, reading the relevant `editing/` docs is mandatory** — the schema and the `artifact_editor` commands, at minimum. Composition YAML is strictly validated, and authoring from memory is the top failure mode. This skill deliberately does not duplicate the schema. `docs read` with a `#anchor` path
- Whenever you are unsure how a Kestroll feature behaves (captions, split-screen layouts, motion graphics, exports, processing states), search the docs before improvising or asking the user.
- When a tool result or validation warning references a concept you don't recognize, look it up in the docs before retrying.