ImageWhat should this picture say, and did the one that came back say it?
Two skills over image work — one decides what a picture must say, words the request a generator receives, runs it, changes what comes back and gets the file into a project; the other judges whether it is usable. Neither generates pixels: that is Codex’s own <code>imagegen</code> skill, and this is the discipline around it.
2skills
7routes
18playbooks
16reference
39static rules
392listing chars
01What is loaded, and when it is paid for
A skill arrives in three stages and each costs something different. Almost
every design rule in this repository follows from that asymmetry rather than from taste.
Cost is not uniform across the three. Stage 1 is paid on every turn for every
installed skill, which is why a description is budgeted to
200 characters and why boundaries are kept out of it.
Stage 3 is paid only by the run that needs it, which is where anything long or
perishable belongs.
02The 2 skills
Each owns one kind of work and states it in its own Owns section.
The tags under it are the facets recorded in
image-registry/capabilities.yaml, which is also what the fixtures route
against.
image-generatefull
Everything that makes a picture or changes one, from a look nobody has settled to a file the project references: the brief, the request the generator receives, the paid run and its keeper, the edit to a picture that exists, and the export. It never decides whether the result is usable — that verdict belongs to a reader who did not make it.
brief
prompt-structure
exclusions
invocation
candidate-count
recipe-capture
selection
region-edit
upscale
format
naming
placement
alt-text
asset-catalog
image-reviewread-only
Looking at a picture and saying what is wrong with it, where, how badly, and whether it can ship. It writes nothing. That is the guarantee that makes it worth having: a stage that both judged and fixed cannot say which it did first.
artefact-detection
anatomy-and-text
off-brief-drift
severity-ranking
verdict
03Where a skill stops
Boundaries live in one file and never in a description. A description that
named its neighbours would spend listing budget advertising them, and adding a skill would
mean editing every other one — so the cost of an addition would stop being O(1).
Skill
Does not do
Goes to
image-generate
deciding whether a picture is usable, or good enough to stop changing
image-review
image-review
producing the corrected image
image-generate
image-review
deciding the aesthetic the picture was aiming at
image-generate
04Chains that recur
A chain of names expresses linear work only. Where a stage repeats until a
condition holds, the entry carries the condition, the judge, and a hard cycle limit —
without all three, “until it looks right” has no stopping rule and the loop ends
when somebody gets tired.
Route
Pattern
When
Chain
Condition
illustrate
linear
a picture is needed for use or publication, alone or as one of a set
image-generate → image-review → image-generate
gate · the brief names what the image is judged against before any prompt is written; review the actual candidate for its intended use, and a set member by member and together, before delivery
one-off
linear
the look is settled; only an exploratory candidate is wanted, not an asset ready to use
image-generate
gate · the look or brief is named; report a candidate, never a production usability verdict
repair
linear
a picture that exists is wrong in a way someone can point at
image-review → image-generate → image-review
gate · locate findings before changing; the final review checks their removal and any new drift
restyle
linear
the content is right and the look is not
image-generate → image-review
—
ship-existing
linear
the picture is already approved for the intended use and only delivery remains
image-generate
—
look-check
report-only
is this image usable, and what is wrong with it
image-review
stops at · one verdict with each defect located, ranked, and attributed to a cause. Nothing is regenerated
refine-to-brief
loop
iterate a candidate until it meets the brief or the budget stops it
image-generate → image-review
gate · inherit all generation/edit attempts and spend; a new defect does not reset this loop or its budget
05The mechanism this set has and its siblings do not
Eight sets share one validator and one contract shape. Each declares exactly
one signature mechanism, and that declaration is the whole difference — which is what
keeps 8 copies of the same rules from becoming 8 dialects.
recipe · _image/RECIPE.md
A generated picture carries no history inside itself, so seven fields travel beside it — the engine, the model, the prompt verbatim, what was excluded, the size asked for and the size on disk, the inputs, the output. The generator exposes no seed, so a recipe fixes intent and never pixels: that gap is IRREPRODUCIBLE, stated once rather than papered over with a seed nobody has.
engine
model
prompt
excluded
size
inputs
output
IRREPRODUCIBLE
Owed by 2 of 2
image-generate
image-review
A rule states the mechanism
inside every skill through a delivered block. A skill that owes it must also name
its own half in its own words — a rule stated everywhere and owned nowhere is a
ritual.
06What counts as done
Reporting completion without meeting this is reporting a wish. The
vocabulary is fixed in image-registry/harness.yaml and defined in
_image/CONTRACT.md; the validator checks the contract actually
defines every word it declares.
The completion sweep is never omitted. Before reporting, both halves
run and both results are stated: every marker this run introduced appears in the handoff with a
class, and every claim made is a claim at its floor. While either pair disagrees, the status is
not DONE.
07Permission classes
A class is declared once in the registry and the validator checks each
SKILL.md front matter matches it exactly. Where a CLI does not enforce tool
grants, the Never lines are discipline and nothing more — that limit is stated
rather than papered over.
Class
Tools
Writes
Skills
read-only
Read, Grep, Glob, Bash
no
1
doc-write
Read, Grep, Glob, Bash, Write
yes
0
full
Read, Grep, Glob, Bash, Write, Edit
yes
1
08Budgets, and the rules that decide them
Every threshold is declared in one place and read from there by
image-tools/validate.py. A number written twice is a number that drifts.
Raising a limit is the last resort — merging, deleting, compressing and relocating come
first.
Declared limits
skill_md_lines
152
description_chars
200
playbook_lines
300
playbooks_per_skill
15
shared_file_lines
115
shared_lines_total
620
skills_max
8
routes_max
12
route_stages_max
6
repo_md_lines_total
4200
Measured now
skills
2 / 8
routes
7 / 12
shared contract lines
615 / 620
repository markdown
3,919 / 4,200
static rules
39
Adding a rule means adding a
deliberate violation and watching it fail. A check only ever seen passing may be checking
nothing.
09Installing it
Each image-* directory is symlinked 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.
make link # into ~/.claude/skills
make link CLAUDE_DIR=.claude/skills
make check # the rules, then proof the rules still fire
make render # after editing a delivered block
make hooks # run the rules on every commit
Selection happens on the description alone. Every word that selects a
skill appears literally in its description, and a rule checks the registry and the
description still agree.
Contracts are delivered, not referenced. A rule kept only in
_image/ is read on a minority of launches, so the operative part
is copied verbatim into every skill and a rule fails if any copy has drifted.
Knowledge is split by whether it rots. Playbooks hold judgement and are
budgeted; reference holds what goes stale, carries no line budget, and states what re-checks
it instead of a bare date.
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.