How Automatic Prompt/Image Versioning Works in gpt-image-2: A Complete Technical Guide

The gpt-image-2 skill implements deterministic, version-controlled storage for every generated prompt and image by combining URL-friendly slugs, precise timestamps, and mode-aware persistence logic in skills/gpt-image-2/scripts/shared.js.

Automatic prompt/image versioning in the gpt-image-2 skill ensures that every creative iteration is reproducible, searchable, and audit-ready. According to the ConardLi/garden-skills repository, this mechanism is governed by the three runtime modes defined in SKILL.md and implemented through shared utility functions that standardize file naming and directory structures across all operations.

How the Versioning System Works

The skill stores assets in a predictable hierarchy using deterministic naming conventions that eliminate collisions while maintaining human readability.

Default Directory Structure

All artifacts are organized under consistent paths regardless of execution context:

• Prompts: garden-gpt-image-2/prompt/
• Images: garden-gpt-image-2/image/

This structure is enforced by buildDefaultPromptPath() and buildDefaultImagePath() in [shared.js](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/scripts/shared.js), which automatically create missing parent directories using mkdir with { recursive: true } before writing files.

The Slug-and-Timestamp Naming Convention

When users omit explicit filenames, the skill generates unique identifiers through a two-part algorithm:

1. Slug generation: The slugify() function (lines 56–64) normalizes the task description by stripping non-alphanumeric characters, collapsing whitespace to hyphens, and truncating to 48 characters maximum.
2. Timestamp appending: The makeTimestamp() function (lines 67–75) appends the current datetime in YYYYMMDD-HHMMSS format.

The resulting filename follows the pattern: {slug}-{timestamp}.{ext}. For example, a prompt about "A futuristic city skyline" generates futuristic-city-skyline-20260424-153045.md.

Mode-Aware Persistence Logic

Versioning behavior varies according to the active runtime mode detected by scripts/check-mode.js:

• Mode A (Garden): Both savePrompt() and saveImage() are invoked, persisting the complete prompt in .md format and the binary image output.
• Mode B (Host-Native): Only savePrompt() executes; the host agent manages image storage independently.
• Mode C (Advisor): Prompts are saved via savePrompt() but no API call occurs, leaving only the markdown file.

Core Implementation in shared.js

The versioning engine resides in skills/gpt-image-2/scripts/shared.js, which exports five critical utilities:

Function	Purpose	Lines
slugify(text)	Creates URL-safe identifiers from task descriptions	56–64
makeTimestamp()	Generates collision-resistant timestamps	67–75
buildDefaultPromptPath(hint)	Constructs full paths for markdown files	97–101
buildDefaultImagePath(hint)	Constructs full paths for image binaries	78–84
savePrompt(prompt, hint, explicitPath)	Writes prompt content to disk with automatic path generation	97–101

The saveImage() function operates similarly to savePrompt(), utilizing buildDefaultImagePath() to determine the destination for PNG outputs generated by scripts/generate.js and scripts/edit.js.

Runtime Modes and Versioning Behavior

Mode A: Full Garden Persistence

When running in Garden mode, both scripts/generate.js and scripts/edit.js execute the complete persistence pipeline:

node skills/gpt-image-2/scripts/generate.js \
  --prompt "A futuristic city skyline at sunset" \
  --size 1024x1024

This produces:

• Prompt: garden-gpt-image-2/prompt/futuristic-city-skyline-20260424-153045.md
• Image: garden-gpt-image-2/image/futuristic-city-skyline-20260424-153045.png

Mode B: Host-Native Operation

In Host-Native mode, the skill persists only the prompt metadata:

node skills/gpt-image-2/scripts/generate.js \
  --promptfile garden-gpt-image-2/prompt/poster-20260424-153045.md

The user-specified --promptfile flag indicates the host environment manages the actual image generation and storage.

Mode C: Advisor-Only Output

Advisor mode restricts output to prompt engineering without API consumption:

node skills/gpt-image-2/scripts/generate.js \
  --prompt "A cute baby sea otter" \
  --dry-run

Result: Only garden-gpt-image-2/prompt/sea-otter-20260424-153045.md is created; no image file is produced.

Practical Usage Examples

Detect your current runtime mode before executing generation tasks:

# Verify mode detection

node skills/gpt-image-2/scripts/check-mode.js

Execute image editing with automatic versioning:

# Edit existing image (Mode A)

node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png \
  --mask assets/mask.png \
  --prompt "Replace the masked area with a glass vase"

The edit workflow automatically generates versioned output paths using the same slug-timestamp algorithm, ensuring edited images receive unique filenames while maintaining association with their source prompts through directory proximity.

Summary

• Automatic prompt/image versioning relies on slugify() and makeTimestamp() to create collision-free filenames with 48-character slugs and YYYYMMDD-HHMMSS timestamps.
• All prompts save to garden-gpt-image-2/prompt/ and images to garden-gpt-image-2/image/ via buildDefaultPromptPath() and buildDefaultImagePath().
• Three runtime modes (Garden, Host-Native, Advisor) control whether the skill persists prompts only or both prompts and images.
• The shared utilities in shared.js handle recursive directory creation and deterministic path resolution for reproducible asset management.

Frequently Asked Questions

How does gpt-image-2 prevent filename collisions between similar prompts?

The skill combines 48-character truncated slugs derived from the task description with second-precision timestamps (YYYYMMDD-HHMMSS). This dual-key approach ensures unique filenames even when users submit identical prompts within the same minute, as the timestamp captures the exact generation second.

Can I override the automatic naming convention?

Yes. The savePrompt() function accepts an optional explicitPath parameter via the --prompt-output CLI flag. When provided, this path takes precedence over buildDefaultPromptPath(), allowing complete manual control over filename and location while still benefiting from automatic parent directory creation.

What happens to versioned files when running in Advisor mode?

In Mode C (Advisor), the skill executes only the prompt engineering logic without calling the image generation API. Consequently, savePrompt() writes the markdown file to garden-gpt-image-2/prompt/, but saveImage() is never invoked, leaving no binary artifacts in the image directory.

Where is the mode detection logic implemented?

The runtime mode detection resides in skills/gpt-image-2/scripts/check-mode.js, which determines whether the skill operates in Garden (full persistence), Host-Native (prompt-only), or Advisor (prompt-only without API) mode. This detection drives the conditional execution paths in both generate.js and edit.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}