onboarding · diff
git:20261007.0741b8f to git:20261009.9add511
41 added, 88 removed. Audit A to A.
---
name: onboarding
- description: "Orientation skill for new agents and users. Explains what Montaj is and how it works. Use it when the user asks questions about montaj or is getting started"
- ---
-
- # Montaj — Orientation
-
- ---
-
- ## What Montaj is
-
- A video editing toolkit that mounts on top of an agent harness. **You bring the brain. Montaj gives agents the tools.**
-
- Montaj doesn't edit on its own. It provides discrete operations — trim, transcribe, remove fillers, caption, resize, composite overlays — and the agent decides which to call, in what order, with what parameters. The agent is the editor. Montaj is the toolbox.
-
- ---
-
- ## How it compares
-
- Most programmatic video tools (Remotion, Revideo) have the agent **write code** that describes a composition. Montaj takes the opposite approach: the agent **calls tools** against existing footage. Agent can still write code on top of existing footage for overlays and animations, but montaj is desigend to work **around and with existing footage**. The agent reasons about which steps to apply and executes them.
-
- GUI tools (Premiere, DaVinci, Descript, Runway) are driven by a human. Every decision is a click. Montaj is designed for the agent to drive — the human reviews the result and performs last mile edits, the bulk of the process is agent driven.
-
- **Where Montaj is the right choice:**
- - You have raw footage and want an agent to produce an edited video
- - You need captions, overlays, and trim decisions made from the content itself
- - You want to define a reusable editing style for an account and apply it automatically
- - You want to run locally, no API keys required
-
- **Where Montaj is not the right choice:**
- - You want to generate AI videos from scratch (use Veo, Runway, etc)
- - You want a human-driven rich GUI with fine-grained manual control
- - You want an agent to edit videos based purely on visuals and not on trascripts / audio
-
+ description: "A guided first session in the Montaj app: what Montaj is, checking the connection, then walking the user through their first edit from their own footage, from the clips to the exported video. Load it right after Montaj is installed, or when the user asks to get started or what Montaj is."
---
- ## What is a project
-
- A project is one video being made. Everything lives in a single file: `project.json`.
-
- ```
- pending → agent edits → draft → human reviews → final → render → MP4
- ```
-
- - `pending` — created, clips and prompt attached, waiting for the agent
- - `draft` — agent is done; ready for human review
- - `final` — reviewed and approved; ready to render
-
- The agent reads `project.json`, calls steps, writes it back as it works. The UI watches the file and rerenders the timeline on every write.
+ # Getting started with Montaj
- ---
+ Walk the user through their first session, one step at a time. Keep each message short, ask one question at a time, and wait for the answer. Do the work with the Montaj connection's tools. If you have not loaded it yet, call `get_skill` with `mcp`: it says which tool does each thing.
- ## Where things live
+ ## 1. Say what Montaj is
- ```
- ~/Montaj/ ← workspace — all projects live here
- 2025-04-01-product-demo/
- project.json ← the project (pending → draft → final)
- clip.mp4
- clip_spec.json ← trim spec (editing decisions, no re-encode)
- clip_transcript.json ← word-level timestamps
- overlays/hook.jsx ← agent-authored overlay components
- output.mp4 ← final render
+ In two or three lines, for example:
- ~/.montaj/ ← user config + extensions
- config.json ← workspaceDir, model, render settings
- credentials.json ← API keys (never committed)
- profiles/<name>/ ← account style profiles
- steps/ ← custom steps
- workflows/ ← custom workflows
+ > Montaj is a video editor on your computer that I can drive. You bring your footage; I cut it, caption it and add graphics, and you review it in the Montaj app and export it. Your footage stays on your computer.
- montaj/ ← built-in (ships with Montaj)
- steps/
- workflows/
- skills/
- ```
+ ## 2. Check the connection
- ---
+ Call `get_plan`.
- ## Account styles (Style Profiles)
+ - It answers with the user's plan: you are connected. Don't read the plan out and don't bring up upgrades.
+ - "Montaj isn't set up on this computer yet": the app is still opening, or was never opened. Ask the user to open the Montaj app, wait a minute, then try again.
+ - "Montaj isn't running" or "Montaj isn't open": ask the user to open the Montaj app, then try again.
+ - "Montaj was moved or updated": ask the user to quit and reopen this AI app so it reconnects.
- A style profile captures the visual and editorial identity of a social media account — pacing, cut frequency, color palette, caption style, tone. Once created, it gets injected into every project for that account so editing decisions stay consistent automatically.
+ If the Montaj window still shows its welcome screens, ask the user to finish them first.
- Profiles live at `~/.montaj/profiles/<name>/style_profile.md` and are loaded into your agent context when tagged selected in the UI or manually seeked on the prompt.
+ ## 3. Ask what they want to do first
- To create or update one: call get_skill with `app/style-profile`. It is a Montaj Hub skill, served by the Montaj app.
+ Offer three choices and recommend the first:
- ---
+ 1. **Edit a video from your own footage** (recommended): a clip you filmed, trimmed and captioned.
+ 2. **Try a template**: the kinds of video Montaj makes.
+ 3. **Set up your style profile**: I study your account and save how you make videos, so later edits follow it.
- ## The UI
+ Then:
- `montaj serve` starts a local server and opens `http://localhost:3000`.
+ - **1**: go to section 4.
+ - **2**: ask the user to open **Projects**, then **New project**, in the Montaj app. Each card shows what that template makes. When they pick one, make the project with `create_project` and that template's `workflow` (see section 4), then load the skills its workflow names. If the tool says the template needs a plan the user doesn't have, tell them once, with the link it gives, and ask what they'd like to do instead.
+ - **3**: call `get_skill` with `app/style-profile` and follow it. If it says it needs another plan, tell the user once, with the link it gives, and ask what they'd like to do instead.
- The Editor tab drives the core flow: upload clips + prompt → watch the agent work live → review and tweak → render. The agent writes `project.json` as it works; the UI reflects every change in real time via SSE.
+ ## 4. The first edit, step by step
- Four tabs: **Editor**, **Workflows** (node graph), **Overlays** (live JSX preview), **Profiles** (style profiles).
+ 1. **Get the clips.** Ask where the footage is.
+ - The user gives you the clips' file paths: use them in the next step. For a link (YouTube, or a direct video link), call `import_media` with the `url`, then `get_import_status` with its `jobId` until it is done, and use the `path` it gives.
+ - Or the user adds the clips in the app: **Projects**, then **New project**, then **Talking head**. They drop the clips on **Drop your clips** (or use **Browse files**), write what they want in **Prompt**, and click **Run**. The app makes the project and shows **Send this to your AI** with a message to copy. Ask them to paste it here: it has the project's id. Then skip to step 3.
+ 2. **Make the project.** Confirm a short name and what they want (length, tone, captions) with the user, then call `create_project` with `workflow` `overlays` (the Talking head template), `name`, `prompt` in the user's words, and `clips` as the absolute paths. It returns the project's id, with status pending, and a `link`.
+ 3. **Make the edit.** Call `get_skill` with `montaj` and follow it to start the pending project. Tell the user what you are doing as you go: each step's progress line shows live in the Montaj window too. Some steps take a while; say so rather than going quiet.
+ 4. **Review it in the editor.** When the edit is saved as a draft, give the user the project's `link`: it opens the project in Montaj. (They can also click **Projects**, then the project.) They can play it, trim on the timeline and fix captions by hand. Ask what they'd like changed, then call `get_skill` with `edit-session` and follow it. When they point at something on screen, call `get_editor_state` to see where they are looking.
+ 5. **Export.** The user clicks **Export** at the top of the editor. When it says **Render complete**, **Download** gives them the file, and Montaj also keeps it as `<project name>.mp4` in the project's `output` folder, inside the `Montaj` folder in their home folder.
- ---
+ ## 5. What else Montaj can do
- ## Getting started
+ Don't explain these now. Name them when the user asks for something they cover, and load the skill with `get_skill`:
- In the Montaj app the server is already running; never ask its user to run a command. On the command line only, start it with `montaj serve`, and if it warns or fails, tell the user the easiest fix (such as `montaj install ui`).
+ - `edit-session`: changes to a draft: cuts, timing, overlays.
+ - `speech-edit`: cut words, pauses and failed takes by editing the transcript as text.
+ - `select-takes`: keep the best take of each part when they filmed several.
+ - `write-overlay` and `overlay`: titles, callouts and animated graphics.
+ - `image-search`: find real images to put in a video.
+ - `carousel`: swipeable image slides.
+ - `ai-video-plan`: a video generated from a prompt, with a storyboard first.
- Ask the user:
+ `list_skills` lists every skill this user can load.
- > "Before we start — do you want to set up a style profile for your account first, or jump straight into editing a video?
- >
- > **Style profile:** I'll analyze your existing content (or a URL you paste) and build an editing style that gets applied automatically to every project for that account — pacing, caption style, color palette, tone.
- >
- > **Edit a video:** Tell me the location of your clips or drop them in the UI, and I'll run the full edit pipeline for whatever content style you pick. You can always add a style profile later."
+ On the command line, without the Montaj app, follow the root `montaj` skill instead.
- - If **style profile**: call get_skill with `app/style-profile` and follow it.
- - If **edit a video**: load `skills/SKILL.md` and follow it.