Pixel Face Agent Skill

pixel-face — author & refine the Frontier Faces pixel art

A persona face is pure data in examples/04-frontier-faces/personas.mjs (one entry per

persona). The same data drives the terminal renderer (face-term.mjs), the browser element

(web/cotal-face.js), and the PNG tool — so edit personas.mjs once and it's live everywhere.

Always work from examples/04-frontier-faces/.

Where things are

• personas.mjs — the entries (rows, colors, glow, mouths, expr, eyes, lines). Single source of truth.
• FACE-DESIGN.md — the full conventions (grid zones, color keys, eye recipe, visemes). Read it first.
• tools/img2rows.mjs — rough a reference photo into a 32×32 rows+palette.
• tools/render-png.mjs — render a 7-state contact sheet (PNG) for review. This is the validator.
• tools/face-template.mjs — copy-me starter entry that encodes the conventions.
• gallery.html (all personas, original-vs-pixel) and preview.html?p=<key> (one persona) — served

via python3 -m http.server or tools/serve-wall.mjs; for visual QA.

• assets/<persona-key>.<ext> — reference photos. Gitignored / local-only — never commit them.

Persona key ≠ agent name. The roster uses agent-file basenames; the face comes from each agent's

face: frontmatter: elon→musk, steve→jobs, rayan→ray (others match). Persona keys:

neon david ray sven garry jobs musk dario mira bernie michelle.

Conventions (condensed — full detail in FACE-DESIGN.md)

• Grid 32×32, . = transparent, face centered ~col 15. Zones: hair 1–9 · brows 10–11

(drawn by expr, not rows) · eyes 12–13 (drawn by eyes()) · nose 14–16 · mouth

18–20 (drawn by mouths) · chin 21–24 · collar 26–31.

• Color keys: skin P light / S mid / s shadow · E pupil · W/w catchlight · R lip ·

m lip-shadow · b brow · h hair · L cyan + M magenta = the cotal glow ribbon

(glow: { L: 8, M: 6 } blurs them). Use rng(row, c1, c2, key) (exported from personas.mjs) for runs.

• Eye recipe: 2-wide iris (E) on the iris row; row below = catchlight (W/w, OUTER corner)

+ lid-shadow (s, INNER). jobs is the "alive" benchmark — match its eye, don't use flat black blocks.

• Surprise = raised brows + open mouth, eyes stay open (growing the iris behind glasses looks

wrong). Don't reintroduce a wide eye style.

• The face renders at a fixed 32×16 (not scaled to the pane), so faces look the same size as long

as the pane is ≥ ~32 cols.

Tools (exact)

# rough a reference photo → 32×32 rows + palette (macOS: uses sips)
node tools/img2rows.mjs --in assets/<key>.png --w 24 --h 30 [--colors 12] [--x0 4] [--y0 0]

# render a 7-state contact sheet (neutral·happy·sad·angry·surprised·talking·blink) to review
node tools/render-png.mjs --file <draft>.mjs --out /tmp/<key>.png --scale 8     # draft: export const entry = {…}
node tools/render-png.mjs --file personas.mjs --persona <key> --out /tmp/<key>.png --scale 8   # existing

A draft module must export const entry = {…} and (if it uses rng in expr/mouths)

import { rng } from '/abs/path/examples/04-frontier-faces/personas.mjs'.

After every render, Read the PNG and compare it to assets/<key>.<ext>. Iterate.

Create a new persona

• Pick a key. If you have a photo, save it as assets/<key>.png and img2rows it for a rough base;

otherwise copy tools/face-template.mjs.

• Hand-edit a /tmp/<key>-draft.mjs (export const entry) following the conventions above.
• render-png → Read the PNG → compare to the reference → iterate until all 7 states read well.
• Splice the finished entry into personas.mjs (keep the file's style; reuse color keys).
• Review in the gallery; confirm no other persona changed.

Improve an existing persona

• Read its entry in personas.mjs + its reference assets/<key>.<ext> and the current render.
• Edit only the in-scope rows (e.g. hair = rows 1–9). Preserve eyes(), glasses/beard,

expr, mouths, colors of other features, and the collar/glow — change the minimum.

• render-png the draft → Read → compare → iterate (≥3 passes). Then splice the rows back into

personas.mjs and confirm the diff is limited to that entry.

Multi-agent variant loop (use for likeness — "doesn't look like them")

When matching a real person, generate options instead of guessing:

• Spawn ~3 subagents on the main working tree (NOT git worktrees — assets/ is gitignored, so

reference photos are absent from a fresh worktree). Give each: the reference path, the current

entry, the conventions, and a distinct direction.

• Each agent writes its OWN /tmp/<key>-<n>.mjs draft (never edits personas.mjs — avoids

conflicts), renders it, Reads the PNG, compares to the photo, iterates, and **returns the final

rows**.

• You pick the best, splice it in, review in the gallery. Refine one axis per pass (e.g. head

shape, then hair). This is the loop used for garry/musk.

QA bar

• Always review visually — the render-png contact sheet and the gallery.html original-vs-pixel

view — never blind. Judge: does it read / look like the person across all 5 expressions + blink?

• jobs is the reference standard. Keep faces front-facing/symmetric unless intentional.
• Don't commit assets/ (reference photos stay local). Persona edits to personas.mjs ARE committable.