CommunityImagegithub.com

Consistent Image Variations

Turn one request or one reference image into a set that keeps the same subject. Grid mode paints a 2×2, 3×3, or 4×4 sheet and slices it into files. Sequence mode makes 4 to 16 frames of changing light, angle, place, or story, and both modes ship a checkable package with a manifest.

What is Consistent Image Variations?

A reusable stills skill for matched image sets. It chooses a contact sheet or a short sequence, keeps the subject stable, and delivers a zip with a manifest instead of a pile of unverifiable files.

Works with~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/Chans-gh/AI-Image-Variation/tree/HEAD/skills/image-variations

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Image Variations (Skill 01)

Single entry point. Orchestration is written here; the full text of 12 directions, Prompt templates, Provider compatibility matrix, error codes, and thresholds are not here—they are all read on demand from the frozen baseline to avoid two drifting sources of truth.

  • Business rules: Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md
  • Direction registry: .../references/directions/registry.json
  • Prompt templates: .../references/grid-prompt.md, .../references/sequence-prompt.md
  • Provider compatibility & safety: .../references/provider-compat.md
  • Error codes: .../references/error-registry.json
  • Packaging rules: .../references/packaging.md
  • Contracts: .../contracts/{image-artifact,job-state,delivery-package}.schema.json

The baseline is read-only: the hash manifest is in shared/baseline.manifest.json; shared/check_baseline.py must always pass. To change a specification, first explain the rationale and get confirmation—do not silently "correct" the baseline in the implementation.

1. Five Inviolable Rules

  1. No silent degradation. If capability is insufficient, budget is insufficient, or validation fails, always explicitly return an error code from references/error-registry.json; never "silently switch to a smaller size / lower tier / fewer images" and continue running, nor report a failure as a pass.
  2. Thresholds only from configuration. config/iv.config.json is the sole source (single tile edge warn/hard thresholds, seam pass/risk thresholds, upscale factor, retries and budget). These have not yet been calibrated with real models; provide data before changing them. No magic numbers in code.
  3. Single source of truth. Directions, Prompts, error codes, and contracts are all read from the baseline at runtime; do not copy them into this Skill.
  4. Keys only by reference. Only accept secret://… or env:…; keys, original images, and user text must never appear in logs, manifests, error messages, or ZIP files.
  5. Artifacts must be verifiable. Each delivery includes manifest.json (image-artifact 1.1) and delivery-package.json; every entry in the manifest must actually exist and its hash must match.

2. How to Use

# 1) Preflight: calculate plan only, no model calls, no writes to disk
python scripts/run_task.py --input task.json --preflight-only

# 2) Actual execution (use mock_synthetic to test the full pipeline without keys)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty

# 3) If only some frames fail, retry with the original indices (produces rev2, parent points to rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1

Task description (a JSON file; fields match the product parameters in references/provider-compat.md):

{
  "task_id": "cup_light_001",
  "output_mode": "grid",            // grid | sequence
  "grid_size": 3,                   // required for grid: 2 | 3 | 4
  "direction": "light",             // one of 12 directions, see registry.json
  "input_type": "text_only",        // text_only | image_only | image_plus_text
  "subject": "a light gray ceramic cup",  // subject description, goes into subject anchor
  "reference_path": "img/ref.png",  // required when input includes image; relative to workspace
  "aspect_ratio": "3:4",
  "resolution_tier": "1K",          // 1K | 2K | 4K; default derived from minimum tile edge
  "provider": {"type": "mock_synthetic"},
  "pack_zip": true
}

sequence additionally requires branch (one of 3 branches supported by the direction) and image_count (4–16).

Real Provider:

"provider": {
  "type": "openai_image_compatible",     // or gemini_image_compatible
  "base_url": "https://api.example.com/v1",
  "model_id": "gpt-image-1",
  "api_key_secret_ref": "secret://IMAGE_API_KEY",
  "capability": { "...": "see §1 capability declaration in provider-compat.md" }
}

If capability is absent, it is treated as non-conforming and reports MODEL_CAPABILITY_UNSUPPORTED—it is a "minimum requirement list" that cannot be silently filled by default values. If the built-in adapter is not injected, it reports BUILTIN_UNAVAILABLE and does not automatically switch to an external network.

3. Flow (Branch Rules)

Parse input → Preflight (capability/size ratio/tier/count/budget)
  ├─ Fail → Report error code, end (no model call, no write to disk)
  └─ Pass ─┬─ Grid: Generate board in one shot → Validate (N×N / seamless / tileable / ratio) → Limited full-board retry
           │        → Normalize → Row-major tile cropping → Check each tile edge (ok / risk / too_low)
           └─ Sequence: First generate N frame plan (frame count, per-frame change points, preserved items, Prompts)
                    → Generate frames one by one (frame 1 as anchor; frames 2–N always reference frame 1; if original image exists, every frame includes it)
                    → If a single frame fails, keep its slot and continue; if frame 1 fails, immediately SEQUENCE_ANCHOR_FAILED
                    → Near-duplicate detection (after retries exhausted, keep slot and mark it)
 → Write to disk (manifest + delivery-package + optional ZIP) → Return JSON result

Key decisions:

SituationHandling
grid_size not 2/3/4, sequence not in 4–16INVALID_MODE_OR_COUNT
Single tile edge below hard thresholdTILE_RESOLUTION_TOO_LOW, no delivery package
Single tile edge below warn thresholdDeliver but record TILE_RESOLUTION_RISK warning (tile_edge_ok=false)
Seam < risk thresholdGRID_VALIDATION_FAILED, retry full board; do not output cropped tiles
Seam between risk–passDeliver and record GRID_SEAM_RISK
Board N×N structure/ratio not metGRID_VALIDATION_FAILED
Frame 1 failsSEQUENCE_ANCHOR_FAILED, stop consuming budget
Frame i failsKeep the original index slot, continue with subsequent frames; final partial_failed
Budget about to be exceededBUDGET_EXCEEDED (may include split suggestions, but do not split automatically)

4. Artifacts

workspace/iv_<task_id>_<revision>/
├── manifest.json            # image-artifact 1.1 (style/size/seam/execution/warnings/errors)
├── delivery-package.json    # Package manifest (sha256 per file)
├── board.png                # Only for Grid: kind=board, index=0
└── images/NN.png            # Grid=cropped tiles (row-major); Sequence=frames (index does not shift forward)

In the same directory, iv_<task_id>_<revision>.zip is the optional packaging artifact. The ZIP does not contain delivery-package.json itself; the archive hash is written back into delivery-package.json.

Partial failure: only actually existing images are recorded (failed frames are not in images[]); failure information is in errors[].asset_id + validation.failed_indices; status=partial_failed. A retry produces a new revision (parent_artifact_revision points to the previous version), and already successful frames remain byte-identical.

5. Boundaries

  • Only image variations. Copywriting, platform publishing, cover layout belong to Skill 02 (image-content-publishing); this Skill does not cross that boundary.
  • If the user explicitly requests multiple directions, pick only one and explain why, or report MULTIPLE_DIRECTIONS; do not mix.
  • Do not handle borderline requests like "style transfer to someone else's work"; for content involving real people/brands, follow the safety requirements in provider-compat.md §4.
  • Artifacts from the self-test mock_synthetic are always marked provider_type=mock_synthetic and must not be delivered externally.

6. Development and Validation

.venv/bin/python skills/image-variations/tests/run_all.py     # 9 suites (including baseline 24/24 and contracts 48/48)
.venv/bin/python shared/check_baseline.py                     # Baseline read-only validation

Evidence and known deviations are recorded in docs/PHASE_EVIDENCE.md.

Related Skills