pireel

Pireel Studio

Pireel Studio (https://pireel.com) is a multi-source, multi-track video editor that can produce multiple independently editable cuts from one project. Your tools edit the composition live in the user's open studio browser tab via the pireel MCP server; when no tab is open, data-level tools fall back to OFFLINE MODE against the user's latest project.

This one skill covers the whole product. Skim the essentials below, then open the matching file in references/ for the task at hand — don't work from memory on the specialized flows.

Essentials (true for everything)

• What you edit. Typed tracks of clips: a primary video story spine (role=primary), concurrent B-roll / PiP (role=broll), a graphics lane, narration / music / SFX audio lanes, and one managed caption track. Clip kinds: narrative (spoken story footage), media (video or image on any lane), graphic — a Component (Motion Graphics are the main Component family today), audio, and text (native titles set with set_texts). Every clip occupies integer frames [start, end) on the timeline and keeps its own source clock in seconds; media clips carry framing (full / punch-in / corner-* / split-* treatments, or an exact transform / crop via set_clip_framing), speed, color filter and audio treatment (set_clip_properties). A cut between story-spine clips is a hard cut by default; add_transition adds one where a change of time, place, chapter or mode earns it.
• Speech is one editing surface, not the entrance. When footage carries speech, get_transcript + remove_words edit it by transcript (never by frames). When it doesn't — B-roll, product footage, screen recordings, music-led montage — edit by time, picture and sound with the same clip tools (add_clips / insert_clips / split_clips / move_clips / ripple_delete_ranges / set_clip_properties / set_clip_framing / add_clips {role:"music"}). Never ask for a script or transcript before editing speechless footage; get_transcript reporting no coverage is information, not an error.
• get_state once per session — then patch from deltas. Every mutation returns a delta (touched clips, shifted rules, removedClipIds, removedSource, caption changes); re-read get_state only after a failed mutation, an output/project switch, an undo, or when a receipt note says the state is stale. Ids for clips/tracks/components/frames/presets come from get_state, tool receipts, manage_frame {action:"list"}, or the caption catalog. Never invent an id.
• Two clocks. "edited" = timeline frames (startFrame / atFrame / fromFrame / toFrame / durationFrames — add_clips, split_clips, ripple_delete_ranges, move_clips, apply_component address by it; get_state gives the fps and every tool converts, never multiply by fps yourself). "src" = a clip's own source-file seconds (source [inSec, outSec]; a transcript is stamped in its own source's clock and never moves when the timeline is cut). Don't mix them.
• BYO generation is free. Text/markup you write yourself (component composition, the plan you hold in working context, visual labels) runs on the user's own agent subscription, NOT Pireel credits. Only tools whose description carries a […CHARGES…] marker bill credits (image/video/audio/speech generation + Pireel-LLM fallbacks such as apply_component {generate:true}). Prefer the BYO path.
• Surface the editor early on real work. Call create_browser_handoff and open the returned url with YOUR OWN built-in/embedded browser tool — on Codex, use the in-app Browser runtime rather than connected Chrome. Never use the OS open/start/xdg-open, the user's default browser, or an already-connected external Chrome proactively (single-use ticket, ~60s). Keep that tab visible and open past your turn using its keep/finalize controls (details in references/pireel-basics.md). Never print the handoff url.

Routing — read the reference for the task

The user wants to…	Read
Install / connect / set up Pireel, or a tool reports it's not connected	references/getting-started.md
Understand the model + tool routing in depth (read before the first edit)	references/pireel-basics.md
Use an account private/community Studio Skill or its bound voice	references/pireel-basics.md
Use a LOCAL video or image file	references/asset-import.md
Edit a speech-led video end to end (interview, lesson, commentary, podcast, direct-to-camera): cleanup, restructure, B-roll, graphics, sound	references/craft/talking-head-edit.md
Clean up a raw talking-head A-roll only (retakes, filler, dead air)	references/talking-head-cleanup.md
Compose a montage from a body of footage (emotion, motifs, rhythm, sound)	references/craft/montage-edit.md, then references/montage-variants.md for output families / variants
Mix several clips into product ads or create multiple editable outputs / variants	references/montage-variants.md
Edit footage that has no speech (B-roll, product shots, screen recordings, music-led material)	references/pireel-basics.md (clip tools) → references/craft/montage-edit.md for a deliberate assembly
Add / fit background music, sound effects, per-clip sound, transitions, or beat-aligned cuts	references/craft/audio-and-music.md
Add a designed graphic component (BYO markup)	references/compose-blocks.md
Design or execute a complete first cut / finished video	references/storyboard-draft.md
Add / restyle captions	references/captions.md
Export an MP4	references/export.md
Answer pricing / credits / plan / UI questions	references/product-help.md
Recover from a tool error, timeout, or apply_component lint rejection	references/known-errors.md

references/craft/ holds Pireel's built-in craft skills verbatim — the same playbooks the Studio chat uses and that list_skills / read_skill serve over MCP. Read the local copy (no round trip); if the MCP server announces a workflow baseline different from your installed VERSION, prefer read_skill for the freshest text.

The local media import helper lives at scripts/import-media.mjs (Node ≥ 20, zero dependencies).

Locating the references. Every path above (references/…, scripts/…) is relative to THIS skill's own directory — the folder that contains this SKILL.md. If your agent hands you the skill directory, read them directly. If it doesn't, locate this skill once and resolve from there, e.g. find ~ -path '*/skills/pireel/SKILL.md' 2>/dev/null (Codex/Claude Code install skills as plain files on disk); the references sit in references/ right next to this file, and references/product-help/ holds the pricing/UI sub-docs.

Billing

Agent orchestration and every BYO flow run on the user's own agent subscription, not Pireel credits. Pireel bills only media generation (images/video) and the audio/vision pipelines (transcription, visual analysis). Details in references/product-help.md.

Keeping this workflow current

A Plugin bundle is updated by its host — skip this. You are one if the host reports a Plugin identity, or a plugin manifest sits two directories above this SKILL.md.

Otherwise the server announces its workflow baseline and the VERSION file next to this SKILL.md is yours. Both are opaque release tags: compare for equality, never order them. If they differ, run npx skills update pireel (fallback: npx skills add pireel/pireel-agent) through the host's normal command-approval flow, then re-read the updated files. After one attempt — or if the mechanism is unavailable or VERSION is missing — mention it once and continue. Don't nag when they match.