@pixerate/editor 0.221.0 → 0.222.0

package/dist/image-editor/edit-tools.d.cts

@@ -2,7 +2,7 @@ import type { AgentTool } from '../tools/registry.cjs';
 import type { ImageEditorController } from './controller.cjs';
 /**
  * Agent tools for the image editor's layers, geometry and history: `get_image_info`,
- * `get_histogram`, `update_adjustment_layer`, `remove_adjustment_layer`,
+ * `get_histogram`, `measure_region`, `update_adjustment_layer`, `remove_adjustment_layer`,
  * `move_adjustment_layer`, `set_crop`, `reset_crop`, `set_rotation`, `flip_image`,
  * `set_bit_depth`, `undo_image` and `redo_image`. Each write is one undo step and returns what changed.
  */

package/dist/image-editor/edit-tools.d.ts

@@ -2,7 +2,7 @@ import type { AgentTool } from '../tools/registry.js';
 import type { ImageEditorController } from './controller.js';
 /**
  * Agent tools for the image editor's layers, geometry and history: `get_image_info`,
- * `get_histogram`, `update_adjustment_layer`, `remove_adjustment_layer`,
+ * `get_histogram`, `measure_region`, `update_adjustment_layer`, `remove_adjustment_layer`,
  * `move_adjustment_layer`, `set_crop`, `reset_crop`, `set_rotation`, `flip_image`,
  * `set_bit_depth`, `undo_image` and `redo_image`. Each write is one undo step and returns what changed.
  */

package/dist/image-editor/index.cjs

@@ -2807,6 +2807,21 @@ function inspectMaskEdge(mask, image, options = {}) {
     blk.x1 = Math.max(blk.x1, x);
     blk.y1 = Math.max(blk.y1, y);
   };
+  const antiAliased = (x, y) => {
+    let full = false;
+    let none = false;
+    for (let dy = -2; dy <= 2; dy++) {
+      for (let dx = -2; dx <= 2; dx++) {
+        const nx = x + dx;
+        const ny = y + dy;
+        if (nx < 0 || ny < 0 || nx >= W || ny >= H) continue;
+        const n = a[ny * W + nx];
+        if (n === 255) full = true;
+        else if (n === 0) none = true;
+      }
+    }
+    return full && none;
+  };
   const x0 = Math.max(0, b.x - 1);
   const y0 = Math.max(0, b.y - 1);
   const x1 = Math.min(W, b.x + b.width + 1);
@@ -2836,7 +2851,7 @@ function inspectMaskEdge(mask, image, options = {}) {
       const partial = v > 0 && v < 255;
       if (hi && lo || partial) {
         band++;
-        if (partial) soft++;
+        if (partial && !antiAliased(x, y)) soft++;
       }
       if (v < 128) continue;
       const inCanvasLow = (nx, ny) => nx >= 0 && ny >= 0 && nx < W && ny < H && a[ny * W + nx] < 128;
@@ -13784,7 +13799,7 @@ function createImageSelectionTools(controller) {
   const inspectEdge = {
     name: "inspect_mask_edge",
     title: "Inspect a mask edge",
-    description: "Measures the edge of the selection (default), a layer's painted mask (layer-mask) or its vector mask (vector-mask), so you can check it without looking. Returns haloScore 0-1 (background colour left just inside the edge; worse above 0.35), edgeAlignment 0-1 (share of the edge on strong image edges; worse below 0.5), jaggedness (outline turning in radians per 100 px beyond what closing it needs; smooth outlines score under 3, worse above 15), softFraction 0-1 (share of edge pixels partly selected), holes and islands (count, total area, the 10 largest with bounds), worst (up to 5 regions with a reason, ready for capture_view rect) and issues (findings with a suggested fix; empty when clean). Measures a pixel layer's masks against its own pixels, otherwise the composite. Read-only: inspect, fix the issues, inspect again.",
+    description: "Measures the edge of the selection (default), a layer's painted mask (layer-mask) or its vector mask (vector-mask), so you can check it without looking. Returns haloScore 0-1 (background colour left just inside the edge; worse above 0.35), edgeAlignment 0-1 (share of the edge on strong image edges; worse below 0.5), jaggedness (outline turning in radians per 100 px beyond what closing it needs; smooth outlines score under 3, worse above 15), softFraction 0-1 (share of edge pixels in a transition wider than anti-aliasing), holes and islands (count, total area, the 10 largest with bounds), worst (up to 5 regions with a reason, ready for capture_view rect) and issues (findings with a suggested fix; empty when clean). Measures a pixel layer's masks against its own pixels, otherwise the composite. Read-only: inspect, fix the issues, inspect again.",
     inputSchema: {
       type: "object",
       properties: {
@@ -15310,10 +15325,43 @@ function createImageEditTools(controller) {
     annotations: { title: "Read the histogram", ...READ },
     handler: ({ bins }) => {
       const h = controller.getHistogram();
-      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again.");
+      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again, or measure_region, which needs no render.");
       return histogramSummary(h, bins);
     }
   };
+  const measureRegion = {
+    name: "measure_region",
+    title: "Measure part of the image",
+    description: "Measures the composited image (every layer and adjustment, before crop, rotation and output opacity) in a rectangle, without rendering: the histogram summary of get_histogram (per channel and luminance mean, 1st / 99th percentiles 0-255, clipping percentages) plus the mean colour as hex and a cast (red minus blue, green minus the red-blue average, in levels; near 0 is neutral). Use it to check a correction in numbers: a known-neutral area (a white wall, a grey card) should have a cast within about \xB14; skin, sky or a product colour should land where you aim. Works where render_preview cannot. Annotation layers are left out.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "integer", minimum: 0, description: "Left edge in natural image pixels (default: the crop, else the whole image)." },
+        y: { type: "integer", minimum: 0, description: "Top edge in natural image pixels." },
+        width: { type: "integer", minimum: 1, description: "Width in pixels." },
+        height: { type: "integer", minimum: 1, description: "Height in pixels." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Measure part of the image", ...READ },
+    handler: ({ x, y, width, height }) => {
+      const given = [x, y, width, height].filter((v) => v !== void 0).length;
+      if (given !== 0 && given !== 4) throw new Error("Give x, y, width and height together, or none to measure the crop (or the whole image).");
+      const { width: W, height: H } = controller.getState().imageDimensions;
+      const rect3 = given ? { x, y, width, height } : _nullishCoalesce(controller.getState().crop, () => ( { x: 0, y: 0, width: W, height: H }));
+      if (rect3.x + rect3.width > W || rect3.y + rect3.height > H) throw new Error(`The rectangle runs past the image (${W} \xD7 ${H} px); keep x + width \u2264 ${W} and y + height \u2264 ${H}.`);
+      const h = computeHistogram(controller.compositePixels(rect3));
+      const summary3 = histogramSummary(h, void 0);
+      const mean = (bins) => {
+        let sum = 0;
+        for (let i = 0; i < bins.length; i++) sum += i * bins[i];
+        return h.samples ? sum / h.samples : 0;
+      };
+      const [r, g, b] = [mean(h.red), mean(h.green), mean(h.blue)];
+      const hex = "#" + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+      return { rect: rect3, ...summary3, meanColor: h.samples ? hex : null, cast: { redBlue: round(r - b, 1), greenMagenta: round(g - (r + b) / 2, 1) } };
+    }
+  };
   const updateLayer = {
     name: "update_adjustment_layer",
     title: "Change an adjustment layer",
@@ -15470,7 +15518,7 @@ function createImageEditTools(controller) {
       return history();
     }
   };
-  return [getImageInfo, getHistogram, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
+  return [getImageInfo, getHistogram, measureRegion, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
 }
 
 // src/image-editor/layer-tools.ts

package/dist/image-editor/index.js

@@ -2807,6 +2807,21 @@ function inspectMaskEdge(mask, image, options = {}) {
     blk.x1 = Math.max(blk.x1, x);
     blk.y1 = Math.max(blk.y1, y);
   };
+  const antiAliased = (x, y) => {
+    let full = false;
+    let none = false;
+    for (let dy = -2; dy <= 2; dy++) {
+      for (let dx = -2; dx <= 2; dx++) {
+        const nx = x + dx;
+        const ny = y + dy;
+        if (nx < 0 || ny < 0 || nx >= W || ny >= H) continue;
+        const n = a[ny * W + nx];
+        if (n === 255) full = true;
+        else if (n === 0) none = true;
+      }
+    }
+    return full && none;
+  };
   const x0 = Math.max(0, b.x - 1);
   const y0 = Math.max(0, b.y - 1);
   const x1 = Math.min(W, b.x + b.width + 1);
@@ -2836,7 +2851,7 @@ function inspectMaskEdge(mask, image, options = {}) {
       const partial = v > 0 && v < 255;
       if (hi && lo || partial) {
         band++;
-        if (partial) soft++;
+        if (partial && !antiAliased(x, y)) soft++;
       }
       if (v < 128) continue;
       const inCanvasLow = (nx, ny) => nx >= 0 && ny >= 0 && nx < W && ny < H && a[ny * W + nx] < 128;
@@ -13784,7 +13799,7 @@ function createImageSelectionTools(controller) {
   const inspectEdge = {
     name: "inspect_mask_edge",
     title: "Inspect a mask edge",
-    description: "Measures the edge of the selection (default), a layer's painted mask (layer-mask) or its vector mask (vector-mask), so you can check it without looking. Returns haloScore 0-1 (background colour left just inside the edge; worse above 0.35), edgeAlignment 0-1 (share of the edge on strong image edges; worse below 0.5), jaggedness (outline turning in radians per 100 px beyond what closing it needs; smooth outlines score under 3, worse above 15), softFraction 0-1 (share of edge pixels partly selected), holes and islands (count, total area, the 10 largest with bounds), worst (up to 5 regions with a reason, ready for capture_view rect) and issues (findings with a suggested fix; empty when clean). Measures a pixel layer's masks against its own pixels, otherwise the composite. Read-only: inspect, fix the issues, inspect again.",
+    description: "Measures the edge of the selection (default), a layer's painted mask (layer-mask) or its vector mask (vector-mask), so you can check it without looking. Returns haloScore 0-1 (background colour left just inside the edge; worse above 0.35), edgeAlignment 0-1 (share of the edge on strong image edges; worse below 0.5), jaggedness (outline turning in radians per 100 px beyond what closing it needs; smooth outlines score under 3, worse above 15), softFraction 0-1 (share of edge pixels in a transition wider than anti-aliasing), holes and islands (count, total area, the 10 largest with bounds), worst (up to 5 regions with a reason, ready for capture_view rect) and issues (findings with a suggested fix; empty when clean). Measures a pixel layer's masks against its own pixels, otherwise the composite. Read-only: inspect, fix the issues, inspect again.",
     inputSchema: {
       type: "object",
       properties: {
@@ -15310,10 +15325,43 @@ function createImageEditTools(controller) {
     annotations: { title: "Read the histogram", ...READ },
     handler: ({ bins }) => {
       const h = controller.getHistogram();
-      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again.");
+      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again, or measure_region, which needs no render.");
       return histogramSummary(h, bins);
     }
   };
+  const measureRegion = {
+    name: "measure_region",
+    title: "Measure part of the image",
+    description: "Measures the composited image (every layer and adjustment, before crop, rotation and output opacity) in a rectangle, without rendering: the histogram summary of get_histogram (per channel and luminance mean, 1st / 99th percentiles 0-255, clipping percentages) plus the mean colour as hex and a cast (red minus blue, green minus the red-blue average, in levels; near 0 is neutral). Use it to check a correction in numbers: a known-neutral area (a white wall, a grey card) should have a cast within about \xB14; skin, sky or a product colour should land where you aim. Works where render_preview cannot. Annotation layers are left out.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "integer", minimum: 0, description: "Left edge in natural image pixels (default: the crop, else the whole image)." },
+        y: { type: "integer", minimum: 0, description: "Top edge in natural image pixels." },
+        width: { type: "integer", minimum: 1, description: "Width in pixels." },
+        height: { type: "integer", minimum: 1, description: "Height in pixels." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Measure part of the image", ...READ },
+    handler: ({ x, y, width, height }) => {
+      const given = [x, y, width, height].filter((v) => v !== void 0).length;
+      if (given !== 0 && given !== 4) throw new Error("Give x, y, width and height together, or none to measure the crop (or the whole image).");
+      const { width: W, height: H } = controller.getState().imageDimensions;
+      const rect3 = given ? { x, y, width, height } : controller.getState().crop ?? { x: 0, y: 0, width: W, height: H };
+      if (rect3.x + rect3.width > W || rect3.y + rect3.height > H) throw new Error(`The rectangle runs past the image (${W} \xD7 ${H} px); keep x + width \u2264 ${W} and y + height \u2264 ${H}.`);
+      const h = computeHistogram(controller.compositePixels(rect3));
+      const summary3 = histogramSummary(h, void 0);
+      const mean = (bins) => {
+        let sum = 0;
+        for (let i = 0; i < bins.length; i++) sum += i * bins[i];
+        return h.samples ? sum / h.samples : 0;
+      };
+      const [r, g, b] = [mean(h.red), mean(h.green), mean(h.blue)];
+      const hex = "#" + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+      return { rect: rect3, ...summary3, meanColor: h.samples ? hex : null, cast: { redBlue: round(r - b, 1), greenMagenta: round(g - (r + b) / 2, 1) } };
+    }
+  };
   const updateLayer = {
     name: "update_adjustment_layer",
     title: "Change an adjustment layer",
@@ -15470,7 +15518,7 @@ function createImageEditTools(controller) {
       return history();
     }
   };
-  return [getImageInfo, getHistogram, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
+  return [getImageInfo, getHistogram, measureRegion, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
 }
 
 // src/image-editor/layer-tools.ts

package/dist/image-editor/selection/inspect.d.cts

@@ -31,7 +31,7 @@ export interface MaskEdgeReport {
     edgeAlignment: number;
     /** Turning of the outline beyond what closing it needs, in radians per 100 px of outline (0: smooth). */
     jaggedness: number;
-    /** 0–1: the share of edge pixels that are partly covered (0 < α < 1). */
+    /** 0–1: the share of edge pixels in a transition wider than anti-aliasing (partly covered, no fully selected and unselected pixel within 2 px). */
     softFraction: number;
     /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
     holes: {

package/dist/image-editor/selection/inspect.d.ts

@@ -31,7 +31,7 @@ export interface MaskEdgeReport {
     edgeAlignment: number;
     /** Turning of the outline beyond what closing it needs, in radians per 100 px of outline (0: smooth). */
     jaggedness: number;
-    /** 0–1: the share of edge pixels that are partly covered (0 < α < 1). */
+    /** 0–1: the share of edge pixels in a transition wider than anti-aliasing (partly covered, no fully selected and unselected pixel within 2 px). */
     softFraction: number;
     /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
     holes: {

package/package.json

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

package/skills/README.md

@@ -5,6 +5,11 @@ Each editor domain in `@pixerate/editor` ships an [Agent Skill](https://agentski
 expert in the domain would follow. They are published with the package, so an app or agent
 that uses the tools can load the matching skill.
 
+## Reference skills
+
+One per editor domain. A reference skill owns its domain's tool and command tables, its mental
+model and its general practice.
+
 | Skill | Covers |
 | --- | --- |
 | [`pixerate-agent-tools`](pixerate-agent-tools/SKILL.md) | What every editor has in common: the MCP bridge, toolsets and tool naming, finding tools with `list_toolsets` / `search_tools` / `enable_tools` / `get_skill`, `list_commands` / `run_command` / `run_commands`, errors, undo. Load it with any domain skill. |
@@ -15,12 +20,9 @@ that uses the tools can load the matching skill.
 | [`pixerate-chart`](pixerate-chart/SKILL.md) | Chart specs, data, series, presets, trendlines, Office and Mermaid charts. |
 | [`pixerate-diagram`](pixerate-diagram/SKILL.md) | Mermaid diagrams: nodes, edges, groups, layout. |
 | [`pixerate-image-editor`](pixerate-image-editor/SKILL.md) | Adjustments, adjustment layers, selections and masks. |
-| [`pixerate-image-selection-masking`](pixerate-image-selection-masking/SKILL.md) | Workflow: cutouts, background and sky replacement, local adjustments through masks; choosing a selection method, checking and refining edges, and outputting an editable mask. Built on `pixerate-image-editor`'s tools. |
 | [`pixerate-paint-editor`](pixerate-paint-editor/SKILL.md) | Natural-media painting: paper and grain, dry-media brushes, the brush library, strokes as data, pigment mixing. |
 | [`pixerate-animation-editor`](pixerate-animation-editor/SKILL.md) | Vector animation: shots, commands, timing, Flair and Lottie. |
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
-| [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. |
-| [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
 | [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
 | [`pixerate-tokens`](pixerate-tokens/SKILL.md) | Design tokens: collections, modes, variables and aliases, through the whole-set document tools. |
@@ -28,6 +30,23 @@ that uses the tools can load the matching skill.
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 | [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
 
+## Workflow skills
+
+A workflow skill covers one job from start to finish: what to confirm first, the steps in
+order with a check after each, a decision table, recipes and the job's pitfalls. It is built on
+its reference skill's tools (load both), and its description is written about the job, so a
+request like "clean up this export" finds it.
+
+| Skill | Editor | Covers |
+| --- | --- | --- |
+| [`pixerate-image-selection-masking`](pixerate-image-selection-masking/SKILL.md) | Image (`pixerate-image-editor`) | Cutouts, background and sky replacement, local adjustments through masks; choosing a selection method, checking and refining edges, and outputting an editable mask. |
+| [`pixerate-image-photo-correction`](pixerate-image-photo-correction/SKILL.md) | Image (`pixerate-image-editor`) | Global correction in order: straighten and crop, exposure and white balance, points and contrast, colour, local, look; each checked for clipping and neutral greys. |
+| [`pixerate-image-portrait-retouch`](pixerate-image-portrait-retouch/SKILL.md) | Image (`pixerate-image-editor`) | Blemishes, stray hairs and flaws healed on their own layer, dodge and burn, eyes and teeth, kept natural. |
+| [`pixerate-image-product-photo`](pixerate-image-product-photo/SKILL.md) | Image (`pixerate-image-editor`) | Product cutouts on pure white or a brand colour, a grounding shadow, accurate colour, centred marketplace crops. |
+| [`pixerate-spreadsheet-clean-import`](pixerate-spreadsheet-clean-import/SKILL.md) | Spreadsheet (`pixerate-spreadsheet`) | Imported or pasted data made tidy: structure, headers, types (currency, comma decimals, day-first dates, leading zeros, missing values), text, duplicates and validation. |
+| [`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. |
+
 ## Using them
 
 Copy or symlink the directories into your agent's skills folder, for example for Claude Code:
@@ -75,12 +94,27 @@ same change.
   `create*ToolProvider` / `create*Commands` factory is not mapped to a skill. A new domain
   gets a new skill directory, an entry in `expectedBySkill()` and `FACTORIES`, and a row in
   the table above.
-- **Workflow skills.** A skill that covers one job end to end on another skill's tools (for
-  example `pixerate-image-selection-masking` on `pixerate-image-editor`) has no tool table.
-  Its frontmatter adds `metadata` with `kind: workflow` and `reference: <skill>`, it lists the
-  tools it uses as bullets under `## Tools used`, and it is mapped in `WORKFLOWS` in the test
-  (and to `[]` in `expectedBySkill()`). The test checks that every tool it uses exists in the
-  reference skill.
+- **Workflow skills.** A skill that covers one job end to end on another skill's tools has no
+  tool table (unless the job has its own provider, as the two video ones do). Start from
+  [`WORKFLOW_TEMPLATE.md`](WORKFLOW_TEMPLATE.md). Its frontmatter adds `metadata` with
+  `kind: workflow` and `reference: <skill>`; it lists the tools it uses as bullets under
+  `## Tools used`; and it is mapped in `WORKFLOWS` in the test (and to `[]` in
+  `expectedBySkill()`). The test checks that every tool it uses exists in the reference skill,
+  that every backticked tool or command name in its prose is real, that the reference skill
+  names it under `## Workflow skills`, that it stays under 250 body lines (aim for 200) and that
+  it ships evals. Add its row to the workflow table above.
+- **Evals.** Each workflow skill ships at least three scenarios in `evals/*.json`, run by
+  `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" }` or
+  `{ "editor": "image", "width", "height", "background", "shapes" }`), `checks` (a read-only
+  tool, 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
+  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":
+  "layers.-1.id" }`. Checks test the outcome the user asked for, not one way of getting it.
 - **Workflows and practice.** The test cannot check advice. When a feature changes the best
   way to do something (a new batch tool, a new check, a better default), update the working
   method and best practices too.

package/skills/WORKFLOW_TEMPLATE.md

@@ -0,0 +1,50 @@
+---
+name: pixerate-<editor>-<job>
+description: The <job> workflow in the Pixerate <editor> - <what it produces, in the user's words, and the main steps>. Use when asked to <trigger phrases: the verbs and nouns people use for this job>, or when <a tool or two that signal the job> are available. Load with pixerate-<editor>, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-<editor>
+---
+
+# <The job, as a short title>
+
+<Two to four sentences: the model of the job a person needs before starting. What the
+document is made of here, and the one or two facts that make this job go right or wrong.>
+
+This skill is the method. `pixerate-<editor>` has the full tool reference.
+
+## Goal and quality bar
+
+- <What the finished result is, stated so it can be checked: numbers, ranges, absences.>
+- <What must stay editable, reversible or untouched.>
+
+## Inputs to confirm
+
+Ask when you cannot tell from the document; say what you assumed when you can.
+
+- **<Decision>:** <the options, and the default when the user does not say>.
+
+## Working method
+
+1. **<Step>.** <What to do, with which tool and which arguments matter (units, defaults).>
+   **Check:** <a read tool and what its result must show before going on>.
+2. **<Step>.** ...
+   **Check:** ...
+
+## Decision table
+
+| Situation | Approach |
+| --- | --- |
+| <case> | <method, tool, setting> |
+
+## Recipes
+
+**<Common request>.** <The tool calls in order, with arguments, as short prose.>
+
+## Pitfalls
+
+- **<Failure>.** <Why it happens and how to avoid or detect it.>
+
+## Tools used
+
+- `<tool_name>`, `<tool_name>`: <one-line purpose in this job>

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

@@ -7,20 +7,13 @@ description: How to colour-correct, composite and retouch a photo in the Pixerat
 
 The image editor holds a layer stack over a canvas the size of the source image. Opening an
 image gives one pixel layer, **Background**, whose pixels are the source and whose `develop`
-filter holds the base adjustments; adjustment layers sit above it (bottom to top, each through
-its mask, opacity and blend mode) and every annotation is its own layer on top (pen, rectangle,
-ellipse, line and arrow annotations are shape layers, text annotations type layers, that remember
-them). `list_layers`
-shows the whole stack. Edits never touch the source pixels. The base controls edit the develop
-filter of the active pixel layer (the Background unless another pixel layer is active); base
-`blur` blurs that layer (or, in documents saved before layers with blur and adjustment layers,
-the output after the layers), and base `opacity` is the output's alpha. Pixel, annotation, group
-and smart object layers can carry live effects (shadows, glows, bevels, overlays, strokes). A smart
-object places contents (pixels or a nested layer document) through a transform and smart filters,
-re-rendered from the contents on every change. A shape layer holds vector paths with a fill and a
-stroke, rendered again from the paths on every change, so it stays sharp through any transform. A
-type layer holds live, styled text (point or paragraph) drawn with the editor's fonts.
-Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for errors and batching.
+filter holds the base adjustments (the base controls edit the develop filter of the active pixel
+layer). Adjustment layers sit above it, each through its mask, opacity and blend mode, and
+annotations are shape and type layers on top. Edits never touch the source pixels; `list_layers`
+shows the whole stack. Pixel, group and smart object layers can carry live effects; a smart
+object places contents through a transform and smart filters; shape layers hold vector paths and
+type layers live text, re-rendered on every change. There is also an optional selection and a
+crop, rotation and flip. See `pixerate-agent-tools` for errors and batching.
 
 - **Control ids** for base adjustments: `brightness`, `contrast`, `exposure`, `temperature`,
   `tint`, `saturation` (all -100..100, default 0), `blur` (0..30 px) and `opacity` (0..1).
@@ -33,25 +26,31 @@ Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for
 - **Coordinates** for selections are natural pixels of the source image (before crop, rotate
   or flip). Read `get_selection` bounds or the image size, never screen pixels.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-image-photo-correction`: global correction in order (frame, light, colour, local, look), with clipping and neutral checks.
+- `pixerate-image-selection-masking`: cutouts, background and sky replacement, local adjustments through masks.
+- `pixerate-image-portrait-retouch`: blemishes, stray hairs, dodge and burn, eyes and teeth.
+- `pixerate-image-product-photo`: product on white, a grounding shadow, marketplace crops.
+
 ## Working method
 
 1. **Read.** `get_adjustments` for the current values, process version and layers;
    `get_image_info` for the image size, crop and rotation; `list_controls` once for control
    ids, ranges, layer kinds and blend modes; `render_preview` (default 512 px) to see the
    image, then `get_histogram` to judge exposure and clipping in numbers.
-2. **Plan the order of corrections** (see Best practices): straighten and crop first (so
-   later judgements are on the final frame), then global tone and white balance,
-   then contrast and tone curves, then colour, then local fixes through masks, then creative
-   looks.
+2. **Plan the order:** frame, light, colour, local, look (`pixerate-image-photo-correction`).
 3. **Write in few steps.** Put every base change of one correction into one `set_adjustments`
    call (one undo step) with a `label`. Create layers with their `params` in the same
    `add_adjustment_layer` call rather than adding a neutral layer and then setting it.
 4. **Local edits:** select, refine, check with `get_selection`, then `apply_selection_as_mask`
    with a `kind`. Load `pixerate-image-selection-masking` for cutouts, masks and local edits.
-5. **Verify.** `render_preview` after each group of corrections, not after each slider, then
-   `get_histogram` (it reads the last render) for clipping. Compare against the previous
-   preview; read the `applied` and `clamped` lists that writes return. `undo_image` takes back a
-   step that made things worse.
+5. **Verify** after each group of corrections: `measure_region` (no render needed) or
+   `render_preview` then `get_histogram`; read the `applied` and `clamped` lists writes return.
+   `undo_image` takes back a step that made things worse.
 
 ### Working with layers
 
@@ -85,12 +84,9 @@ filters, so nothing degrades. Read [references/smart-objects.md](references/smar
 
 ### Shapes and text
 
-Draw boxes, badges, arrows and callouts as shape layers (`add_shape_layer` with a live `shape`,
-then `set_shape_component` / `update_shape` / `add_shape_component`), and text as type layers
-(`add_text_layer`, then `set_text`, `set_text_style`, `set_paragraph_style` by `start` / `end`
-range). Both stay sharp through transforms and take effects, masks and blend modes; rasterize only
-to paint on them. Read [references/shapes-and-type.md](references/shapes-and-type.md) before
-drawing or editing either.
+Boxes, badges, arrows and callouts are shape layers (`add_shape_layer`), text is type layers
+(`add_text_layer`); both stay sharp and take effects, masks and blends. Read
+[references/shapes-and-type.md](references/shapes-and-type.md) before drawing or editing either.
 
 ### Layer effects
 
@@ -110,12 +106,11 @@ selection or locked transparency. Read [references/painting.md](references/paint
 ### Colour management
 
 Working space, profiles, soft proofing and print conversions: read [references/color-management.md](references/color-management.md).
+
 ### Retouching
 
-Clone Stamp, Healing Brush, Spot Healing, Smudge, Dodge, Burn, Sponge, Blur, Sharpen and the
-History Brush: retouch on an empty layer with `sample: "current-below"`, pick `spot_heal` for small
-spots, `heal_brush` for larger flaws and `clone_stamp` to copy exactly (`set_clone_transform` scales,
-rotates or flips the source), and keep strokes short and soft. Read [references/retouching.md](references/retouching.md) first.
+Heal, clone, dodge and burn on layers above the photo (`sample: "current-below"`): load
+`pixerate-image-portrait-retouch`, and read [references/retouching.md](references/retouching.md) first.
 
 ### Photoshop files
 
@@ -128,27 +123,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 - **Non-destructive first.** Prefer an adjustment layer over pushing a base slider to its
   limit: layers can be masked, faded with `opacity`, blended and stacked. Use base sliders for
   global exposure and white balance, layers for everything you may want to tune later.
-- **Order of corrections** (as in a raw / Photoshop workflow): exposure and white balance
-  (`exposure`, `temperature`, `tint`) → black and white points and contrast (a `levels` layer,
-  then a gentle S-curve `curves` layer) → colour (`vibrance` before `saturation`,
-  `hueSaturation` per range, `colorBalance`) → local adjustments through masks → creative looks
-  (`photoFilter`, `blackWhite`, `posterize`). Correct before you stylise.
-- **Avoid clipping.** Set levels black and white points (`master.inBlack`, `master.inWhite`)
-  just inside where the image data starts (the histogram's `p1` / `p99`), not past it; large
-  `exposure` or `contrast` values blow highlights and crush shadows in the output. More than
-  about 0.5% of pixels in `clipping.highlightsPercent` or `shadowsPercent` on a normal photo
-  means detail is lost; check bright skies, skin and deep shadows in `render_preview` too.
-- **Straighten, then crop.** Level horizons with `set_rotation` (small angles such as -2.5);
-  any angle that is not a quarter turn leaves transparent corners, so crop inside them with
-  `set_crop` afterwards. Keep a standard aspect ratio (3:2, 4:3, 16:9, 1:1, 4:5) unless asked
-  otherwise, and do not crop away the subject's space to look or move into.
-- **Small moves.** Real corrections are usually within ±10..30 on these scales. Prefer
-  `vibrance` over `saturation` for portraits (it protects already-saturated colours and skin).
-- **Contrast through curves.** A curves S-curve keeps endpoints fixed and avoids the flat
-  greys that a big `contrast` value with low `exposure` produces. Curve points are levels
-  0..255 (`{ input, output }`); keep `(0,0)` and `(255,255)` and move quarter-tones by 10..25.
-- **Neutral greys.** Use `temperature` / `tint` (or `colorBalance` midtones) so known-neutral
-  areas (white walls, grey roads, clouds) have no cast; then add warmth deliberately if wanted.
+- **Correct in order** (frame, light, colour, local, look) and measure clipping and neutrals after
+  each step: `pixerate-image-photo-correction` has the method and settings.
 - **Masks:** select, refine, then mask; see `pixerate-image-selection-masking`.
 - **Blend modes for tone-only or colour-only changes:** `luminosity` applies a curves or
   levels layer without shifting hue or saturation; `color` applies a tint without changing
@@ -159,29 +135,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
   natural colour mixing and painterly strokes; it is not a Photoshop mode, so keep it off
   layers that must survive a PSD round trip. It costs about ten times a normal blend.
 - **Name layers** (`name`) by intent ("Sky darken", "Warm skin"), so the stack stays readable.
-- **Effects: subtle first.** A drop shadow reads as natural with a small `distance` (2..10 px),
-  a `size` a little larger than the distance, `opacity` 0.3..0.6 and the default multiply; a
-  hard, dark, far shadow looks pasted on. Glows want `screen` and a light colour; strokes on
-  text 1..4 px. Bevels: `depth` 1..2 and `size` a fraction of the shape's thickness.
-- **Outline-only looks** (an outlined title, a glass button): set the layer's `fillOpacity` to
-  0 with `set_layer_properties` and keep its effects; fill opacity hides the layer's own pixels,
-  layer `opacity` fades the effects too.
-- **Prefer an effect over painted pixels** for shadows, glows, outlines and colour fills of a
-  shape: it follows later edits and stays adjustable.
-- **Transforms: one resample, bicubic, whole pixels when you can.** Combine a scale, rotation and
-  move into one `transform_layer` call; use `rotate_layer_90` / `flip_layer` (exact) instead of
-  `rotate: 90` or `scaleX: -100`. `interpolation: "nearest"` keeps hard pixel art crisp; bicubic
-  (default) is right for photos, bilinear is a little softer. Enlarging past about 200 % shows
-  softness: prefer a larger source.
-- **Scale proportionally** unless asked to stretch: give `scaleX` and `scaleY` the same value.
-  Keep the subject in frame: after a scale about `center` the layer can run past the canvas,
-  which `bounds` in the result shows.
-- **Smart objects for anything you may scale again.** Convert first, then transform as often as
-  needed; set exact sizes with `set_smart_object_transform` `scaleX` / `scaleY` (percent of the
-  contents) rather than chaining relative scales. Prefer smart filters over layer filters when
-  the user may want to mask, blend or reorder them later.
-- **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
-  identical (a logo placed twice); use `linked: false` when the copies will be edited apart.
+- **Effects, transforms and smart objects** have their own best practices in
+  `references/layer-effects.md`, `references/free-transform.md` and `references/smart-objects.md`.
 - **Merge Down only onto an opaque, 100 % lower layer** when the result must look the same:
   the merged layer keeps the lower layer's opacity and blend, so a faded lower layer fades the
   merged content too, and a blend mode on the upper layer stops seeing what was below the lower
@@ -209,6 +164,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
 | `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, `bitDepth` (8, 16 or 32), the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
 | `get_histogram` | Judge exposure numerically: per channel and luminance `mean`, `p1` and `p99` (0..255), and `clipping` percent at pure black and white per channel. Reads the last render, so call `render_preview` first. `bins` (16, 32, 64 or 256) adds the counts. Cheaper than another image for checking a tonal change. |
+| `measure_region` | Measure a rectangle of the composited image (`x`, `y`, `width`, `height` in natural pixels; default the crop, else the whole image) without a render: the `get_histogram` summary plus `meanColor` (hex) and `cast` (`redBlue`, `greenMagenta` in levels; within about ±4 is neutral). Check a neutral reference, skin, a background or clipping after each correction. |
 | `render_preview` | See the edited image (crop, adjustments, layers, annotations) as a PNG, or with `layerId` one layer alone. `maxSide` 16..2048 px, default 512. Images cost tokens: render after a group of edits, use 512 for overall look and 1024+ to judge clipping, edges and masks. Fails in environments without rendering. |
 | `inspect_psd` | Read a PSD / PSB (`data` base64) without opening it: size, `depth`, `colorMode`, `resolution`, every layer bottom first with `psdKind`, the `type` it would become (`smart`, `shape` and `type` for Photoshop smart objects, shapes and text) and `status` (`mapped`, `approximated`, `dropped`) with `notes`, and the import `warnings`. Call before `import_psd`. |
 | `export_psd` | Save the document as an RGB PSD at its bit depth (PSB above 30000 px) with layers, groups, adjustment layers and masks. Returns `data` (base64), `size` in bytes, `psb` and `warnings` (crop or rotation not applied, filters and depth masks baked, annotations rasterized or left out, Pigment blends written as Normal). Shape and type layers are written as real Photoshop shape and type layers. Changes nothing. |

package/skills/pixerate-image-editor/references/free-transform.md

@@ -20,3 +20,14 @@ How to move, scale, rotate, skew, distort and warp layers, selected pixels and m
 4. **Transform once.** Every call resamples the pixels, so chained calls soften them: put scale,
    rotation and move into one `transform_layer` call (or one matrix) instead of several.
 5. **Look**: `render_preview`, or `capture_view` at the edges; each call is one undo step.
+
+## Best practices
+
+- **Transforms: one resample, bicubic, whole pixels when you can.** Combine a scale, rotation and
+  move into one `transform_layer` call; use `rotate_layer_90` / `flip_layer` (exact) instead of
+  `rotate: 90` or `scaleX: -100`. `interpolation: "nearest"` keeps hard pixel art crisp; bicubic
+  (default) is right for photos, bilinear is a little softer. Enlarging past about 200 % shows
+  softness: prefer a larger source.
+- **Scale proportionally** unless asked to stretch: give `scaleX` and `scaleY` the same value.
+  Keep the subject in frame: after a scale about `center` the layer can run past the canvas,
+  which `bounds` in the result shows.

package/skills/pixerate-image-editor/references/layer-effects.md

@@ -22,3 +22,15 @@ Read this before `add_layer_effect`, `update_layer_effect`, `set_global_light` o
    every effect of a layer (each keeps its own `enabled`); `scale` resizes them all (Scale
    Effects), e.g. after resizing a layer's content.
 5. **Look after each change**: `render_preview` (with `layerId` for one layer alone).
+
+## Best practices
+
+- **Effects: subtle first.** A drop shadow reads as natural with a small `distance` (2..10 px),
+  a `size` a little larger than the distance, `opacity` 0.3..0.6 and the default multiply; a
+  hard, dark, far shadow looks pasted on. Glows want `screen` and a light colour; strokes on
+  text 1..4 px. Bevels: `depth` 1..2 and `size` a fraction of the shape's thickness.
+- **Outline-only looks** (an outlined title, a glass button): set the layer's `fillOpacity` to
+  0 with `set_layer_properties` and keep its effects; fill opacity hides the layer's own pixels,
+  layer `opacity` fades the effects too.
+- **Prefer an effect over painted pixels** for shadows, glows, outlines and colour fills of a
+  shape: it follows later edits and stays adjustable.

package/skills/pixerate-image-editor/references/smart-objects.md

@@ -26,3 +26,12 @@ How to work with smart objects in the image editor (see the main skill for the t
    in a new image for every linked instance; `export_smart_object_contents` returns the file.
 6. **Finish**: `rasterize_smart_object` only when the user wants plain pixels to paint on; the
    placement and filters are then gone.
+
+## Best practices
+
+- **Smart objects for anything you may scale again.** Convert first, then transform as often as
+  needed; set exact sizes with `set_smart_object_transform` `scaleX` / `scaleY` (percent of the
+  contents) rather than chaining relative scales. Prefer smart filters over layer filters when
+  the user may want to mask, blend or reorder them later.
+- **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
+  identical (a logo placed twice); use `linked: false` when the copies will be edited apart.