@pixerate/editor 0.222.2 → 0.223.0

package/dist/tools/skill-evals.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The evals that workflow skills ship in `skills/<name>/evals/*.json`, for any harness to run.
+ *
+ * An eval is a task a model would be given (`prompt`), the document it starts from
+ * (`fixture`), the checks that decide whether the job was done (`checks`: a read tool, its
+ * arguments and what its result must match) and one known-good answer (`solution`: the tool
+ * calls an expert would make). The package's own tests prove each eval with its `solution`; an
+ * agent harness builds the fixture, gives its model the `prompt` in place of the solution, then
+ * runs `failedEvalChecks`. The format is described in `skills/README.md`.
+ */
+import type { McpToolResult } from './registry.js';
+export interface SkillEvalToolCall {
+    tool: string;
+    args?: Record<string, unknown>;
+}
+export interface SkillEvalCheck extends SkillEvalToolCall {
+    /** What the check is for, shown when it fails. */
+    why: string;
+    expect: unknown;
+}
+export interface SkillEval {
+    prompt: string;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture;
+    checks: SkillEvalCheck[];
+    solution: SkillEvalToolCall[];
+}
+export interface SpreadsheetEvalFixture {
+    editor: 'spreadsheet';
+    /** Raw inputs from A1, row by row, typed as a person would (`'` forces text). */
+    rows: Array<Array<string | number | boolean | null>>;
+}
+export interface ImageEvalFixture {
+    editor: 'image';
+    width: number;
+    height: number;
+    /** RGB background. */
+    background: [number, number, number];
+    /** Shapes painted over it in order, with RGB colours. */
+    shapes: Array<{
+        shape: 'rect' | 'ellipse';
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: [number, number, number];
+    }>;
+}
+export interface VectorEvalFixture {
+    editor: 'vector';
+    width: number;
+    height: number;
+    /** Commands that build the starting artwork, run in order (`"$0.id"` refers to an earlier result). */
+    setup?: Array<{
+        id: string;
+        params?: Record<string, unknown>;
+    }>;
+}
+export interface PaintEvalFixture {
+    editor: 'paint';
+    width: number;
+    height: number;
+    /** Tool calls that prepare the canvas (paper, layers, strokes), run in order. */
+    setup?: SkillEvalToolCall[];
+}
+export interface VideoEvalFixture {
+    editor: 'video';
+    /** Tool calls that build the starting project (settings, assets, clips, markers), run in order. */
+    setup?: SkillEvalToolCall[];
+}
+/** One eval file of a skill. */
+export interface SkillEvalFile {
+    skill: string;
+    /** Path relative to the skills directory, e.g. `pixerate-image-selection-masking/evals/local-adjustment.json`. */
+    path: string;
+    eval: SkillEval;
+}
+/**
+ * The evals in a set of skill files (paths relative to the skills directory, contents as text,
+ * like `SkillFiles` but including `evals/*.json`), sorted by path.
+ */
+export declare function listSkillEvals(files: Readonly<Record<string, string>>): SkillEvalFile[];
+/** The RGBA pixels of an image fixture: shapes painted over the background in order. */
+export declare function imageEvalFixturePixels(f: ImageEvalFixture): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** Calls a tool by the bare name an eval uses; the harness maps it to its own names if it must. */
+export type SkillEvalToolCaller = (tool: string, args: Record<string, unknown>) => Promise<McpToolResult>;
+/** Calls one eval tool step (resolving `$read` arguments); throws with the tool's error text. */
+export declare function callEvalTool(callTool: SkillEvalToolCaller, { tool, args }: SkillEvalToolCall): Promise<unknown>;
+/**
+ * Whether `actual` matches `expected`. Objects match key by key (other keys are ignored),
+ * arrays element by element with the same length, other values exactly. Operators:
+ * `$min` / `$max` (numbers), `$type`, `$match` (a regular expression, or `[pattern, flags]`), `$in`, `$not`,
+ * `$every` / `$some` (array elements), `$length`, `$unique`, `$distinct` (the distinct
+ * values), `$sum`, `$column: [index, matcher]` (one column of a 2D array), `$nonEmpty`
+ * (the array without empty cells or rows) and `$expr` (a JavaScript expression over `v`).
+ */
+export declare function matchesEvalExpectation(actual: unknown, expected: unknown): boolean;
+/** The checks that fail, each as its `why` with what the tool returned (or its error). */
+export declare function failedEvalChecks(callTool: SkillEvalToolCaller, checks: readonly SkillEvalCheck[]): Promise<string[]>;

package/dist/tools/skills.d.cts

@@ -13,11 +13,22 @@ export interface SkillInfo {
     description: string;
     /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
     references: string[];
+    /**
+     * `workflow` for a skill that covers one job from start to finish on a reference skill's tools
+     * (frontmatter `metadata.kind: workflow`); otherwise `reference`.
+     */
+    kind: 'reference' | 'workflow';
+    /** A workflow skill's reference skill (frontmatter `metadata.reference`), whose tools it uses. */
+    reference?: string;
 }
-/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+/**
+ * Reads `name`, `description` and the one-level `metadata` map (`metadata.kind`,
+ * `metadata.reference`, …) from a SKILL.md's YAML frontmatter.
+ */
 export declare function parseSkillFrontmatter(markdown: string): {
     name?: string;
     description?: string;
+    metadata: Record<string, string>;
     body: string;
 };
 /** The skills in a set of skill files, sorted by name. */

package/dist/tools/skills.d.ts

@@ -13,11 +13,22 @@ export interface SkillInfo {
     description: string;
     /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
     references: string[];
+    /**
+     * `workflow` for a skill that covers one job from start to finish on a reference skill's tools
+     * (frontmatter `metadata.kind: workflow`); otherwise `reference`.
+     */
+    kind: 'reference' | 'workflow';
+    /** A workflow skill's reference skill (frontmatter `metadata.reference`), whose tools it uses. */
+    reference?: string;
 }
-/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+/**
+ * Reads `name`, `description` and the one-level `metadata` map (`metadata.kind`,
+ * `metadata.reference`, …) from a SKILL.md's YAML frontmatter.
+ */
 export declare function parseSkillFrontmatter(markdown: string): {
     name?: string;
     description?: string;
+    metadata: Record<string, string>;
     body: string;
 };
 /** The skills in a set of skill files, sorted by name. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.222.2",
+  "version": "0.223.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -50,6 +50,9 @@ request like "clean up this export" finds it.
 | [`pixerate-paint-watercolour`](pixerate-paint-watercolour/SKILL.md) | Paint (`pixerate-paint-editor`) | Watercolour paper, light to dark with the paper's white kept, wet-in-wet and wet-on-dry washes, drying before glazing, steering the water. |
 | [`pixerate-paint-oil-impasto`](pixerate-paint-oil-impasto/SKILL.md) | Paint (`pixerate-paint-editor`) | A toned ground, thin block-in to thick paint, pigment mixing, impasto relief and its light. |
 | [`pixerate-paint-sketch-to-finish`](pixerate-paint-sketch-to-finish/SKILL.md) | Paint (`pixerate-paint-editor`) | Sketch, ink, flats under the lines, clipped shading and light, one named layer per pass. |
+| [`pixerate-video-social-cut`](pixerate-video-social-cut/SKILL.md) | Video (`pixerate-video-editor`) | Vertical or square reframes that fill the frame, the hook first, platform lengths, titles in the safe area. |
+| [`pixerate-video-colour-grade`](pixerate-video-colour-grade/SKILL.md) | Video (`pixerate-video-editor`) | Correct and match shots, then one look on an adjustment clip; LUTs at moderate strength with skin protected. |
+| [`pixerate-video-montage`](pixerate-video-montage/SKILL.md) | Video (`pixerate-video-editor`) | Selects on the beat, varied pacing, short transitions with handles, music under everything and a clean ending. |
 | [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Video (`pixerate-video-editor`) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. Owns the dialogue tools. |
 | [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Video (`pixerate-video-editor`) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. Owns the music tools. |
 
@@ -113,12 +116,14 @@ same change.
   `packages/core/tests/agent-skill-evals.test.ts`. An eval has a `prompt` (the task, in the
   user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }`,
   `{ "editor": "image", "width", "height", "background", "shapes" }` or `{ "editor":
-  "vector", "width", "height", "setup" }` with commands that draw the starting art, or
-  `{ "editor": "paint", "width", "height", "setup" }` with tool calls), `checks` (a read-only
+  "vector", "width", "height", "setup" }` with commands that draw the starting art, 
+  `{ "editor": "paint", "width", "height", "setup" }` or `{ "editor": "video", "setup" }` with tool calls), `checks` (a read-only
   tool, or `run_command` with a read-only command such as `vector.list`, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
   tool calls an expert would make). The test proves each eval: some check fails on the fixture,
   and all pass after the solution. A model harness runs the same file with the model in place
-  of the solution. In `expect`, objects match key by key and arrays element by element, with
+  of the solution, using `@pixerate/editor/tools`: `listSkillEvals` reads the eval files,
+  `imageEvalFixturePixels` paints an image fixture, and `failedEvalChecks` runs the checks
+  through the harness's own tool calls (`matchesEvalExpectation` is the matcher on its own). In `expect`, objects match key by key and arrays element by element, with
   operators for ranges and lists (`$min`, `$max`, `$match`, `$every`, `$some`, `$length`,
   `$unique`, `$distinct`, `$sum`, `$column`, `$nonEmpty`, `$not`, `$in`, `$type`); a check's
   argument can read a value the job created with `{ "$read": "list_layers", "path":

package/skills/pixerate-agent-tools/SKILL.md

@@ -42,7 +42,9 @@ editor's, or (in discovery mode) only `list_toolsets`, `search_tools`, `enable_t
    toolset when you will use many of its tools). The tools then appear in your list. Use
    `disable_tools` to drop a toolset you are done with.
 4. **Read the skill before working in a toolset.** `get_skill` with the skill `list_toolsets`
-   names (or the MCP prompt / `skill://` resource of the same name).
+   names (or the MCP prompt / `skill://` resource of the same name). When the task is a whole
+   job one of the toolset's `workflows` covers (a cutout, a photo correction, an icon set), read
+   that workflow skill too: it has the steps in order and the check after each.
 5. **Read the house style when there is one.** A toolset with a `style` field in
    `list_toolsets` (or an `enable_tools` result with a `style` line) has house-style skills:
    call `get_style` with that domain before you make or change work there.
@@ -149,11 +151,11 @@ Never repeat an identical failing call. Never work around a read-only refusal; t
 | Tool | Use it to |
 | --- | --- |
 | `list_editors` | See which editors are open in the browser and connected to the MCP bridge (id, name, kind, tool count, last activity). Call it first when tools come through the bridge; pass an id or part of a name as `editor` to any tool to pick one when several are open, otherwise the most recently active editor with that tool answers. If none is connected, ask the user to open the app and connect it. |
-| `list_toolsets` | See the toolsets open now: name, title, what each covers, its skill, how many tools it has and whether they are in your tool list (`enabled`: all, some, none). Call it first in a discovery view, then `search_tools` or `enable_tools`. |
+| `list_toolsets` | See the toolsets open now: name, title, what each covers, its skill, its workflow skills (`workflows`), how many tools it has and whether they are in your tool list (`enabled`: all, some, none). Call it first in a discovery view, then `search_tools` or `enable_tools`. |
 | `search_tools` | Find the tool for a task: pass `query` in plain words (and `toolset` to search one editor, `limit` for more than 10). Returns the best matches first with name, toolset, title, one-sentence summary, whether it only reads and whether it is listed. Follow with `enable_tools`. |
 | `enable_tools` | Add tools to your tool list by full name (`tools`, from `search_tools`) and/or whole `toolsets` (from `list_toolsets`). Returns the names added and how many are listed. Prefer single tools to large toolsets. Unknown names fail and change nothing. Allowed tools can also be called by name without enabling them. |
 | `disable_tools` | Drop tools or whole toolsets you are done with from your tool list, to keep it short. Returns the names removed. |
-| `get_skill` | Read a toolset's skill (markdown) before working with it; pass `file` for one of its reference files (listed at the top). The note at the top says how names are prefixed here. |
+| `get_skill` | Read a toolset's skill (markdown) before working with it, and the workflow skill for the job when one fits; pass `file` for one of its reference files (listed at the top). The note at the top says how names are prefixed here. |
 | `list_styles` | See the house-style skills here, general layer first: name, description, layer, the domains each applies to, which have a profile, whether each is on, and issues that leave all or part of one out. Pass `domain` to see one domain's. Follow with `get_style`. |
 | `get_style` | Read the house style for a `domain` before you make or change work there: each skill's preferences as a `<style_skill>` block naming its layer, the merged profile (tokens resolved), `sources` (which layer set each field) and `issues`. Then check your work with the domain's `check_<domain>_style`. |
 | `get_style_file` | Read one file of a house-style skill (`name`, `file`), such as a `references/*.md` its preferences point to, or its raw profile (`chart.json`) before tokens are resolved. An unknown file fails with the list of its files. |

package/skills/pixerate-paint-watercolour/evals/sky-wash.json

@@ -12,7 +12,7 @@
 		{ "tool": "set_brush", "args": { "id": "watercolor-wash" } },
 		{ "tool": "set_color", "args": { "color": "#6fa8dc" } },
 		{ "tool": "paint_stroke", "args": { "points": [{ "x": 0, "y": 6 }, { "x": 64, "y": 6 }, { "x": 64, "y": 14 }, { "x": 0, "y": 14 }] } },
-		{ "tool": "advance_wet_paint", "args": { "seconds": 30 } },
+		{ "tool": "advance_wet_paint", "args": { "seconds": 3 } },
 		{ "tool": "dry_paint" },
 		{ "tool": "get_wet_paint" }
 	]

package/skills/pixerate-video-colour-grade/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pixerate-video-colour-grade
+description: The colour grading workflow in the Pixerate video editor - correcting each shot first (exposure, contrast, white balance) so a scene matches, then one look over the whole piece on an adjustment clip, LUTs at a sensible strength with skin tones protected, masks for spot changes, and checking with scopes and frames. Use when asked to colour correct, colour grade, match shots, fix exposure or white balance in a video, add a look, a LUT, a film or cinematic look, warm or cool a video, or protect skin tones, or when update_video_clip grade, add_video_adjustment_clip, set_video_lut or get_video_scopes are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Grading a video
+
+A grade has two passes. **Correction** makes each shot right and makes shots in a scene match:
+exposure, contrast and white balance on the clip's own `grade`. **The look** is one creative
+decision over everything: an adjustment clip above the timeline with its own grade or a LUT,
+so it is changed in one place. Faces are the reference: people notice skin that is wrong before
+anything else.
+
+This skill is the method. `pixerate-video-editor` has the full tool reference.
+
+## Goal and quality bar
+
+- Shots in a scene match in brightness and colour; cuts between them do not jump.
+- Corrections are moderate: exposure within about ±1 stop, contrast and saturation within
+  ±0.3, white balance within ±0.3, unless a shot is badly off.
+- One look, in one place: an adjustment clip over the whole timeline (or one per scene), not
+  the same settings pasted on every clip.
+- Skin stays natural under strong looks (skin protection 0.5-0.8 on LUTs).
+- The original corrections are not overwritten by the look.
+
+## Inputs to confirm
+
+- **The look:** natural, warm, cool, desaturated, high contrast, a named LUT; or a reference.
+- **Which shot is the reference** for matching (the best-exposed, or the one the user likes).
+- **Where the LUT file is** (a `.cube` path or URL the host can load).
+
+## Working method
+
+1. **Read.** `get_video_project` for clips and their `grade`; where the host has a preview,
+   `get_video_scopes` at a frame of each shot reads levels and colour in numbers.
+   **Check:** you know which shots are off and by how much.
+2. **Correct the reference shot** (`update_video_clip` `set.grade`): exposure first, then
+   contrast, then white balance (`temperature`, `tint`). The grade object replaces the clip's
+   whole grade, so pass every setting you want to keep.
+3. **Match the others to it.** A shot one stop under gets `exposure: 1`; a cooler shot more
+   `temperature`. `copy_video_grade` when shots from one camera setup need the same correction;
+   `apply_video_grade_preset` for a common starting point.
+   **Check:** the clip `grade` values; scopes or `get_video_frame` at both sides of each cut.
+4. **The look over everything.** `add_video_track` at the top (`at: 0`) and
+   `add_video_adjustment_clip` on it from 0 for the whole duration with the look's `grade`
+   (`scope: "underneath"`).
+   **Check:** one adjustment clip covering the timeline; media clips keep their corrections.
+5. **LUTs.** `set_video_lut` with `strength` 0.3-0.7 for a look (1 only for a technical
+   conversion LUT) and skin protection (`preserve_skin_tones: 0.7`, 0.5-0.8) when people are on screen;
+   `set_video_skin_protection` to change the protection later.
+   **Check:** each clip's `grade.lut` has the strength and protection you meant.
+6. **Spot changes.** `set_video_clip_mask` on a duplicate clip or an adjustment clip for a sky,
+   a face or a vignette.
+7. **Review.** `render_video_frame` with `times` across the piece for a contact sheet; fix any
+   shot that stands out.
+
+## Decision table
+
+| Problem | Fix |
+| --- | --- |
+| Shot too dark or bright | `grade.exposure` in stops (+1 doubles the light) |
+| Flat, low contrast | `grade.contrast` +0.1-0.3 |
+| Blue or orange cast | `grade.temperature` against it |
+| Green or magenta cast | `grade.tint` against it |
+| Same correction on many shots from one setup | `copy_video_grade` |
+| One look for the whole piece | Adjustment clip on a top track |
+| A LUT look | `set_video_lut`, strength 0.3-0.7 |
+| Faces off under the look | Skin protection 0.5-0.8 (`set_video_lut` or `set_video_skin_protection`), or lower the strength |
+| Change only part of the frame | `set_video_clip_mask` |
+
+## Recipes
+
+**Match an underexposed shot.** `update_video_clip` `{ clip, set: { grade: { exposure: 1 } } }`
+for one stop under; check with scopes or frames on both sides of the cut.
+
+**Warm, slightly desaturated look.** `add_video_track` `{ kind: "video", at: 0 }` →
+`add_video_adjustment_clip` `{ track, start: 0, duration: <project duration>, grade:
+{ temperature: 0.2, saturation: -0.15 } }`.
+
+**Tame a LUT.** `set_video_lut` `{ clips, src, strength: 0.6, preserve_skin_tones: 0.7 }`.
+
+## Pitfalls
+
+- **Grading before correcting.** A look over unmatched shots makes the mismatch stronger.
+- **Partial grade objects.** `set.grade` replaces the whole grade; read it first and include
+  the settings you keep.
+- **The look on every clip.** Pasting it per clip means every change is many edits; use an
+  adjustment clip.
+- **Full-strength creative LUTs** turn faces orange or green and crush detail.
+- **ffmpeg and skin protection.** The export's `lut3d` cannot protect skin; the export notes
+  it, and the preview differs from the file. Lower the strength when that matters.
+- **Judging on one frame.** Check several frames per shot; light changes within shots.
+
+## Tools used
+
+- `get_video_project`, `get_video_scopes`, `get_video_frame`, `render_video_frame`: read grades, measure and look
+- `update_video_clip`: each shot's correction (`set.grade`)
+- `copy_video_grade`, `apply_video_grade_preset`: match and start from a preset
+- `add_video_track`, `add_video_adjustment_clip`: one look over the timeline
+- `set_video_lut`, `remove_video_lut`, `set_video_skin_protection`: LUT looks and skin
+- `set_video_clip_mask`, `remove_video_clip_mask`: spot changes
+- `undo_video`: take back a step

package/skills/pixerate-video-colour-grade/evals/look-in-one-place.json

@@ -0,0 +1,16 @@
+{
+	"prompt": "Give the whole piece a warm, slightly desaturated look that I can tweak in one place later, on top of the shot corrections.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "one adjustment clip over the whole timeline", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "start": 0, "duration": { "$min": 12000 } } } } } } },
+		{ "why": "warm and a little desaturated", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "grade": { "temperature": { "$min": 0.05, "$max": 0.5 }, "saturation": { "$min": -0.4, "$max": -0.02 } } } } } } } },
+		{ "why": "the shots' own grades are left alone", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$expr": "v.filter((c) => c.type === 'media').every((c) => !c.grade)" } } } } }
+	],
+	"solution": [
+		{ "tool": "add_video_track", "args": { "kind": "video", "id": "v0", "at": 0 } },
+		{ "tool": "add_video_adjustment_clip", "args": { "track": "v0", "start": 0, "duration": 12000, "grade": { "temperature": 0.2, "saturation": -0.15 } } }
+	]
+}

package/skills/pixerate-video-colour-grade/evals/lut-keep-skin.json

@@ -0,0 +1,132 @@
+{
+	"prompt": "The teal-and-orange LUT on both shots is too strong and turns the faces orange. Tone the look down to a moderate strength and keep the skin tones natural.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "a",
+					"kind": "video",
+					"src": "shot-a.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "b",
+					"kind": "video",
+					"src": "shot-b.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "a",
+						"id": "c1",
+						"start": 0,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "b",
+						"id": "c2",
+						"start": 6000,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "set_video_lut",
+				"args": {
+					"clips": [
+						"c1",
+						"c2"
+					],
+					"src": "data:text/plain,TITLE%20%22Teal%20orange%22%0ALUT_3D_SIZE%202%0A0%200.1%200.1%0A1%200.5%200.2%0A0%201%200.9%0A1%201%200.6%0A0%200.2%201%0A1%200.4%200.9%0A0%201%201%0A1%201%201%0A",
+					"strength": 1
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the LUT is still on both shots, at a moderate strength",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$length": 2,
+							"$every": {
+								"grade": {
+									"lut": {
+										"src": {
+											"$match": "^data:"
+										},
+										"strength": {
+											"$min": 0.3,
+											"$max": 0.85
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "skin tones protected",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$every": {
+								"grade": {
+									"lut": {
+										"preserveSkinTones": {
+											"$min": 0.4
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_video_project"
+		},
+		{
+			"tool": "set_video_lut",
+			"args": {
+				"clips": [
+					"c1",
+					"c2"
+				],
+				"src": {
+					"$read": "get_video_project",
+					"path": "tracks.0.clips.0.grade.lut.src"
+				},
+				"strength": 0.6,
+				"preserve_skin_tones": 0.7
+			}
+		}
+	]
+}

package/skills/pixerate-video-colour-grade/evals/match-exposure.json

@@ -0,0 +1,14 @@
+{
+	"prompt": "Shot two (c2) was filmed one stop underexposed compared with shot one. Match it to shot one without touching shot one.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "c2 brought up by about one stop", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c2", "grade": { "exposure": { "$min": 0.8, "$max": 1.2 } } } } } } } },
+		{ "why": "shot one is untouched", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c1", "$expr": "!v.grade || Object.values(v.grade).every((x) => x === 0)" } } } } } }
+	],
+	"solution": [
+		{ "tool": "update_video_clip", "args": { "clip": "c2", "set": { "grade": { "exposure": 1 } } } }
+	]
+}

package/skills/pixerate-video-editor/SKILL.md

@@ -33,6 +33,9 @@ the pitfalls, and uses the tools below.
 
 - `pixerate-talking-head-edit`: dialogue cleanup by transcript: fillers, pauses, stutters.
 - `pixerate-bgm-alignment`: cutting to the beat, ducking music under speech, loudness.
+- `pixerate-video-social-cut`: vertical reframes, the hook first, platform lengths, titles in the safe area.
+- `pixerate-video-colour-grade`: correct and match shots, one look on an adjustment clip, LUTs and skin.
+- `pixerate-video-montage`: selects on the beat, pacing, transitions, music and the ending.
 
 ## Working method
 

package/skills/pixerate-video-montage/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-video-montage
+description: The montage workflow in the Pixerate video editor - choosing selects and their best moments, assembling them on beats or a rhythm, varying shot length for pacing, cutting on action, short transitions where they help, music under the whole sequence, and a clean start and end. Use when asked to make a montage, a highlight reel, a sizzle reel, a recap, a music video edit, a slideshow of clips or photos, or to cut a set of clips to music or a rhythm, or when edit_video, add_video_marker, set_video_transition or find_video_gaps are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Cutting a montage
+
+A montage tells its story through rhythm: the best moment of each shot, in an order that
+builds, cut to a beat. The work is choosing (selects and their best seconds), then placing
+(on the beat, with shot lengths that breathe and quicken), then finishing (transitions only
+where they help, music under everything, a clear ending).
+
+This skill is the method. `pixerate-video-editor` has the full tool reference; for beats in a
+music track and cutting to them, see `pixerate-bgm-alignment`.
+
+## Goal and quality bar
+
+- Each shot is its best moment: taken from the middle of the action, not its first frames
+  (`in` past the camera's settle).
+- Cuts land on beats or on action, on frame boundaries, with no gaps (`find_video_gaps` empty).
+- Pacing varies: longer shots to establish, shorter to build, a held shot to land.
+- Straight cuts by default; short crossfades (300-600 ms) or dips only for a reason (time
+  passing, a change of section), each with enough media on both sides (no handle errors).
+- Music runs under the whole sequence and ends with it (a fade out or a musical ending), and
+  the picture ends cleanly (a fade to black or a held final frame).
+
+## Inputs to confirm
+
+- **Selects and order:** which clips, in what order (story, chronology, energy).
+- **Rhythm:** music with beats, markers, or a shot length (e.g. 1 s per shot).
+- **Length** of the finished piece.
+
+## Working method
+
+1. **Read.** `get_video_project`: assets (with durations), markers (beats), music.
+   With music, `find_video_beats` (`pixerate-bgm-alignment`) marks the beats.
+   **Check:** you have a beat grid or a shot length, and each select's usable range.
+2. **Pick the moments.** For each select, the `in` point of its best stretch (skip the first
+   second or two, where the camera settles).
+3. **Assemble in one batch.** `edit_video` with one add-clip op per shot (`asset`, `id`, `in`,
+   `start` on a beat, `duration` to the next beat), `dry_run: true` first.
+   **Check:** the clips are in order, each `start` on a beat; `find_video_gaps` is empty.
+4. **Refine the rhythm.** `roll_video_edit` to move a cut to a beat or onto action without
+   shifting anything else; `slip_video_clip` to change what a shot shows without moving it.
+   Vary lengths: build up with shorter shots before the peak.
+5. **Transitions, sparingly.** `set_video_transition` `crossfade` 300-600 ms (or `dip` for a
+   section change); every type but dip needs half its length in media past the cut on both sides.
+   **Check:** `check_video_project` has no errors.
+6. **Music and ending.** The music clip on an audio track from 0 for the whole duration, with a
+   `fadeOut` of 1-3 s (or cut on its last beat); the last picture clip `fadeOut` 300-1000 ms to
+   black.
+   **Check:** `get_video_project` shows both, ending together.
+7. **Review.** `render_video_frame` with `times` at each cut for a contact sheet; watch the
+   rhythm in the preview where available.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| Energy, a build | Shorter shots toward the peak, cuts on every beat |
+| Calm, reflective | Longer shots, cuts every 2-4 beats, crossfades |
+| Time passing | Crossfade or dip between shots |
+| A section change | Dip to black or a held shot, then a new rhythm |
+| Continuity of motion | Cut on action (`roll_video_edit` onto the movement) |
+| Photos in a slideshow | Image assets, a slow push-in (`set_video_keyframes` scale 1 to 1.08) |
+
+## Recipes
+
+**On the beat.** Beats every `b` ms from 0: `edit_video` with `{ op: "add_clip", track: "v1", clip:
+{ type: "media", asset, id, in, start: k * b, duration: b } }` for each shot `k`; then `find_video_gaps`.
+
+**Crossfades.** `edit_video` with `{ op: "set_transition", clip, transition: { type: "crossfade",
+duration: 400 } }` for every clip after the first; then `check_video_project`.
+
+**Music and fade-out.** `add_video_clip` on the audio track `{ type: "media", asset: music,
+start: 0, duration: <sequence>, fadeOut: 2000 }`; `update_video_clip` on the last shot
+`{ set: { fadeOut: 500 } }`.
+
+## Pitfalls
+
+- **First frames of a clip** are often the camera settling; take `in` later.
+- **Transitions everywhere** soften the rhythm and look dated; cut straight by default.
+- **Missing handles.** A transition needs media past the cut on both sides; trimmed-to-the-edge
+  clips fail `check_video_project`.
+- **Music that stops dead** at the end of the picture; fade it or end on a musical phrase.
+- **Uniform shot lengths** for a long montage feel mechanical; vary them.
+
+## Tools used
+
+- `get_video_project`, `find_video_gaps`, `check_video_project`, `render_video_frame`: read and check
+- `add_video_marker`: beats and sections
+- `edit_video`, `add_video_clip`: assemble in one batch
+- `roll_video_edit`, `slip_video_clip`, `trim_video_clip`, `close_video_gaps`: refine the rhythm
+- `set_video_transition`: crossfades and dips
+- `update_video_clip`, `set_video_keyframes`: fades, volume and push-ins
+- `undo_video`: take back a step