---
name: packshot
description: >-
  Generate commercial product packshots, clean ecommerce product images, ghost-mannequin shots, top-down flat-lays, folded/styled product shots, 2K vs 4K benchmarks, and post-ready comparison images from reference photos. Use when the user asks to turn product or wardrobe photos into polished packshots with Gemini Nano Banana Pro.
---

# Packshot

Turn rough product or wardrobe reference photos into clean commercial packshots.

This skill uses Gemini Nano Banana Pro through the Google GenAI Python SDK. The scripts read a Gemini API key from macOS Keychain service `gemini-api-key`, or from `GEMINI_API_KEY`.

## What it can generate

- Single packshot at `1K`, `2K`, or `4K`
- Ghost mannequin packshot
- Top-down flat-lay packshot
- Folded/styled product shot
- 2K vs 4K benchmark sheet
- Staging variant comparison sheet
- LinkedIn/social landscape layout with original plus generated variants

## Requirements

- macOS or Linux with `uv` installed
- Gemini API key in one of:
  - macOS Keychain service `gemini-api-key`
  - environment variable `GEMINI_API_KEY`
- Product reference images in `.png`, `.jpg`, `.jpeg`, `.webp`, `.heic`, or `.heif`

Store a Gemini key in Keychain on macOS:

```bash
security add-generic-password -a "$USER" -s gemini-api-key -w "YOUR_GEMINI_API_KEY" -U
```

## Folder shape

Run from a project root that contains a `brands/` folder:

```text
brands/my-brand/
  brand-identity/
    visual-guidelines.md
  packshots/
    red-jacket-fit/
      product-references/
        front.jpg
      packshot-spec.json
```

## Create a packshot spec

Create `brands/[brand]/packshots/[output-name]/packshot-spec.json`:

```json
{
  "output_name": "red-jacket-fit",
  "brand": "my-brand",
  "product_description": "red jacket outfit with white t-shirt, black jeans, and white sneakers",
  "aspect_ratio": "3:4",
  "image_size": "2K",
  "product_images": [
    "brands/my-brand/packshots/red-jacket-fit/product-references/front.jpg"
  ],
  "prompt": "Produce a clean, professional top-down flat-lay packshot, oriented with surgical precision for e-commerce.\n\nProduct Typography and Alignment Syntax:\n- Describe visible logos, patches, labels, and exact text here.\n\n--- Physical Characteristics ---\nDescribe the product structure, materials, hardware, color, seams, silhouette, texture, and visible details.\n\nMaterial & Identity Fidelity: Every aspect of the item, its morphology, dimensions, material weight, color saturation, and surface pattern, must be a faithful match with the provided source image. Any graphics, hallmarks, or text must be replicated with extreme precision in font, spacing, and positional coordinates. Do not invent hidden garments or details that are not visible in the reference.\n\nIllumination Profile: Primary lighting is provided by a high-output, evenly diffused softbox array at a 5600k daylight temperature, tuned to lift shadows without losing depth. The environment should use a neutral #f9f9f9 light source for a consistent clinical grey backdrop without gradients.\n\nRender Specs: High-resolution commercial product master. Capture individual fibers, stitch lines, fabric texture, hardware, wrinkles, seams, and edge detail with optical clarity.\n\nStrict Negative Constraints: No creative interpretation of the original product. Do not render studio hardware, light stands, or power cords. Exclude all human elements, including faces, hands, skin, bodies, and mannequins. No props beyond the visible product items, no dust, and no digital artifacts."
}
```

## Analyze reference images before writing the prompt

When creating a spec, inspect the reference images and write the prompt from the actual visible product. Use this internal analysis structure:

```text
Act as a specialist in commercial product imaging. You have been provided with reference images containing [product description]. Conduct a deep visual audit of the item only.

Choose the best staging archetype:
1. Produce a high-end commercial ghost-mannequin packshot, showing the item in a three-dimensional, hollow-body floating state.
2. Produce a clean, professional top-down flat-lay packshot, oriented with surgical precision for e-commerce.
3. Produce a stylized streetwear-inspired folded packshot, emphasizing the item's texture and silhouette in a relaxed studio setting.

Extract visible text, labels, patches, logos, and typography exactly when legible. If text is not legible, say that clearly and preserve shapes/colors instead of inventing lettering.

Describe physical properties: materials, weight, color, seams, hardware, cut, texture, pattern, and silhouette. Do not reference the background, environment, or people.
```

## Generate one packshot

```bash
uv run skills/references/generate-packshot.py brands/my-brand/packshots/red-jacket-fit
```

Choose resolution:

```bash
uv run skills/references/generate-packshot.py brands/my-brand/packshots/red-jacket-fit --size 4K --tag 4k
```

Useful options:

```text
--size 1K|2K|4K     Output resolution. Default comes from packshot-spec.json, falling back to 2K.
--tag label         Adds a tag to the output filename, for example _4k_v1.png.
--dry-run           Validate inputs without calling Gemini.
--json              Print machine-readable output.
```

## Generate staging variants

Generate ghost, flat-lay, and folded/styled versions:

```bash
uv run skills/references/generate-packshot-variants.py brands/my-brand/packshots/red-jacket-fit
```

Choose only some variants:

```bash
uv run skills/references/generate-packshot-variants.py brands/my-brand/packshots/red-jacket-fit --variants ghost,folded
```

Choose resolution:

```bash
uv run skills/references/generate-packshot-variants.py brands/my-brand/packshots/red-jacket-fit --size 4K
```

Valid variants:

```text
ghost, flatlay, folded
```

## Benchmark 2K vs 4K

```bash
uv run skills/references/benchmark-packshot-size.py brands/my-brand/packshots/red-jacket-fit
```

This creates:

```text
red-jacket-fit_2k_v1.png
red-jacket-fit_4k_v1.png
red-jacket-fit_2k-vs-4k_v1.png
size-benchmark.json
```

## Create a LinkedIn/social layout

```bash
uv run skills/references/create-linkedin-packshot-layout.py \
  --original brands/my-brand/packshots/red-jacket-fit/product-references/front.jpg \
  --main brands/my-brand/packshots/red-jacket-fit/red-jacket-fit_4k_v1.png \
  --top brands/my-brand/packshots/red-jacket-fit/red-jacket-fit_ghost_4k_v1.png \
  --bottom brands/my-brand/packshots/red-jacket-fit/red-jacket-fit_folded_4k_v1.png \
  --out brands/my-brand/packshots/red-jacket-fit/red-jacket-fit_linkedin-landscape.png \
  --main-label "4K flat-lay" --main-score "9/11" \
  --top-label "4K ghost" --top-score "8/11" \
  --bottom-label "4K folded" --bottom-score "8.5/11"
```

Layout:

- left third: original image
- middle third: best generated image
- right third: two generated variants stacked

## Output behavior

All generation scripts auto-increment versions and never overwrite previous images:

```text
red-jacket-fit_v1.png
red-jacket-fit_v2.png
red-jacket-fit_4k_v1.png
red-jacket-fit_flatlay_2k_v1.png
```

## Notes

- More reference angles improve fidelity. One image works, three to five images are better.
- For text or logos, add close-up references.
- 4K is visibly sharper but costs more and takes longer.
- 2K is good for fast iteration and social posts.
- 2K vs 4K benchmarks are separate generations, so some differences are model variance rather than pure resolution.