feat: add flows-diagram skill

.claude-plugin/marketplace.json

@@ -5,15 +5,15 @@
     "url": "https://amigoscode.com"
   },
   "metadata": {
-    "description": "Amigoscode marketplace — content and developer tools for educators and engineers.",
+    "description": "Amigoscode marketplace \u2014 content and developer tools for educators and engineers.",
     "version": "1.0.0",
     "repository": "https://github.com/amigoscode/skills"
   },
   "plugins": [
     {
       "name": "amigoscode",
       "source": "./",
-      "description": "Branded explainer videos, educational infographics (HOW X WORKS diagrams), LinkedIn carousels, X-style quote cards, and an autonomous LinkedIn poster."
+      "description": "Branded explainer videos, animated backend flow diagrams, educational infographics (HOW X WORKS diagrams), LinkedIn carousels, X-style quote cards, and an autonomous LinkedIn poster."
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "amigoscode",
   "version": "1.0.0",
-  "description": "Amigoscode content tools — branded explainer videos, educational infographics, LinkedIn carousels, X-style quote cards, and an autonomous LinkedIn poster.",
+  "description": "Amigoscode content tools \u2014 branded explainer videos, animated backend flow diagrams, educational infographics, LinkedIn carousels, X-style quote cards, and an autonomous LinkedIn poster.",
   "author": {
     "name": "Amigoscode",
     "url": "https://amigoscode.com"
@@ -23,6 +23,10 @@
     "hyperframes",
     "headshots",
     "profile-picture",
-    "portrait"
+    "portrait",
+    "flows-diagram",
+    "diagram",
+    "animation",
+    "backend"
   ]
 }

README.md

@@ -19,6 +19,7 @@ Skills are markdown files that give AI agents specialized knowledge and workflow
 |-------|-------------|
 | [carousel](skills/carousel/) | Generate branded LinkedIn carousel slides (1080x1350px PNGs), a combined PDF, beat-synced MP4s, a GIF, and platform... |
 | [explainer-video](skills/explainer-video/) | Produce a branded Amigoscode vertical explainer VIDEO (1080x1920 MP4) that teaches one backend, Java, data-structures,... |
+| [flows-diagram](skills/flows-diagram/) | Produce a branded Amigoscode animated BACKEND-DIAGRAM video: a React/SVG flow diagram (controllers, queues, threads,... |
 | [headshots](skills/headshots/) | Generate polished LinkedIn-style profile-picture variations from a single reference photo, while keeping the person's... |
 | [infographic](skills/infographic/) | Generate 'HOW X WORKS' educational infographic diagrams for Amigoscode — hand-drawn style diagrams about backend/Java... |
 | [linkedin-poster](skills/linkedin-poster/) | Fully autonomous LinkedIn poster. Drives the LinkedIn web composer via Playwright/TypeScript to publish posts... |
@@ -37,7 +38,7 @@ Use [npx skills](https://github.com/vercel-labs/skills) to install skills direct
 npx skills add amigoscode/skills
 
 # Install specific skills
-npx skills add amigoscode/skills --skill infographic carousel explainer-video x-card linkedin-poster
+npx skills add amigoscode/skills --skill infographic carousel explainer-video flows-diagram x-card linkedin-poster
 
 # List available skills
 npx skills add amigoscode/skills --list
@@ -91,6 +92,7 @@ Each skill has its own dependencies and one-time setup. See the skill READMEs:
 - [`skills/infographic/README.md`](./skills/infographic/README.md) — needs a `GEMINI_API_KEY` and `npm install` for the diagram generator and Playwright screenshot step.
 - [`skills/carousel/README.md`](./skills/carousel/README.md) — needs `npm install` + `npx playwright install chromium`; Python 3 with `librosa` and `ffmpeg` for the beat-synced videos.
 - [`skills/explainer-video/README.md`](./skills/explainer-video/README.md) — needs an `ELEVEN_LABS` API key (Creator tier for cloned voices), `ffmpeg`/`ffprobe`, and `npx hyperframes` (Whisper transcription + render).
+- [`skills/flows-diagram/README.md`](./skills/flows-diagram/README.md) — needs Google Chrome, `ffmpeg`/`ffprobe`, `npm install` (puppeteer-core), and an `ELEVEN_LABS` API key for the voiceover.
 - [`skills/x-card/README.md`](./skills/x-card/README.md) — needs Python 3 with Pillow (`pip install pillow`). Fonts and badge are bundled.
 - [`skills/linkedin-poster/README.md`](./skills/linkedin-poster/README.md) — needs `npm install` + `npx playwright install chromium`, then a one-time LinkedIn login that is saved for future runs.
 
@@ -110,6 +112,9 @@ Once installed, just ask your agent to help with content tasks:
 "Create a LinkedIn carousel about the top 10 Git commands"
 → Uses carousel skill
 
+"Make a flows diagram for the outbox pattern"
+→ Uses flows-diagram skill
+
 "Make an X card: Juniors write code. Seniors delete it."
 → Uses x-card skill
 
@@ -125,6 +130,7 @@ You can also invoke skills directly:
 ```
 /infographic
 /carousel
+/flows-diagram
 /x-card
 /linkedin-poster
 ```

VERSIONS.md

@@ -11,9 +11,13 @@ Current versions of all skills. Agents can compare against local versions to che
 | linkedin-poster | 1.0.0 | 2026-06-23 | Fully autonomous LinkedIn poster that publishes immediately or schedules text, carousel, or image posts via Playwright. |
 | nanobanana | 1.0.0 | 2026-06-27 | Generate and edit images with Google's Gemini 3.1 Flash Image model: text-to-image, single-image edits, style transfer, and multi-image compositing. |
 | headshots | 1.1.0 | 2026-06-28 | Generate polished LinkedIn-style profile-picture variations from one reference photo, preserving the person's identity. 11 options including a restore-only mode, picked via checkbox; fans out one subagent per style. Self-contained Gemini generator. |
+| flows-diagram | 1.0.0 | 2026-07-31 | Animated backend flow diagrams (React/SVG scenes) rendered to a 1440x1440 square MP4, a 960x960 looping GIF, and a 1080x1920 branded reel, plus ElevenLabs voiceover, word-by-word captions, caption.txt, and title.txt. |
 
 ## Recent Changes
 
+### 2026-07-31
+- Added `flows-diagram` skill: animated backend/Java/Spring/database diagrams (square MP4 + looping GIF + branded reel) with voiceover and word-by-word captions
+
 ### 2026-06-28
 - `headshots`: added a `restore` option (enhance/repair the original photo with no restyle), selectable in the checkbox prompt alongside the styled looks
 

skills/flows-diagram/.env.example

@@ -0,0 +1,9 @@
+# ElevenLabs API key (voiceover + forced alignment).
+# Also read from ~/.env if you keep your keys there.
+ELEVEN_LABS=
+
+# Optional: override the Chrome binary used for rendering.
+# CHROME_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+
+# Optional: override where diagrams are authored and rendered.
+# FLOWS_DIR=~/amigoscode-skills/flows

skills/flows-diagram/.gitignore

@@ -0,0 +1,15 @@
+# Secrets
+.env
+
+# Vendored React + Babel, fetched on first render
+.cache/
+
+# Scratch frames / harness
+.work/
+
+# Dependencies
+node_modules
+
+# OS / editor cruft
+.DS_Store
+*.log

skills/flows-diagram/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amigoscode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/flows-diagram/README.md

@@ -0,0 +1,108 @@
+# flows-diagram
+
+Turn one backend concept into a **branded animated diagram**: a React/SVG scene animated across
+10 seconds and rendered three ways from a single command, then voiced, captioned, and titled.
+
+Built on headless Chrome (puppeteer-core) + ffmpeg. Deterministic: the timeline is stepped to
+exact timestamps, so renders are repeatable.
+
+## What you get per diagram
+
+```
+$FLOWS/<name>-flow/
+├── <base>.mp4                    ← 1440x1440 square, branded frame
+├── <base>.gif                    ← 960x960 infinite loop
+├── <base>-reel.mp4               ← 1080x1920 vertical reel
+├── <base>-reel-voice-over.mp4    ← the reel with voiceover + word-by-word captions
+├── <base>-vo.mp3                 ← ElevenLabs narration
+├── <name>-scene.jsx              ← the diagram (the only creative file)
+├── animations.jsx                ← shared timeline engine (copied per project)
+├── vo-script.txt                 ← ~44 word narration script
+├── caption.txt                   ← long-form social post copy
+└── title.txt                     ← short upload title
+```
+
+## Prerequisites
+
+- **Google Chrome** or Chromium (set `CHROME_PATH` if it is not in a standard location).
+- **ffmpeg** and **ffprobe** on `PATH`.
+- **Node.js 18+**, then `npm install` in this folder (pulls `puppeteer-core`).
+- **`ELEVEN_LABS` API key** for the voiceover and forced alignment ([elevenlabs.io](https://elevenlabs.io)).
+  Read from the environment, this folder's `.env`, or `~/.env`.
+
+```bash
+cp .env.example .env   # then add your key, or: export ELEVEN_LABS=...
+npm install
+```
+
+React and Babel are fetched into `.cache/` automatically on the first render.
+
+## Usage
+
+In Claude Code:
+
+> "make a flows diagram for the outbox pattern"
+> "add a diagram about backpressure"
+> "give the retry diagram a voiceover and captions"
+
+Or drive the pipeline directly:
+
+```bash
+SKILL=~/.claude/skills/flows-diagram
+FLOWS=~/amigoscode-skills/flows
+
+cd "$FLOWS" && mkdir -p outbox-flow
+cp "$SKILL/assets/template/animations.jsx"    outbox-flow/animations.jsx
+cp "$SKILL/assets/template/example-scene.jsx" outbox-flow/outbox-scene.jsx   # then edit
+
+# fast one-frame layout check
+MODE=check node "$SKILL/scripts/make.mjs" outbox-flow outbox-scene.jsx outbox \
+  "How the Outbox Pattern Works" "DISTRIBUTED TX" "x"
+
+# full render: square mp4 + looping gif + branded reel
+CROP_TOP=150 CROP_BOTTOM=140 node "$SKILL/scripts/make.mjs" outbox-flow outbox-scene.jsx outbox \
+  "How the Outbox Pattern Works" "DISTRIBUTED TX" "Write → Outbox → Relay → Broker"
+```
+
+## Workspace
+
+Diagrams are authored and rendered **outside** the skill so updating the skill never touches your
+work. The workspace resolves in this order:
+
+1. `FLOWS_DIR` environment variable
+2. `workspaceDir` in `~/amigoscode-skills/flows-diagram-config.json`
+3. `~/flows` if it exists (the original project location)
+4. `~/amigoscode-skills/flows` (created on demand)
+
+Copy `config.default.json` to `~/amigoscode-skills/flows-diagram-config.json` to change the
+workspace, the ElevenLabs voice, or the voice settings.
+
+## Layout
+
+```
+flows-diagram/
+├── SKILL.md                  # agent instructions
+├── scripts/
+│   ├── make.mjs              # scene -> square mp4 + gif + reel
+│   ├── gen-vo.mjs            # ElevenLabs TTS
+│   ├── vo-align.mjs          # forced alignment -> word timings
+│   ├── caption-render.mjs    # Submagic-style caption overlay frames
+│   └── paths.mjs             # workspace / Chrome / key / cache resolution
+├── assets/
+│   ├── logo-mark.svg         # purple mark (top of every frame)
+│   ├── amigoscode-logo*.png  # wordmarks
+│   └── template/             # animations.jsx + example scene to copy
+└── references/
+    ├── pipeline.md           # make.mjs contract, env vars, tuned render matrix
+    ├── scene-contract.md     # how to author a scene
+    └── voiceover-captions.md # voiceover, captions, caption.txt, title.txt
+```
+
+## Brand rules
+
+Purple `#7f56d9` primary, teal `#2FA39B` secondary, red `#E5484D` failure, ink `#20273e` text.
+10 seconds, 30fps. No en dashes or em dashes anywhere in titles, captions, or narration.
+
+## License
+
+MIT

skills/flows-diagram/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: flows-diagram
+description: "Produce a branded Amigoscode animated BACKEND-DIAGRAM video: a React/SVG flow diagram (controllers, queues, threads, caches, DB cylinders, arrows, packets) animated over 10s and rendered to a 1440x1440 square MP4, a 960x960 looping GIF, and a 1080x1920 branded reel, then optionally given an ElevenLabs voiceover, word-by-word captions with animated emojis, an infographic-style caption.txt, and an upload title.txt. Use whenever the user wants an animated backend, Java, Spring, database, or concurrency DIAGRAM, flow, or 'how X works' reel, or to add a voiceover, captions, or a title to one of these diagrams. Examples: 'make a flows diagram for the outbox pattern', 'add a diagram about backpressure', 'render the square + reel for saga', 'give the retry diagram a voiceover and captions', 'generate title.txt for these'. This is the SVG-scene pipeline (make.mjs + puppeteer + ffmpeg). It is NOT the HyperFrames explainer-video skill and NOT the CSV reel skill."
+license: MIT
+---
+
+# Flows diagram
+
+Turn one backend concept into a set of branded animated diagrams. Every diagram is a self
+contained React/SVG scene animated across 10 seconds and rendered three ways from one command,
+then voiced, captioned, and titled. The voiced, captioned reel is part of the standard
+deliverable, not an afterthought.
+
+Zero en dashes or em dashes anywhere (titles, captions, voiceover). Periods and commas only.
+
+## Where things live
+
+- **`$SKILL`** — this skill folder. It carries `scripts/` (the pipeline), `assets/` (brand logos
+  and the scene template), and `references/`. Never write output here.
+- **`$FLOWS`** — the workspace where diagrams are authored and rendered. One folder per diagram
+  (`<name>-flow/`). Resolution order: `FLOWS_DIR` env var, then `workspaceDir` in
+  `~/amigoscode-skills/flows-diagram-config.json`, then `~/flows` if it exists, then
+  `~/amigoscode-skills/flows` (created on demand).
+
+Set both once per session, then every command below is copy-paste:
+
+```bash
+SKILL=~/.claude/skills/flows-diagram          # or the installed plugin path
+FLOWS=$(node -e "import('$SKILL/scripts/paths.mjs').then(m=>console.log(m.workspaceDir({create:true})))")
+```
+
+First render fetches React and Babel into `$SKILL/.cache` automatically. `puppeteer-core` must be
+installed once (`cd $SKILL && npm install`); rendering needs system Chrome (`CHROME_PATH` to
+override) plus `ffmpeg` and `ffprobe`.
+
+## The pipeline at a glance
+
+1. **Scene** — author `$FLOWS/<name>-flow/<name>-scene.jsx` (+ copy `animations.jsx`) from
+   `$SKILL/assets/template/`. This is the only creative step. See `references/scene-contract.md`.
+2. **Render** — `node $SKILL/scripts/make.mjs <folder> <sceneFile> <outBase> "<Title>" "<EYEBROW>" "<caption>"`
+   emits the square MP4, the GIF, and the reel. Tune `CROP_TOP`/`CROP_BOTTOM` per diagram so the
+   diagram is centered between the title and the footer (see below). See `references/pipeline.md`.
+3. **Words** — write `caption.txt` (the /infographic post copy) and `title.txt` (the upload
+   name). See `references/voiceover-captions.md`.
+4. **Voiceover + captions** — write `vo-script.txt` (~44 words), then run the voiceover +
+   Submagic caption pipeline to produce `<base>-reel-voice-over.mp4`. Do this for every diagram
+   by default (the reel ships voiced and captioned); only skip it if the user explicitly says
+   they just want the silent base videos. See `references/voiceover-captions.md`.
+
+## Fast path for a brand new diagram
+
+```bash
+cd "$FLOWS"
+mkdir foo-flow
+cp "$SKILL/assets/template/animations.jsx"   foo-flow/animations.jsx
+cp "$SKILL/assets/template/example-scene.jsx" foo-flow/foo-scene.jsx   # then edit the diagram
+# iterate on layout with the fast one-frame check (writes $FLOWS/.work/foo/foo-check.png):
+MODE=check node "$SKILL/scripts/make.mjs" foo-flow foo-scene.jsx foo "How Foo Works" "SUBSYSTEM" "x"
+# when the frame looks right, full render (square mp4 + gif + reel):
+CROP_TOP=150 CROP_BOTTOM=140 node "$SKILL/scripts/make.mjs" foo-flow foo-scene.jsx foo \
+  "How Foo Works" "SUBSYSTEM" "Left → Middle → Right"
+```
+
+`MODE=check` renders a single mid-timeline frame in ~5s so you can dial in the diagram and the
+`CROP_TOP`/`CROP_BOTTOM` padding before committing to a full 30fps render. Always iterate on the
+check frame first.
+
+## Conventions (non negotiable)
+
+- **Palette**: purple `#7f56d9` primary, teal `#2FA39B` secondary/success, red `#E5484D`
+  failure. Ink text `#20273e`. The scene template's `C` object already holds these.
+- **Layout is locked** in `make.mjs`: purple mark at top, eyebrow + title pinned near the top,
+  the diagram in the middle, ink wordmark pinned at the bottom. Do not restyle the frame; only
+  the diagram inside `#stage` changes.
+- **Center the diagram between the title and the footer.** This is the look we want: roughly
+  equal breathing room above the diagram (below the title) and below it (above the wordmark), not
+  jammed against the title with a big empty gap below. `CROP_TOP`/`CROP_BOTTOM` are how you land
+  it: a tall diagram fills the body naturally, but a short or single-row diagram needs a *smaller*
+  `CROP_TOP` so it drops into the vertical middle. Always confirm the balance on the `MODE=check`
+  frame before the full render. Example: a thin single row centers at `CROP_TOP=95
+  CROP_BOTTOM=130`, whereas a tall diagram like a connection pool uses `180/165`.
+- **10 seconds, 30fps, k=1** (no breathing zoom). Scenes animate on `useTime()` (0..10).
+- **Voiceover ~44 words** so the brand voice lands near 18 to 21 seconds. Longer scripts drift
+  past 22s.
+- **Caption placement for reels is fixed**: `caption-render.mjs ... 1080 1920 30 <dur> 1545 60 1420`.
+- **Clean up after every render**: `make.mjs` wipes `$FLOWS/.work/<outBase>` automatically (set
+  `KEEP_WORK=1` to keep frames for debugging). The voiceover driver deletes its caption frames.
+  Never leave `.work` or `caps-*` scratch behind; it grows to many GB fast.
+
+## Scaling to many diagrams (use agents)
+
+Writing scenes, `caption.txt`, `vo-script.txt`, and `title.txt` is per diagram authoring work
+that parallelizes well: dispatch one general-purpose agent per small batch (3 to 4 diagrams) to
+write the text files, giving each agent the exact style spec. Do the RENDERING sequentially in a
+single resumable driver (a `done_file` the loop skips) because puppeteer/Chrome and ffmpeg
+contend when run in parallel. See `references/pipeline.md` for the batch-render pattern and
+`references/voiceover-captions.md` for the batch-voiceover driver.
+
+## References
+
+- `references/pipeline.md` — the `make.mjs` CLI contract, every env var, the tuned 26-diagram
+  render matrix (folder / outBase / CROP values / title / eyebrow), and the resumable
+  batch-render driver.
+- `references/scene-contract.md` — how to author a `<name>-scene.jsx`: the helpers, `KCard`/
+  `KIcon`/`ICONS`, the DB cylinder, `Defs`, the `SceneRouter`/`window.*` exports, and how motion
+  is driven by time.
+- `references/voiceover-captions.md` — `gen-vo.mjs`, `vo-align.mjs`, `caption-render.mjs`, the
+  emoji map, the exact ffmpeg composite command, and the `caption.txt` / `title.txt` styles.