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

> Discover how gpt-image-2's automatic prompt image versioning uses URL-friendly slugs, timestamps, and mode-aware logic for precise, version-controlled storage. Learn the technical details.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: deep-dive
- Published: 2026-08-31

---

**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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/scripts/generate.js) and [`scripts/edit.js`](https://github.com/ConardLi/garden-skills/blob/main/scripts/edit.js).

## Runtime Modes and Versioning Behavior

### Mode A: Full Garden Persistence

When running in Garden mode, both [`scripts/generate.js`](https://github.com/ConardLi/garden-skills/blob/main/scripts/generate.js) and [`scripts/edit.js`](https://github.com/ConardLi/garden-skills/blob/main/scripts/edit.js) execute the complete persistence pipeline:

```bash
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`](https://github.com/ConardLi/garden-skills/blob/main/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:

```bash
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:

```bash
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`](https://github.com/ConardLi/garden-skills/blob/main/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:

```bash

# Verify mode detection

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

```

Execute image editing with automatic versioning:

```bash

# 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/generate.js) and [`edit.js`](https://github.com/ConardLi/garden-skills/blob/main/edit.js).