Two agent skills covering image work — one decides what a picture must say, asks a generator for it, changes it and gets the file into a project; the other judges what comes back — plus the contracts they share and the budgets that keep the set from growing into something nobody can route through.
None of them generate pixels themselves. The generation is one of two
installed tools — Codex's own imagegen skill and its built-in image_gen tool
(switched on by the image_generation feature), or the generate_image tool
built into the agy CLI.
This set is the discipline around them: what to ask for, how many times, whether
anyone looked, and what has to be written down so the picture can be made again.
The two do not take the same argument. One takes no size argument on its default path, and a pixel canvas subject to four constraints on its fallback CLI; the other takes an aspect ratio off a fixed list and no pixel count at all, and writes JPEG. Which one ran is the first thing a recipe settles, because half the fields beside an image mean something different depending on the answer.
| Skill | Owns | Produces |
|---|---|---|
image-generate |
Making a picture and changing one: the brief, the request, the run and its keeper, the edit, the file in the project | Briefs, prompt records, images, recipes, files and an asset catalog |
image-review |
Whether the result is usable, and what is wrong with it | Nothing. Report-only |
Every retained generated candidate carries its recipe. Capture the request
at invocation; immediate discards need no persistent recipe. Text-only work and
references to supplied images need no invented generation fields. engine,
model, prompt verbatim, excluded, size asked for and size on disk,
inputs, output. A picture is the one deliverable here that carries no
history inside itself: open the file six weeks later and nothing in it says
what was asked for or what it was made from, so the wording has to travel
beside it.
A recipe does not establish exact pixel regeneration. IRREPRODUCIBLE limits
that promise, not copying the original or editing it. Check the selected tool's
current controls rather than treating the generator snapshots as a guarantee
(skills/_image/RECIPE.md).
An image can be run — it is a file, and a file can be opened. So the grade
here is about whether anyone looked. measured — the image opened and
viewed, its dimensions or bytes read, a defect located in a named region.
inspected — opened and reasoned over, with the reason nothing could be
measured. asserted — the claim alone, which never supports completion.
The prompt is a request, never a description of what came back. "It is 3:2
because I asked for 3:2" is asserted, and so is every count of fingers and
every word of rendered text taken from the wording rather than the pixels. This
is the failure the set is built around, and it is not hypothetical: asking the
default path for 1024×1024 produced a 1254×1254 file, because that path takes
no size argument at all.
The unit is the decision, not the batch. Four candidates and one export is
five files and a dozen decisions. Each promised decision carries a grade or
appears as UNSPECIFIED — which is what gets invented at export time by
whoever hits it first.
A skill is loaded in three stages, and each costs something different. The
listing carries name and description only, for every enabled skill, on
every turn. SKILL.md is read in full once a skill is chosen. Anything it
points at is read only when the situation calls for it.
Selection happens on the description alone. Nothing else is in front of the
engine at that moment. So every word that selects a skill appears literally in
its description, and image-registry/capabilities.yaml
lists those words per skill. A rule checks the two agree.
Boundaries live in one file. That same registry carries not: — what a
skill does not do and where that work goes instead. Descriptions never name a
neighbour. If they did, adding a third skill would mean editing the other two,
and a description would spend its 200-character listing budget advertising a
competitor.
Contracts are delivered, not referenced. A rule kept in skills/_image/ is
read on a minority of launches, so the operative part of each contract is copied
verbatim into every SKILL.md between <!-- deliver:… --> markers.
image-registry/delivered/ holds the source, make render writes it back, and
a rule fails if any copy has drifted.
Knowledge is split by whether it rots. playbooks/ holds judgement —
failure types, the order decisions go in, structures that stay true — and is
budgeted. reference/ holds what goes stale — a model's size constraints, an
invocation, a taxonomy of edit modes — carries no line budget, and states its
purpose and the date anyone last checked it instead. A rule rejects a pinned
version, a date, or a model identifier inside a playbook: in this domain the
model name is the fastest-rotting string there is.
Where a number follows from another number, a date is not enough. A
Verified: line records that someone looked once; it cannot fail, so it cannot
catch a value edited into a wrong one later. make figures recomputes what the
reference layer states from the reference layer itself — every listed canvas
size put back through the four constraints the same page states, its ratio
reduced and its megapixel figure recomputed, every size listed as rejected
checked to still be rejected by the rule named against it, and every export rung
recomputed from its own base and factor and matched to its @Nx label — and
the aspect tolerance the page states is matched to the one imgfacts.py uses. The
deliberate errors that prove it can fail are not a claim in this file, and
neither is how many there are — they are image-tools/test_figures.py, they run
in make check, and some of them make the checks vacuous rather than wrong: a
row rewritten out of a computable shape, a table header renamed, a constraint
deleted from the prose it reads.
Five tools, linked into the skills that can run them.
imgfacts.py reads what is actually in a file —
dimensions, format, bytes, alpha, whether a colour profile is declared, the
shape an Exif orientation turns the picture to on screen, and whether a canvas
is legal, or which aspect is nearest, for the generator that will run it. It is what makes measured cheap,
because a grade that costs effort gets skipped.
recipe.py captures a generated file out of whichever
generator produced it and writes its recipe in the same move. Prefer the
returned path and actual generator explicitly; the newest-file fallback does
not establish invocation provenance. It reads the prompt and the whole file
before it copies anything — a file that stops short of its end marker, as one
still being written does, is refused — and places the file and its recipe
together, so a failure leaves no recipe-less asset behind. It refuses a
destination whose extension names another format, and a link at either name. It checks fields and
dimensions later. strip.py removes what
should not ship — Exif, XMP, generation parameters, comments, timestamps,
embedded thumbnails, and anything appended after the image ends — while
keeping the colour profile, the alpha channel and any content credential the
project decided to carry — and refusing to keep a credential beside any other
removal, which would leave its signature reading as tampered. refute.py puts a claim to
the engines that did not make it and asks them to break it; an answer outside
its schema, from an engine that exited non-zero or reported an error, or in
text that is not UTF-8, is no answer, a claim refuted or contested exits 3, one that not
every refuter could read exits 1, and unrefuted is never proof.
catalog.py inventories delivered images as HTML with
previews or JSON, measuring file properties and linking recipes without copying
prompts. The delivery skill refreshes it after placement and links it in the report.
None of the four file tools needs an image library: they read and edit headers rather than decoding pixels, so there is nothing to install beyond the PyYAML the harness already requires, and nothing is ever re-encoded. A tool that needed a build step before it could say how wide a file is would not get run.
strip.py names what stays rather than what goes, so a metadata block nobody
here has heard of is removed by default instead of shipped by default. It
refuses rather than guessing — a non-upright Exif orientation stops the run,
because dropping that flag without applying the rotation turns the picture
sideways somewhere downstream, and a truncated file stops it too, because a
copy of half a picture is not a stripped one. Every byte that does not reach
the output is named in the report, in all three formats. It re-reads its own
output in memory, before touching the disk, refusing if the dimensions, format,
alpha or profile moved, and it replaces a lone file whole or not at all; a file
with other hard links, or in a directory that refuses new files, is rewritten
through its own inode so every name sees the result, with the original put
back if that write fails part-way. In place, it writes only over the bytes it
read: a file another process saved in the meantime is left as that process
saved it, and the run says so. A file with nothing to remove is left as it
is, not rewritten in place. A run with neither --out nor --in-place
writes nothing.
One parser per format, shared. strip.py reads JPEG through the same marker
scanner imgfacts.py uses. Two parsers of one format is two chances to disagree
about it, and a review found them doing exactly that on the fill bytes the
standard allows before a marker.
The tools directory is never linked whole — a skill holding Bash and all of it
could edit the harness it is part of. linked_tools in the registry names which
skills get which tool, and a rule checks each link is present exactly where the
skill's class grants a shell, so a missing one fails rather than passing as an
oversight.
One declaration for the generators' numbers. generators in the registry
holds both — the four canvas constraints for one, the list of aspects for the
other, each tagged with the control that separates them. imgfacts.py decides
legality from it, image-generate/reference/sizes.md states both in prose for a
reader, and make figures checks the prose against the registry — so the tools
and the page cannot quietly disagree. Adding a third generator is a registry
edit; the tools resolve which is which by control. A second canvas generator
trips an assert rather than letting the first in the file win, and with a second
aspect generator --check-aspect needs --generator to say which is meant.
Budgets are enforced, not intended.
image-registry/harness.yaml holds every
threshold. image-tools/validate.py decides them and CI fails on a violation.
Generation and generative refinement share a paid-attempt budget. The brief
carries budget, cumulative spent travels in the handoff (including failed or
refused attempts unless confirmed uncharged), and the loop has a hard cycle
bound, not a target. Unknown billing is not zero; candidate count is not cost.
A skills directory is flat and shared with every other set installed on the machine. A generic name placed there is a silent collision.
One declaration. set: image in image-registry/harness.yaml is the only
place the name is written. The prefix (image-), the shared directory
(skills/_image/), and the label every document carries all derive from it.
Every directory this set owns carries the set name — image-* or _image,
with only the platform's own directories exempt. Carrying the prefix is not what
makes something installable: a skill is a directory holding a SKILL.md, and
only those are linked.
Everything a skill reads lives inside the skill, reached through symlinks
named _image and registry. A skill is handed its own directory as the base
for relative paths, and those are normalised lexically, so ../_image/X.md
does not travel back through the install symlink. A shell follows the link and
finds the file, which is what makes this fail quietly.
| File | What it fixes |
|---|---|
skills/_image/CONTRACT.md |
Evidence grades, status, residual classes, the completion sweep |
skills/_image/RECIPE.md |
The seven fields every retained generated candidate carries, and what IRREPRODUCIBLE obliges |
skills/_image/SIZING.md |
How much ceremony a request is worth; when a dialogue is mandatory; the brief |
skills/_image/HANDOFF.md |
What passes between skills, and the checks the receiver runs |
skills/_image/VALUES.md |
The order that decides when two goods conflict, and the escape hatch |
skills/_image/ROUTING.md |
Guidance. Read when the owner is unclear or the work spans several |
skills/_image/REPORT.md |
What a person reads: the order, the ceiling per tier, and why the recipe is the record |
image-skills/
├── README.md
├── Makefile
├── image-registry/ # budgets, boundaries, routes, delivered blocks
├── image-tools/ # imgfacts · recipe · strip · catalog · refute · engine · render
│ # · validate · figures · tests
└── skills/ # everything the CLI reads
├── _image/ # contracts in force on every run
└── image-<facet>/ # a SKILL.md is what makes this a skill, and
│ # only skills are installed
├── SKILL.md # Owns / Before starting / Decide first /
│ # Always·Never / Verify with / Done when
├── _image -> ../_image # short names: the parent scopes them
├── registry -> ../../image-registry
├── imgfacts.py -> ../../image-tools/imgfacts.py # declared per skill
│ # in registry/harness.yaml linked_tools
├── playbooks/ # judgement. Budgeted, and must not rot
└── reference/ # what goes stale. No line budget, dated instead
Run from the project root, using the path to this checkout's tool:
python3 image-tools/catalog.py --dir assets --out .agents/asset-catalog.html
python3 image-tools/catalog.py --dir assets --out .agents/asset-catalog.json --format jsonOpen HTML locally; its relative links reference the original PNG, JPEG, WebP and
GIF files. Nothing is copied or published. Add --replace to refresh a confirmed
catalog destination. See the catalog guide
for access policy, provenance, unsupported formats and failure handling.
make check # the rules, the figures, the tools, and proof each still fires
make render # after editing anything in image-registry/delivered/
make hooks # run the rules on every commit, against what is staged
make catalog-test # measured catalogs, safe links, and preserved source filesThe hook checks the index, not the working tree: the commit is what is staged,
so an unrelated unstaged edit cannot fail it and an unstaged fix cannot pass it.
It will not replace a different pre-commit hook that is already installed
unless told to with FORCE=1, and in a shared hooks directory it stands aside
in any repository that is not this set. An intent-to-add file (git add -N)
is not in the commit, so it is not checked.
Adding a rule means adding a deliberate violation to
image-tools/test_validate.py, and adding a figure check means adding one to
image-tools/test_figures.py — including one that makes the check vacuous
rather than wrong. A check only ever seen passing may be checking nothing. Each
case also names what has to fire — a message for a rule, the checker for a
figure — because a neighbour catching the same edit proves nothing about the
one under test. The other direction is covered too: QUIET cases in
test_validate.py are ordinary writing a rule must not fire on.
The tools get the same treatment in image-tools/test_tools.py, and it is worth
saying what that has caught so far. Inverting the keyed-transparency branch in
imgfacts.py did not fail the suite, because no fixture had a tRNS chunk in
it. Dropping a standalone JPEG marker did not fail it, because the fixtures
checked what was removed and never that the rest survived byte for byte. And
widening ASPECT_TOLERANCE to 1.0 did not fail it, because the assertion read
the constant from the module it was testing — which passes for any value that
module picks. All three fixtures exist now. A later review found more of the
same kind across the tools and the checks — metadata appended after a JPEG's
end, a cut-short PNG written out short, an engine's "false" read as a
refutation, a validator rule that matched nothing in the corpus, a budget no
tool read — and each now has a case, seen failing against the old code before
the fix went in. A test suite only ever seen passing has the same problem a
check does, and an assertion that borrows the
implementation's own number is the version of that which looks fine in review.
make link # into ~/.claude/skills, ~/.codex/skills, ~/.gemini/…
make link CLAUDE_DIR="$PWD/../my-project/.claude/skills" # one project's skillsEach image-* skill is linked individually, so a skills directory keeps
whatever else it already carries, and a name already taken by a real directory
is skipped rather than overwritten. A host directory is written to only when
its parent exists, and a relative one is read from this checkout — so name a
project's directory by its absolute path. A path with a space in it — a home
like /Users/Jo Smith — is read whole.
docs/index.html is a generated page — every figure on it is
read off this repository, the way make figures recomputes what the reference
layer states. Do not edit it by hand: tools/pages.py in the agent-toolkit
repository writes it, tools/pages.py --check fails when it is behind, and
.github/workflows/pages.yml here only publishes what is committed.
- A recipe alone cannot guarantee identical pixel regeneration. Backing-tool controls are moving targets; the original file can still be reused or edited
allowed-toolsis one CLI's mechanism. Where a tool grant is not enforced, theNeverlines are discipline and nothing more- No rule can check that a file was actually opened. The contract says a
claim about a picture rests on having looked; the validator cannot see whether
anyone did.
imgfacts.pymakes the mechanical half cheap, and it is no evidence at all about the half that needs eyes: it reads headers, never pixels, so it cannot see a sixth finger, garbled lettering, or a shadow going the wrong way. That half is enforced by the refuting engine, or not at all - The fixtures do not model how a model chooses. They catch a missing or duplicated signal. Passing them is not evidence that nothing will be misrouted
Verified:dates are not checked against anything. A stale reference file with a fresh date passes. The date makes the staleness visible to a reader; it does not detect it- The backing skill is a moving target. Its modes, its taxonomy and its size
constraints are read off one installed copy on one machine, recorded in
reference/with the date, and nothing re-checks them