@olegkoval/agent-skills 1.60.0 → 1.62.0

package/adapters/grok/olko-creative/skills/shorts-animator/scripts/sa.ts

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/*
+ * Shorts Animator: a script and a look in, an animated short out.
+ *
+ *   SA new <dir> [--look oil] [--format 9:16]   a project: short.json, scenes.js
+ *   SA looks                                     the looks, moods and voices, one line each
+ *   SA check <dir>                               finds what a render would get wrong, in a second, no browser
+ *   SA voice <dir>                               narrates every line (cached) and prints the timing
+ *   SA frames <dir>                              one painted frame per shot -> frames/sheet.jpg
+ *   SA still <dir> <shot> [at]                   one shot, full size -> frames/shot-NN.jpg
+ *   SA render <dir>                              the MP4: voice, score, every drawing -> <title>.mp4
+ *   SA set <dir> key=value...                    change short.json from the command line (JSON values)
+ *   SA doctor                                    checks the machine and renders a 3-second test
+ *
+ * SA = node <skill-dir>/scripts/sa.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { check, report } from "./domain/check.ts";
+import { resolveLook, pageState } from "./domain/look.ts";
+import { parseAssignment, setPath } from "./domain/patch.ts";
+import { isJson, isMap, parseShort } from "./domain/schema.ts";
+import { timeline } from "./domain/timeline.ts";
+import type { Json, JsonMap, Result, Short, Take, Timeline } from "./domain/types.ts";
+import { fail, ok } from "./domain/types.ts";
+import type { Page } from "./edge/chrome.ts";
+import { doctor } from "./edge/doctor.ts";
+import { encoder, jpeg, mkdir, readJson, stillSheet, videoSheet, writeJson } from "./edge/media.ts";
+import { pageErrors, paintPage } from "./edge/page.ts";
+import { kitNames, probeScenes } from "./edge/probe.ts";
+import { MOODS, soundtrack } from "./edge/sound.ts";
+import { cachedTakes, narrate } from "./edge/voice.ts";
+
+const LOOKS = path.join(import.meta.dirname, "looks");
+const VOICES = "bm_george (warm British man, default), am_michael, am_adam, af_heart, af_nova, bf_emma, bf_isabella";
+const NEW_SCENES = `// One function per shot. k is the drawing kit (references/kit.md).
+window.SCENES = {
+  opening: (k) => {
+    k.sky({ stops: ["#f3ecd2", "#e9dfb7"] });
+    k.ridge({ y: 0.52, amp: 0.02, freq: 4, color: "#4f7a3a", shape: "bush" });
+    k.ground({ y: 0.52, color: "#8fbf3a", far: "#c3cf5a", stripes: 14 });
+    k.person({ x: 0.5, y: 0.7, h: 0.22, pose: "walk", facing: "front" });
+  },
+};
+`;
+
+const unwrap = <T>(r: Result<T>): T => {
+  if (!r.ok) throw new Error(r.errors.join("\n  "));
+  return r.value;
+};
+
+const slug = (s: string): string =>
+  s.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "short";
+
+const twosName = (n: number): string => (n === 1 ? "ones" : n === 2 ? "twos" : `${n}s`);
+
+const lookFiles = (): readonly string[] => fs.readdirSync(LOOKS).filter((f) => f.endsWith(".json")).toSorted();
+
+const namedLook = (name: string): Result<JsonMap> => {
+  const f = path.join(LOOKS, `${name}.json`);
+  if (!fs.existsSync(f)) return fail(`no look "${name}" (SA looks lists them)`);
+  const v = readJson(f);
+  return isMap(v) ? ok(v) : fail(`looks/${name}.json is not an object`);
+};
+
+const shortFile = (dir: string): string => path.join(dir, "short.json");
+
+function rawShort(dir: string): Json {
+  const f = shortFile(dir);
+  if (!fs.existsSync(f)) throw new Error(`no short.json in ${dir} (start one with: SA new ${dir})`);
+  const v = readJson(f);
+  if (!isJson(v)) throw new Error("short.json is not JSON");
+  return v;
+}
+
+const load = (dir: string): Short => unwrap(parseShort(rawShort(dir)));
+
+type Project = { readonly dir: string; readonly s: Short; readonly takes: readonly Take[]; readonly tl: Timeline };
+
+async function project(dir: string, quiet = false): Promise<Project> {
+  const s = load(dir);
+  const takes = await narrate(dir, s, quiet);
+  return { dir, s, takes, tl: unwrap(timeline(s, takes)) };
+}
+
+async function withPage<T>({ dir, s, tl }: Project, use: (pg: Page) => Promise<T>): Promise<T> {
+  const state = pageState(s, tl, unwrap(resolveLook(s.look, namedLook)));
+  const pg = await paintPage(dir, state, tl.W, tl.H);
+  try {
+    const out = await use(pg);
+    const errs = pageErrors(pg);
+    if (errs.length) console.log("⚠ the page said:\n  " + errs.join("\n  "));
+    return out;
+  } finally {
+    pg.close();
+  }
+}
+
+const frameName = (i: number): string => `s${String(i).padStart(3, "0")}.jpg`;
+
+/* ------------------------------------------------------------------ commands */
+
+type Args = { readonly dir: string | undefined; readonly rest: readonly string[] };
+type Command = (a: Args) => Promise<number>;
+
+const need = (dir: string | undefined, usage: string): string => {
+  if (!dir) throw new Error(usage);
+  return dir;
+};
+
+const looks: Command = async () => {
+  lookFiles().forEach((f) => {
+    const l = readJson(path.join(LOOKS, f));
+    console.log(`${f.replace(".json", "").padEnd(12)} ${isMap(l) && typeof l.about === "string" ? l.about : ""}`);
+  });
+  console.log(`\nmusic moods: ${MOODS.join(", ")} (or "none", or a path to their own track)`);
+  console.log(`voices: ${VOICES}`);
+  return 0;
+};
+
+const create: Command = async ({ dir, rest }) => {
+  const d = need(dir, "SA new <dir>");
+  mkdir(d, "assets");
+  const opt = (k: string, dflt: string): string => {
+    const i = rest.indexOf(`--${k}`);
+    return (i >= 0 ? rest[i + 1] : undefined) ?? dflt;
+  };
+  if (!fs.existsSync(shortFile(d))) {
+    writeJson(shortFile(d), {
+      title: "Untitled short", brief: "", format: opt("format", "9:16"), look: opt("look", "oil"),
+      voice: { id: "bm_george", speed: 0.92 }, music: { mood: "tender" }, captions: { style: "box" },
+      lines: [{ say: "Every story starts somewhere.", scene: "opening", move: "push" }],
+    });
+  }
+  if (!fs.existsSync(path.join(d, "scenes.js"))) fs.writeFileSync(path.join(d, "scenes.js"), NEW_SCENES);
+  console.log(`✓ ${d}\n  short.json  the script, look, voice, music\n  scenes.js   the drawings\n  assets/     anything they gave you`);
+  return 0;
+};
+
+const set: Command = async ({ dir, rest }) => {
+  const d = need(dir, "SA set <dir> key=value...");
+  const next = rest.map((a) => unwrap(parseAssignment(a))).reduce<Json>((doc, a) => setPath(doc, a.path, a.value), rawShort(d));
+  // Placeholder takes are enough to catch what only the timeline knows (an unknown format).
+  const s = unwrap(parseShort(next));
+  unwrap(timeline(s, s.lines.map(() => ({ file: null, dur: 1 }))));
+  writeJson(shortFile(d), next);
+  console.log("✓ short.json updated");
+  return 0;
+};
+
+const lookKeys = (): readonly string[] =>
+  [...new Set(lookFiles().flatMap((f) => {
+    const l = readJson(path.join(LOOKS, f));
+    return isMap(l) ? Object.keys(l) : [];
+  }))];
+
+const checkCmd: Command = async ({ dir }) => {
+  const d = need(dir, "SA check <dir>");
+  const s = load(d);
+  const tl = unwrap(timeline(s, cachedTakes(d, s)));
+  const findings = check({ short: s, timeline: tl, probes: probeScenes(d, tl), kit: kitNames(), lookKeys: lookKeys() });
+  console.log(report(findings));
+  return findings.some((f) => f.level === "error") ? 1 : 0;
+};
+
+const voice: Command = async ({ dir }) => {
+  const { tl } = await project(need(dir, "SA voice <dir>"));
+  tl.beats.forEach((b, i) => console.log(`${String(i + 1).padStart(2)}  ${b.start.toFixed(2).padStart(6)}s  ${b.dur.toFixed(2)}s  ${b.scene.padEnd(16)} ${b.say}`));
+  console.log(`total ${tl.duration.toFixed(1)}s, ${tl.beats.length} shots`);
+  return 0;
+};
+
+const frames: Command = async ({ dir }) => {
+  const p = await project(need(dir, "SA frames <dir>"), true);
+  const fdir = mkdir(p.dir, "frames");
+  fs.readdirSync(fdir).filter((f) => /^s\d+\.jpg$/.test(f)).forEach((f) => fs.rmSync(path.join(fdir, f)));
+  await withPage(p, (pg) =>
+    p.tl.beats.reduce<Promise<void>>(async (prev, _b, i) => {
+      await prev;
+      fs.writeFileSync(path.join(fdir, frameName(i)), jpeg(await pg.evaluate(`window.still(${i}, 0.6)`)));
+    }, Promise.resolve()),
+  );
+  const sheet = path.join(fdir, "sheet.jpg");
+  stillSheet(p.tl, path.join(fdir, "s%03d.jpg"), sheet);
+  console.log(`✓ ${sheet}  (${p.tl.beats.length} shots, ${p.tl.duration.toFixed(1)}s)`);
+  return 0;
+};
+
+const still: Command = async ({ dir, rest }) => {
+  const p = await project(need(dir, "SA still <dir> <shot> [at]"), true);
+  const i = Math.max(0, parseInt(rest[0] ?? "1", 10) - 1);
+  const at = parseFloat(rest[1] ?? "0.6");
+  if (i >= p.tl.beats.length) throw new Error(`shot ${i + 1}? there are ${p.tl.beats.length}`);
+  const f = path.join(mkdir(p.dir, "frames"), `shot-${String(i + 1).padStart(2, "0")}.jpg`);
+  await withPage(p, async (pg) => fs.writeFileSync(f, jpeg(await pg.evaluate(`window.still(${i}, ${at})`))));
+  console.log(`✓ ${f}`);
+  return 0;
+};
+
+/** Next free vN: one past the highest, so deleting an old render never reuses its number. */
+const nextVersion = (rdir: string): number =>
+  1 + Math.max(0, ...fs.readdirSync(rdir).flatMap((f) => /^v(\d+)\.mp4$/.exec(f)?.[1] ?? []).map(Number));
+
+async function paintAll(pg: Page, write: (b: Buffer) => Promise<void>, drawings: number): Promise<void> {
+  const step = async (d: number): Promise<void> => {
+    if (d >= drawings) return;
+    await write(jpeg(await pg.evaluate(`window.drawing(${d})`)));
+    if (d % 60 === 0) process.stdout.write(`\r· painting ${d}/${drawings} drawings`);
+    return step(d + 1);
+  };
+  await step(0);
+  process.stdout.write(`\r· painted ${drawings} drawings          \n`);
+}
+
+const render: Command = async ({ dir }) => {
+  const t0 = Date.now();
+  const p = await project(need(dir, "SA render <dir>"));
+  const { tl, s } = p;
+  console.log(`· ${tl.beats.length} shots, ${tl.duration.toFixed(1)}s at ${tl.fps} fps, drawn on ${twosName(tl.twos)}`);
+  const audio = soundtrack(p.dir, s, tl, p.takes);
+  const rdir = mkdir(p.dir, "renders");
+  const n = nextVersion(rdir);
+  const outV = path.join(rdir, `v${n}.mp4`);
+  const enc = encoder(tl, audio, outV);
+  await withPage(p, (pg) => paintAll(pg, enc.write, Math.ceil((tl.duration * tl.fps) / tl.twos)));
+  const code = await enc.done();
+  if (code !== 0) throw new Error(`ffmpeg exited ${code} while encoding`);
+  const final = path.join(p.dir, `${slug(s.title)}.mp4`);
+  fs.copyFileSync(outV, final);
+  fs.copyFileSync(shortFile(p.dir), path.join(rdir, `v${n}.json`));
+  const sheet = path.join(mkdir(p.dir, "qa"), "sheet.jpg");
+  videoSheet(tl, final, sheet);
+  console.log(`✓ ${final}\n  ${tl.duration.toFixed(1)}s · ${tl.W}×${tl.H} · ${((Date.now() - t0) / 1000).toFixed(0)}s to make · check: ${sheet}`);
+  return 0;
+};
+
+const COMMANDS: Readonly<Record<string, Command>> = {
+  looks, new: create, set, check: checkCmd, voice, frames, still, render,
+  doctor: async () => doctor(import.meta.filename),
+};
+
+const usage = (): string =>
+  fs.readFileSync(import.meta.filename, "utf8").split("\n").slice(2, 16).join("\n").replace(/^ \* ?/gm, "");
+
+// stripTypeScriptTypes is stable in practice but flagged experimental; that one notice is noise to a user.
+process.removeAllListeners("warning");
+process.on("warning", (w) => {
+  if (!(w.name === "ExperimentalWarning" && /stripTypeScriptTypes/.test(w.message))) console.error(`${w.name}: ${w.message}`);
+});
+
+const [cmd = "", dirArg, ...rest] = process.argv.slice(2);
+const command = COMMANDS[cmd];
+if (!command) {
+  console.log(usage());
+  process.exit(cmd ? 1 : 0);
+}
+command({ dir: dirArg ? path.resolve(dirArg) : undefined, rest })
+  .then((code) => process.exit(code))
+  .catch((e: unknown) => {
+    console.error("✗ " + (e instanceof Error ? e.message : String(e)));
+    process.exit(1);
+  });

package/adapters/grok/olko-creative/skills/shorts-animator/scripts/test/domain.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { captionChunks, chunks, words } from "../domain/captions.ts";
+import { check, report, type Facts, type Probe } from "../domain/check.ts";
+import { resolveLook } from "../domain/look.ts";
+import { parseAssignment, setPath } from "../domain/patch.ts";
+import { parseShort } from "../domain/schema.ts";
+import { timeline } from "../domain/timeline.ts";
+import type { Json, Result, Short, Take, Timeline } from "../domain/types.ts";
+import { fail, ok } from "../domain/types.ts";
+
+const value = <T>(r: Result<T>): T => {
+  if (!r.ok) throw new Error(r.errors.join("; "));
+  return r.value;
+};
+
+const RAW = {
+  title: "test", voice: "none", music: "none",
+  lines: [
+    { say: "A bright and open morning, out on the hills.", scene: "day", move: "push" },
+    { say: "Night comes down over the city.", scene: "night" },
+  ],
+};
+const short = (patch: object = {}): Short => value(parseShort({ ...RAW, ...patch }));
+const silent = (s: Short): readonly Take[] => s.lines.map(() => ({ file: null, dur: 2 }));
+const tl = (s: Short): Timeline => value(timeline(s, silent(s)));
+
+test("words drops the writer's emphasis and pause marks", () => {
+  assert.deepEqual(words("a *bright* | morning"), ["a", "bright", "morning"]);
+});
+
+test("chunks are balanced, not greedy", () => {
+  assert.deepEqual(chunks("one two three four five six seven", 5).map((c) => c.split(" ").length), [4, 3]);
+  assert.deepEqual(chunks("short line", 5), ["short line"]);
+});
+
+test("a slash in the caption forces the break", () => {
+  assert.deepEqual(captionChunks({ say: "Everyone, every pose.", caption: "Everyone, / every pose.", shots: [] }, 5), ["Everyone,", "every pose."]);
+});
+
+test("parseShort fills defaults and rejects a script with no lines", () => {
+  const s = short();
+  assert.equal(s.format, "9:16");
+  assert.equal(s.fps, 24);
+  assert.equal(s.voice.kind, "none");
+  assert.equal(parseShort({ title: "x" }).ok, false);
+  assert.equal(parseShort([]).ok, false);
+});
+
+test("timeline lays beats end to end and rejects an unknown format", () => {
+  const t = tl(short());
+  assert.equal(t.beats.length, 2);
+  assert.equal(t.W, 1080);
+  const [a, b] = t.beats;
+  assert.ok(a && b && Math.abs(a.start + a.dur - b.start) < 1e-9);
+  assert.ok(t.duration >= b.start + b.dur);
+  const bad = timeline(short({ format: "3:2" }), silent(short()));
+  assert.equal(bad.ok, false);
+});
+
+test("parseAssignment reads JSON values and falls back to text", () => {
+  assert.deepEqual(value(parseAssignment("lines.0.hold=0.8")), { path: ["lines", "0", "hold"], value: 0.8 });
+  assert.deepEqual(value(parseAssignment("look=watercolor")), { path: ["look"], value: "watercolor" });
+  assert.equal(parseAssignment("nokey").ok, false);
+  assert.equal(parseAssignment("a..b=1").ok, false);
+});
+
+test("setPath returns a new document and leaves the old one alone", () => {
+  const doc: Json = { lines: [{ say: "hi" }], music: { mood: "tender" } };
+  const before = JSON.stringify(doc);
+  const next = setPath(setPath(doc, ["lines", "0", "hold"], 1), ["music", "mood"], "night");
+  assert.equal(JSON.stringify(doc), before);
+  assert.deepEqual(next, { lines: [{ say: "hi", hold: 1 }], music: { mood: "night" } });
+});
+
+test("resolveLook merges a named base under the overrides", () => {
+  const named = (n: string): Result<{ readonly [k: string]: Json }> => (n === "oil" ? ok({ grain: 0.3, edge: 1 }) : fail(`no look "${n}"`));
+  const look = value(resolveLook({ base: "oil", grain: 0.5 }, named));
+  assert.equal(look.grain, 0.5);
+  assert.equal(look.edge, 1);
+  assert.equal(resolveLook("nope", named).ok, false);
+});
+
+const facts = (probes: readonly Probe[], s = short()): Facts => ({ short: s, timeline: tl(s), probes, kit: ["sky", "person"], lookKeys: ["grain"] });
+
+test("check flags missing scenes, unknown kit calls and throwing scenes as errors", () => {
+  const found = check(facts([{ scene: "day", calls: [{ fn: "skyy", opts: {} }] }, { scene: "other", calls: [], error: "boom" }]));
+  const errors = found.filter((f) => f.level === "error").map((f) => f.msg);
+  assert.ok(errors.some((m) => m.includes('no scene "night"')));
+  assert.ok(errors.some((m) => m.includes("k.skyy is not in the kit")));
+  assert.ok(errors.some((m) => m.includes("throws: boom")));
+});
+
+test("check warns when a person stands in the caption band, unless captions are off", () => {
+  const probes: readonly Probe[] = [
+    { scene: "day", calls: [{ fn: "person", opts: { y: 0.82, h: 0.28 } }] },
+    { scene: "night", calls: [{ fn: "person", opts: { y: 0.5, h: 0.2 } }] },
+  ];
+  const band = (s: Short) => check(facts(probes, s)).filter((f) => f.msg.includes("caption line"));
+  assert.deepEqual(band(short()).map((f) => f.where), ['scene "day"']);
+  assert.deepEqual(band(short({ captions: { style: "none" } })), []);
+});
+
+test("report is one line per finding, or clean", () => {
+  assert.equal(report([]), "check: clean");
+  assert.equal(report([{ level: "error", where: "x", msg: "y" }]), "ERROR x: y");
+});

package/adapters/grok/olko-creative/skills/shorts-animator/scripts/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts", "domain", "edge", "audio", "test"]
+}

package/adapters/grok/olko-creative/skills/shorts-animator/scripts/tts.py

@@ -0,0 +1,20 @@
+"""The narrator: Kokoro-82M on this computer, every line of a short in one go.
+
+  python tts.py <model.onnx> <voices.bin> <voice> <speed> < jobs.json
+
+jobs.json is [[text, out.wav], ...]. Loads the model once, writes one WAV per line,
+prints one line per file. Apache-2.0 model, no account, nothing leaves the machine.
+"""
+import json
+import sys
+
+import soundfile as sf
+from kokoro_onnx import Kokoro
+
+model, voices, voice, speed = sys.argv[1], sys.argv[2], sys.argv[3], float(sys.argv[4])
+lang = {"a": "en-us", "b": "en-gb", "e": "es", "f": "fr-fr", "h": "hi", "i": "it", "j": "ja", "p": "pt-br", "z": "cmn"}.get(voice[0], "en-us")
+k = Kokoro(model, voices)
+for text, out in json.load(sys.stdin):
+    samples, rate = k.create(text, voice=voice, speed=speed, lang=lang)
+    sf.write(out, samples, rate)
+    print(out, flush=True)

package/adapters/hermes/olko-creative/README.md

@@ -10,3 +10,5 @@ into the active Hermes profile. The canonical packages are:
 - `plugins/olko-creative/skills/music-to-plex/SKILL.md`
 - `plugins/olko-creative/skills/vinted-listing/SKILL.md`
 - `plugins/olko-creative/skills/wikipedia-uk-editor/SKILL.md`
+- `plugins/olko-creative/skills/shorts-animator/SKILL.md`
+- `plugins/olko-creative/skills/carousel-maker/SKILL.md`

package/catalog/skills.json

@@ -1300,6 +1300,52 @@
             "hermes",
             "pi"
           ]
+        },
+        {
+          "name": "shorts-animator",
+          "lookupName": "olko:shorts-animator",
+          "path": "plugins/olko-creative/skills/shorts-animator",
+          "description": "Make narrated, painted animated shorts (TikTok, Reels, YouTube Shorts) from a script and a look described in words: scenes drawn in code, GPU-painted, voiced locally, captioned and scored into an MP4.",
+          "tags": [
+            "video",
+            "animation",
+            "shorts",
+            "narration",
+            "canvas"
+          ],
+          "adapters": [
+            "codex",
+            "claude",
+            "cursor",
+            "copilot",
+            "windsurf",
+            "kiro",
+            "grok",
+            "hermes"
+          ]
+        },
+        {
+          "name": "carousel-maker",
+          "lookupName": "olko:carousel-maker",
+          "path": "plugins/olko-creative/skills/carousel-maker",
+          "description": "Make Instagram or LinkedIn carousel slides from a topic or pasted copy: a brand template sets the text, and a reusable library of hand-drawn illustrations, drawn once in code per brand, supplies the pictures.",
+          "tags": [
+            "instagram",
+            "carousel",
+            "social",
+            "design",
+            "slides"
+          ],
+          "adapters": [
+            "codex",
+            "claude",
+            "cursor",
+            "copilot",
+            "windsurf",
+            "kiro",
+            "grok",
+            "hermes"
+          ]
         }
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/plugins/olko-apple-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-apple-kit",
   "description": "Build and ship Apple platform apps: macOS menubar apps, App Store submissions.",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-creative/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-creative",
   "description": "Creative and personal projects: photo galleries, music players, listings, wiki editing.",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-creative/skills/carousel-maker/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: carousel-maker
+description: Use when someone wants Instagram or LinkedIn carousel slides from a topic, a brief or pasted copy. A fixed brand template sets the text on every slide, and an optional library of hand-drawn illustrations, drawn once in code per brand and reused across decks, supplies the pictures. No image models or stock.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Hermes Agent, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Needs Node 22.18+ and Chrome; ffmpeg for the contact sheet. The illustration library needs the shorts-animator skill installed alongside.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - instagram
+    - carousel
+    - social
+    - design
+    - slides
+---
+
+# Carousel Maker
+
+A brand and a few lines of copy in, 1080x1350 carousel slides out. The template places the text, so it
+is never garbled and never off-brand. Pictures come from the brand's library: drawings written once as
+canvas code, painted by shorts-animator, and reused by every deck after that. Text-only decks need no
+library at all.
+
+`CM` = `node <this skill's folder>/scripts/cm.ts`. Write the full command each time. One folder per
+brand: `BRAND=./<slug>-carousels`. Decks live in `$BRAND/decks/<deck>.json`.
+
+## 1. Decide the copy
+
+Decide the slides yourself. Ask one question only if the subject or the brand is unclear. A pasted
+script is used word for word.
+
+- 5 to 8 slides: a `cover`, then `point` slides, then one `cta`.
+- The cover is a promise in 8 words or fewer. It is the only slide most people see.
+- One idea per point slide: a title of 7 words or fewer, a body of 22 words or fewer.
+- The cta asks for one thing (save, follow, comment) and carries a `follow` line.
+- `caption` is the post text: two short lines and one question for the comments.
+
+## 2. Set up the brand
+
+```bash
+CM new "$BRAND" --name "Slow Hours" --handle @slowhours --look ink   # brand.json, decks/, art/, library/
+```
+
+`brand.json`: `name`, `handle`, `colors` (`paper`, `ink`, `accent`, `muted`, all `#rrggbb`), `fonts`
+(`head`, `body`, CSS font stacks). Set them from what they told you; the defaults are cream, near-black
+and orange. `--look` picks the paint for the library: `ink`, `gouache`, `watercolor`, `pastel`, `oil`.
+
+A deck:
+
+```json
+{ "title": "mornings", "caption": "...", "slides": [
+  { "kind": "cover", "title": "Slow mornings, in 4 steps", "body": "No 5am club.", "art": "window" },
+  { "kind": "point", "title": "Coffee, outside", "body": "Five minutes on the step.", "art": "coffee" },
+  { "kind": "point", "title": "Their own photo", "art": "photos/desk.jpg" },
+  { "kind": "cta", "title": "Save this for tomorrow", "follow": "Follow @slowhours" } ] }
+```
+
+`art` is a library drawing (a bare name), a file (a path, relative to `$BRAND`), or left out for a
+text-only slide, which gets larger type.
+
+## 3. Draw the library (once per brand)
+
+Skip this for text-only decks. Every bare `art` name needs a function in `$BRAND/art/scenes.js`:
+`window.SCENES = { "window": (k) => { k.sky({...}); ... } }`. Read `../shorts-animator/references/kit.md`
+before writing scenes. Draw objects and places, square, one subject, big simple shapes, strong value
+contrast; the paint pass adds texture. No people's faces close up.
+
+```bash
+CM art "$BRAND"            # every drawing the decks use -> library/<name>.jpg
+CM art "$BRAND" coffee     # only these
+```
+
+Look at the sheet it reports once. Redraw only the drawings that are muddy, empty or look alike. The
+library is the brand's asset: the next deck reuses it and only new names cost a drawing.
+
+## 4. Check, render, look (budgeted)
+
+```bash
+CM check "$BRAND" [deck]   # no browser: unknown kinds, missing drawings or files, deck shape, word counts
+CM render "$BRAND" [deck]  # out/<deck>/slide-N.png, sheet.jpg, caption.txt; measures every slide
+```
+
+Fix every `ERROR` from `check` before rendering. `render` also fails a slide whose text spills out of
+its frame or whose picture did not load. Then read `out/<deck>/sheet.jpg` once. **Budget: at most two
+looks per deck** (the library sheet and the deck sheet). Images are the expensive part of this loop; do
+not reopen a sheet you have already judged.
+
+Tell them in two lines what it is (slides, look) and: "Tell me what to change, one sentence is enough."
+
+## 5. One-sentence changes
+
+Smallest change, `CM check`, render, show.
+
+| they say | change |
+|---|---|
+| shorter, punchier | the slide's `title` or `body` |
+| different colours, our brand | `brand.json` `colors` |
+| serif, sans, our font | `brand.json` `fonts` |
+| a different picture on slide 3 | that slide's `art`, or one new scene plus `CM art "$BRAND" <name>` |
+| no pictures | drop `art` from the slides |
+| another post on the same brand | a new `decks/<deck>.json`; reuse library names |
+
+## When something goes wrong
+
+| symptom | fix |
+|---|---|
+| no Chrome | install Chrome, or set `CHROME` to a Chrome or headless-shell binary |
+| `CM art` cannot find shorts-animator | install it alongside, or set `SHORTS_ANIMATOR` to its `scripts/sa.ts` |
+| "text spills out of the frame" | cut words; `check` warns before this happens |
+| no sheet.jpg | ffmpeg is missing; the slides are still in `out/<deck>/` |