Agent Skills / image set

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&rsquo;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.

what the engine is holding, and when 1 · LISTING every skill, every turn 2 names + descriptions 392 characters selection happens here, and on nothing else 2 · SKILL.MD one skill, once chosen ≤ 152 lines each 6 fixed sections contracts are copied in, not referenced 3 · DEFERRED only when the situation calls 18 playbooks · 16 reference budgeted / unbudgeted judgement stays; what rots is dated
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-generate full

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-review read-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).

SkillDoes not doGoes to
image-generatedeciding whether a picture is usable, or good enough to stop changing image-review
image-reviewproducing the corrected image image-generate
image-reviewdeciding 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.

RoutePatternWhenChainCondition
illustratelinear a picture is needed for use or publication, alone or as one of a setimage-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-offlinear the look is settled; only an exploratory candidate is wanted, not an asset ready to useimage-generate gate · the look or brief is named; report a candidate, never a production usability verdict
repairlinear a picture that exists is wrong in a way someone can point atimage-review → image-generate → image-review gate · locate findings before changing; the final review checks their removal and any new drift
restylelinear the content is right and the look is notimage-generate → image-review —
ship-existinglinear the picture is already approved for the intended use and only delivery remainsimage-generate —
look-checkreport-only is this image usable, and what is wrong with itimage-review stops at · one verdict with each defect located, ranked, and attributed to a cause. Nothing is regenerated
refine-to-briefloop iterate a candidate until it meets the brief or the budget stops itimage-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.

AxisVocabulary
Evidence gradesmeasured inspected asserted
Residual classesBLOCKED OUT-OF-SCOPE DEFERRED UNSPECIFIED
StatusesDONE PARTIAL BLOCKED
Sizing tiersT0 T1 T2
Route patternslinear loop report-only
Recipeengine model prompt excluded size inputs output IRREPRODUCIBLE
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.

ClassToolsWritesSkills
read-onlyRead, Grep, Glob, Bash no 1
doc-writeRead, Grep, Glob, Bash, Write yes 0
fullRead, 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_lines152
description_chars200
playbook_lines300
playbooks_per_skill15
shared_file_lines115
shared_lines_total620
skills_max8
routes_max12
route_stages_max6
repo_md_lines_total4200

Measured now

skills2 / 8
routes7 / 12
shared contract lines615 / 620
repository markdown3,919 / 4,200
static rules39

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