mirror of
https://github.com/openai/skills.git
synced 2026-09-21 08:26:39 +03:00
hatch-pet: use app mention syntax for imagegen
This commit is contained in:
Andrew Ambrosino
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: hatch-pet
|
||||
description: Create, repair, validate, visually QA, and package Codex-compatible animated pets and pet spritesheets from character art, generated images, company or prospect brand cues, or visual references. Use when a user wants a lightweight-worker Codex pet workflow, a non-pixel custom pet style, a prospect or company mascot pet, or a full 8x9 animated pet atlas with transparent unused cells, QA contact sheets, and pet.json packaging. This skill composes the installed $imagegen system skill for visual generation and uses bundled scripts for deterministic spritesheet assembly.
|
||||
description: Create, repair, validate, visually QA, and package Codex-compatible animated pets and pet spritesheets from character art, generated images, company or prospect brand cues, or visual references. Use when a user wants a lightweight-worker Codex pet workflow, a non-pixel custom pet style, a prospect or company mascot pet, or a full 8x9 animated pet atlas with transparent unused cells, QA contact sheets, and pet.json packaging. This skill composes the installed @imagegen system skill for visual generation and uses bundled scripts for deterministic spritesheet assembly.
|
||||
---
|
||||
|
||||
# Hatch Pet
|
||||
@@ -13,7 +13,7 @@ User-facing inputs are optional. If the user omits a pet name, infer one from th
|
||||
|
||||
## Generation Delegation
|
||||
|
||||
Use `$imagegen` for all normal visual generation.
|
||||
Use `@imagegen` for all normal visual generation.
|
||||
|
||||
Before generating base art, row strips, or repair rows, load and follow the installed image generation skill:
|
||||
|
||||
@@ -21,21 +21,21 @@ Before generating base art, row strips, or repair rows, load and follow the inst
|
||||
${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md
|
||||
```
|
||||
|
||||
Do not call the Image API, image CLI, or any other image-generation path directly. Let `$imagegen` choose its own built-in-first path and fallback rules. If `$imagegen` says a fallback requires confirmation, ask the user before continuing.
|
||||
Do not call the Image API, image CLI, or any other image-generation path directly. Let `@imagegen` choose its own built-in-first path and fallback rules. If `@imagegen` says a fallback requires confirmation, ask the user before continuing.
|
||||
|
||||
When invoking `$imagegen`, pass the generated pet prompt as the authoritative visual spec. Pet prompts should stay concise, state-specific, sprite-production oriented, and grounded in the listed input images. Keep longer policy and QA rules in this skill and the deterministic review scripts rather than expanding them into every image prompt. Do not wrap prompts in the generic `$imagegen` shared prompt schema.
|
||||
When invoking `@imagegen`, pass the generated pet prompt as the authoritative visual spec. Pet prompts should stay concise, state-specific, sprite-production oriented, and grounded in the listed input images. Keep longer policy and QA rules in this skill and the deterministic review scripts rather than expanding them into every image prompt. Do not wrap prompts in the generic `@imagegen` shared prompt schema.
|
||||
|
||||
Use this skill's scripts for deterministic image work only: preparing layout guides and prompts, mirroring approved `running-left`, extracting frames, validating rows, composing the final atlas, and creating contact-sheet plus motion-preview QA media. Parent-owned shell/`jq` steps handle manifest updates, packaging, and cleanup.
|
||||
|
||||
## Storage Controls
|
||||
|
||||
The built-in `$imagegen` path stores generated PNG bytes in the rollout that invokes it, even when it also writes a file under `${CODEX_HOME:-$HOME/.codex}/generated_images`. Deleting files later reduces filesystem use, but it does not shrink an already-written rollout. Keep image generation isolated and bounded:
|
||||
The built-in `@imagegen` path stores generated PNG bytes in the rollout that invokes it, even when it also writes a file under `${CODEX_HOME:-$HOME/.codex}/generated_images`. Deleting files later reduces filesystem use, but it does not shrink an already-written rollout. Keep image generation isolated and bounded:
|
||||
|
||||
- Use one lightweight generation worker per visual job. Do not batch multiple base/row jobs into the same worker.
|
||||
- Workers must return only `selected_source=...` and `qa_note=...`; they must not include Markdown image previews, base64, or extra visual attachments in their final response.
|
||||
- The parent must not open every generated PNG visually. Use worker QA for each job and inspect only the final contact sheet.
|
||||
- After copying the selected generated output into `decoded/`, remove the selected original from `${CODEX_HOME:-$HOME/.codex}/generated_images` when it lives there, then remove its now-empty generation directory if possible.
|
||||
- For storage-sensitive full runs, ask the user whether to use the `$imagegen` CLI fallback when available. That path requires local API credentials and explicit user confirmation, but it can avoid built-in image payloads being embedded in rollout events.
|
||||
- For storage-sensitive full runs, ask the user whether to use the `@imagegen` CLI fallback when available. That path requires local API credentials and explicit user confirmation, but it can avoid built-in image payloads being embedded in rollout events.
|
||||
|
||||
## Brand Discovery
|
||||
|
||||
@@ -92,11 +92,11 @@ brand_sources=<same comma-separated URLs from Generation handoff>
|
||||
|
||||
The parent should save the markdown brief before preparing the run, then pass it to `prepare_pet_run.py` as `--brand-discovery-file` together with `--brand-name`, `--brand-brief`, repeated `--brand-source`, and a concise `--pet-notes` value based on `avatar_seed` when the user did not provide a better avatar description. Keep the full brief for review; only the compact handoff fields should shape prompts. If web search is unavailable and the user gave only a bare brand name, ask for brand cues before generating.
|
||||
|
||||
For a normal pet run, expect up to 10 visual generation jobs: 1 base pet plus 9 row-strip jobs. The Codex app contract currently uses all 9 states: `idle`, `running-right`, `running-left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review`. The only deterministic visual derivation is `running-left`, which may be produced by mirroring `running-right` only after `running-right` has been generated, visually inspected, and explicitly approved as safe to mirror. If mirroring is not appropriate, generate `running-left` as a normal grounded `$imagegen` row.
|
||||
For a normal pet run, expect up to 10 visual generation jobs: 1 base pet plus 9 row-strip jobs. The Codex app contract currently uses all 9 states: `idle`, `running-right`, `running-left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review`. The only deterministic visual derivation is `running-left`, which may be produced by mirroring `running-right` only after `running-right` has been generated, visually inspected, and explicitly approved as safe to mirror. If mirroring is not appropriate, generate `running-left` as a normal grounded `@imagegen` row.
|
||||
|
||||
After selecting a visual output, the parent agent copies that exact image into the job's `decoded/` path and marks the job complete in `imagegen-jobs.json`. Do not write helper scripts that populate row outputs. The deterministic Python scripts may only process already-generated visual outputs.
|
||||
|
||||
Only the base job may be prompt-only. Every row-strip job generated through `$imagegen` must use the input images listed in `imagegen-jobs.json`, including the canonical base reference created after the selected base output is copied. Treat any row generation without attached grounding images as invalid.
|
||||
Only the base job may be prompt-only. Every row-strip job generated through `@imagegen` must use the input images listed in `imagegen-jobs.json`, including the canonical base reference created after the selected base output is copied. Treat any row generation without attached grounding images as invalid.
|
||||
|
||||
## Pet-Safe Styles
|
||||
|
||||
@@ -190,7 +190,7 @@ python "$SKILL_DIR/scripts/prepare_pet_run.py" \
|
||||
All arguments above are optional except any flags needed to express user constraints. For text-only requests, pass the concept through `--pet-notes` and omit `--reference`; `prepare_pet_run.py` will infer a name, description, chroma key, and output directory as needed.
|
||||
For brand-only requests, run the discovery worker first, save the markdown brief, then pass the brief path through `--brand-discovery-file`, `avatar_seed` through `--pet-notes`, `brand_name` through `--brand-name`, `brand_brief` through `--brand-brief`, and each source URL through repeated `--brand-source`.
|
||||
|
||||
2. Inspect `imagegen-jobs.json` for the next ready `$imagegen` jobs. A job is ready when its `status` is not `complete` and every id in `depends_on` is already complete. Prefer reading the manifest directly with `jq` or the editor instead of adding helper scripts for status display:
|
||||
2. Inspect `imagegen-jobs.json` for the next ready `@imagegen` jobs. A job is ready when its `status` is not `complete` and every id in `depends_on` is already complete. Prefer reading the manifest directly with `jq` or the editor instead of adding helper scripts for status display:
|
||||
|
||||
```bash
|
||||
jq '.jobs[] | {id, kind, status, depends_on, prompt_file, retry_prompt_file, input_images, output_path, derivation_policy}' /absolute/path/to/run/imagegen-jobs.json
|
||||
@@ -204,13 +204,13 @@ jq '.jobs[] | {id, kind, status, depends_on, prompt_file, retry_prompt_file, inp
|
||||
- Generate `running-left` normally with a lightweight worker when mirroring would change meaning or identity.
|
||||
- Generate the remaining rows with lightweight workers, using every input image listed for each job.
|
||||
|
||||
For each ready visual job, invoke `$imagegen` with the prompt file listed in `imagegen-jobs.json`, every listed input image with its role label, and the default built-in `image_gen` path unless `$imagegen` itself routes otherwise. The parent agent must keep its own image handling minimal: do not open every generated base or row in the parent rollout. Workers return only the selected source path and a one-sentence QA note; the parent records the selected source path in the manifest.
|
||||
For each ready visual job, invoke `@imagegen` with the prompt file listed in `imagegen-jobs.json`, every listed input image with its role label, and the default built-in `image_gen` path unless `@imagegen` itself routes otherwise. The parent agent must keep its own image handling minimal: do not open every generated base or row in the parent rollout. Workers return only the selected source path and a one-sentence QA note; the parent records the selected source path in the manifest.
|
||||
|
||||
`prepare_pet_run.py` creates 9 row-specific layout guide images under `references/layout-guides/`, one per animation state. Row jobs attach the matching guide as a layout-only input so the model can follow the correct frame count, spacing, centering, and safe padding. Treat these guides as invisible construction references: the generated row strip must not include visible boxes, borders, center marks, labels, guide colors, or the guide background.
|
||||
|
||||
When generating row strips, keep the identity lock in the row prompt authoritative. Preserve the same style, face, markings, palette, materials, prop design, body proportions, and silhouette from the canonical base. Row jobs attach the layout guide and canonical base by default; the decoded base is kept in the run folder for deterministic processing rather than sent as a redundant generation input.
|
||||
|
||||
If `$imagegen` returns a transport-level `Bad Request` for a row, retry that same row once with its generated `retry_prompt_file`. The retry prompt preserves the row id, frame count, chroma key, canonical-base identity, and state action. Keep the canonical base attached. If the retry still fails, stop and report the failing row and prompt paths instead of switching to any other generation path.
|
||||
If `@imagegen` returns a transport-level `Bad Request` for a row, retry that same row once with its generated `retry_prompt_file`. The retry prompt preserves the row id, frame count, chroma key, canonical-base identity, and state action. Keep the canonical base attached. If the retry still fails, stop and report the failing row and prompt paths instead of switching to any other generation path.
|
||||
|
||||
4. After selecting a generated output for a job, copy it into the decoded output path and mark the job complete. For `base`, also create the canonical identity reference:
|
||||
|
||||
@@ -376,7 +376,7 @@ Keep `pet_request.json`, `final/spritesheet.webp`, `final/validation.json`, `qa/
|
||||
|
||||
## Lightweight Visual Workers
|
||||
|
||||
Use lightweight subagents for image-heavy work by default. This bounds each `$imagegen` rollout to one selected image, keeps contact-sheet vision payloads out of the parent thread, and reduces cost while preserving the full 9-state app contract.
|
||||
Use lightweight subagents for image-heavy work by default. This bounds each `@imagegen` rollout to one selected image, keeps contact-sheet vision payloads out of the parent thread, and reduces cost while preserving the full 9-state app contract.
|
||||
|
||||
## Subagent Delegation
|
||||
|
||||
@@ -396,7 +396,7 @@ Base worker responsibilities:
|
||||
|
||||
- handle only the `base` job
|
||||
- read `prompts/base-pet.md` and use any listed reference images
|
||||
- use `$imagegen` only
|
||||
- use `@imagegen` only
|
||||
- honor any compact brand inspiration line in the prompt as broad visual/personality guidance, without copying logos, readable marks, UI screenshots, slogans, or text
|
||||
- return only `selected_source=/absolute/path/to/selected-output.png` and `qa_note=<one sentence>`
|
||||
|
||||
@@ -404,7 +404,7 @@ Row worker responsibilities:
|
||||
|
||||
- handle exactly one row job
|
||||
- read the row prompt and use all listed input images
|
||||
- use `$imagegen` only; do not draw, edit, tile, or synthesize sprites locally
|
||||
- use `@imagegen` only; do not draw, edit, tile, or synthesize sprites locally
|
||||
- perform a quick visual sanity check for frame count, identity, chroma background, spacing, clipping, and detached effects
|
||||
- enforce the row prompt's transparency and effects rules, including no detached effects, no wave marks for `waving`, no speed lines or dust for directional running rows, no literal foot-running for the non-directional `running` row, and only attached opaque sprite-like tears/smoke/stars when allowed by the state prompt
|
||||
- return only `selected_source=/absolute/path/to/selected-output.png` and `qa_note=<one sentence>`
|
||||
@@ -434,7 +434,7 @@ Prompt file: <absolute base prompt file>
|
||||
Input images:
|
||||
- <absolute path> — <role>
|
||||
|
||||
Use $imagegen only. Read the base prompt and attach every listed input image. If the prompt contains brand inspiration, use it only as broad mascot-safe guidance; do not copy logos, readable marks, UI screenshots, slogans, or text. Before returning, visually check that the result is one centered full-body pet on a flat chroma background, with no text, scenery, shadows, or detached effects.
|
||||
Use @imagegen only. Read the base prompt and attach every listed input image. If the prompt contains brand inspiration, use it only as broad mascot-safe guidance; do not copy logos, readable marks, UI screenshots, slogans, or text. Before returning, visually check that the result is one centered full-body pet on a flat chroma background, with no text, scenery, shadows, or detached effects.
|
||||
|
||||
Do not edit manifests, copy into decoded, mark jobs complete, generate rows, run image-processing scripts, repair, package, or open unrelated files.
|
||||
Do not include Markdown image previews, base64, or extra attachments in the final response.
|
||||
@@ -457,7 +457,7 @@ Input images:
|
||||
- <absolute path> — <role>
|
||||
- <absolute path> — <role>
|
||||
|
||||
Use $imagegen only. Read the row prompt and attach every listed input image. If imagegen returns Bad Request, retry once with the retry prompt and the same input images.
|
||||
Use @imagegen only. Read the row prompt and attach every listed input image. If imagegen returns Bad Request, retry once with the retry prompt and the same input images.
|
||||
|
||||
Before returning, visually check: exact frame count, same pet identity as canonical base, flat chroma background, complete separated unclipped poses, and no detached effects or guide marks. The prompt's transparency and effects rules are mandatory: no detached effects, no wave marks for `waving`, no speed lines or dust for directional running rows, no literal foot-running for the non-directional `running` row, and only attached opaque sprite-like tears/smoke/stars when allowed by the state prompt.
|
||||
|
||||
@@ -504,18 +504,18 @@ For extraction-induced motion popping, do not regenerate imagery first. If the s
|
||||
|
||||
## Rules
|
||||
|
||||
- Keep `$imagegen` as the primary generation layer.
|
||||
- Keep `@imagegen` as the primary generation layer.
|
||||
- For brand/product/company/prospect requests without a concrete avatar description or reference image, run brand discovery before base generation and pass only the compact brief into the run.
|
||||
- Use `$imagegen` as the only visual generation layer. Do not invoke image APIs, image CLIs, local raster generators, or one-off generation scripts from this skill.
|
||||
- Keep reference images attached/visible for `$imagegen` whenever the chosen path supports references.
|
||||
- Use `@imagegen` as the only visual generation layer. Do not invoke image APIs, image CLIs, local raster generators, or one-off generation scripts from this skill.
|
||||
- Keep reference images attached/visible for `@imagegen` whenever the chosen path supports references.
|
||||
- Attach the row's `references/layout-guides/<state>.png` image to every row-strip job as a layout-only guide, and do not accept outputs that copy guide pixels.
|
||||
- Use lightweight visual workers for base generation, row-strip visual generation, and final contact-sheet QA by default; the parent owns manifest updates, deterministic image scripts, packaging, and cleanup.
|
||||
- Generate every normal visual job with `$imagegen`: base plus all row strips that are not explicitly approved `running-left` mirror derivations.
|
||||
- Generate every normal visual job with `@imagegen`: base plus all row strips that are not explicitly approved `running-left` mirror derivations.
|
||||
- Treat only the base job as eligible for prompt-only generation; every row job must attach its listed grounding images.
|
||||
- Generate `running-right` before deciding whether `running-left` can be mirrored.
|
||||
- When `running-left` is mirrored, preserve frame order and timing semantics; derive it through the deterministic script instead of mirroring an entire strip wholesale.
|
||||
- Do not derive or reuse `waiting`, `running`, `failed`, `review`, `jumping`, or `waving` from another state; each has distinct app semantics and must be generated as its own row.
|
||||
- Never substitute locally drawn, tiled, transformed, or code-generated row strips for missing `$imagegen` outputs.
|
||||
- Never substitute locally drawn, tiled, transformed, or code-generated row strips for missing `@imagegen` outputs.
|
||||
- Only mark a visual job complete after its selected output has been copied into the decoded output path.
|
||||
- Do not rely on generated images for exact atlas geometry; use this skill's deterministic image scripts.
|
||||
- Use the chroma key stored in `pet_request.json`; do not force a fixed green screen.
|
||||
|
||||
@@ -565,7 +565,7 @@ def make_jobs(
|
||||
"input_images": reference_inputs,
|
||||
"output_path": "decoded/base.png",
|
||||
"depends_on": [],
|
||||
"generation_skill": "$imagegen",
|
||||
"generation_skill": "@imagegen",
|
||||
"requires_grounded_generation": bool(reference_inputs),
|
||||
"allow_prompt_only_generation": not reference_inputs,
|
||||
}
|
||||
@@ -590,7 +590,7 @@ def make_jobs(
|
||||
"may_derive_from": "running-right",
|
||||
"derivation": "framewise-horizontal-mirror-preserving-order",
|
||||
"requires_explicit_approval": True,
|
||||
"fallback_generation_skill": "$imagegen",
|
||||
"fallback_generation_skill": "@imagegen",
|
||||
}
|
||||
elif state not in NON_DERIVABLE_STATES:
|
||||
derivation_policy["reason"] = "no deterministic derivation is configured for this state"
|
||||
@@ -615,7 +615,7 @@ def make_jobs(
|
||||
],
|
||||
"output_path": f"decoded/{state}.png",
|
||||
"depends_on": depends_on,
|
||||
"generation_skill": "$imagegen",
|
||||
"generation_skill": "@imagegen",
|
||||
"requires_grounded_generation": True,
|
||||
"allow_prompt_only_generation": False,
|
||||
"identity_reference_paths": identity_reference_paths,
|
||||
@@ -782,7 +782,7 @@ def main() -> None:
|
||||
"brand_brief": args.brand_brief,
|
||||
"brand_sources": args.brand_source,
|
||||
"pet_safe_style": PET_SAFE_STYLE,
|
||||
"primary_generation_skill": "$imagegen",
|
||||
"primary_generation_skill": "@imagegen",
|
||||
}
|
||||
if brand_discovery_path:
|
||||
request["brand_discovery_path"] = brand_discovery_path
|
||||
@@ -805,7 +805,7 @@ def main() -> None:
|
||||
"schema_version": 1,
|
||||
"created_at": datetime.now(timezone.utc).isoformat(),
|
||||
"run_dir": str(run_dir),
|
||||
"primary_generation_skill": "$imagegen",
|
||||
"primary_generation_skill": "@imagegen",
|
||||
"jobs": make_jobs(run_dir, copied_refs),
|
||||
}
|
||||
(run_dir / "imagegen-jobs.json").write_text(
|
||||
|
||||
Reference in New Issue
Block a user