agentleFS
Cotal-AICotal-AI/Cotal/.claude/skills/pixel-face/SKILL.md

pixel-face

Skill393 starsChanged 15 days agoApache-2.0View on GitHub

Create or improve a 32×32 pixel-art persona face for the Frontier Faces demo (examples/04-frontier-faces/personas.mjs) — the animated agent avatars rendered by face-term.mjs / the browser <cotal-face> / the gallery. Use when the user asks to add a new persona/face/avatar, improve an existing one (hair, eyes, likeness, expression), make it "look more like" someone, or fix a face that "doesn't read". Drives the example's own tools (img2rows.mjs, render-png.mjs) and follows FACE-DESIGN.md; uses a multi-agent variant loop for likeness.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read its entry in personas.mjs + its reference assets/<key>.<ext> and the current render.

    line 63
  2. Distinctive:

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

    line 70
  3. Very specific:

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

    line 81
  4. Very specific:

    Don't commit assets/ (reference photos stay local).

    line 84

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

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

Improve an existing persona

  1. Read its entry in personas.mjs + its reference assets/<key>.<ext> and the current render.
  2. 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.
  3. 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:

  1. 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.
  2. 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.
  3. 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.