ecom-details-image: A Claude Code Skill for AI-Generated E-Commerce Product Images

What ecom-details-image Solves for E-Commerce Sellers

Listing a product on Amazon, Shopify, or a domestic platform like Taobao or Douyin requires multiple image types: a white-background hero shot, lifestyle scenes, detail close-ups, infographic images explaining features, a comparison image, and social media crops. Commissioning a photographer and a graphic designer for all of these is expensive. Generating them manually with an image API means writing a separate, carefully structured prompt for each image type from scratch, with no mechanism to ensure the images look like they belong to the same campaign.

The ecom-details-image skill addresses this by providing 25 pre-built scene templates with complete prompts, a Campaign Style Lock that locks the color palette, tone, fonts, background style, and lighting across all images in a batch, and a conversion-driven diagnostic that reads the product type and decides whether a visual-led, pain-point-led, or emotional-value-led image sequence fits better. The skill works inside Claude Code or Codex using natural language commands, or standalone via its Python script with a direct API call.

Campaign Style Lock and the Conversion-Driven Approach

The Campaign Style Lock is the mechanism the README describes as the skill's primary differentiator. When a multi-image job runs, the skill generates a style lock text block that pins the background color, text color, accent color, warm or cool tone, font system, background style, lighting system, and layout rules for the entire batch. That lock text is copied verbatim to the beginning of every image prompt in the job. The README explicitly lists what the lock prohibits: color palette drift, font mixing, lighting inconsistencies, and layout variation between images.

The conversion-driven diagnostic categorizes each product into one of three image-sequence types: visual-driven (the product sells itself aesthetically), pain-point-driven (the product solves a clear problem that photos can demonstrate), or emotional-value-driven (the product's value is aspirational). The skill generates a different image sequence depending on the diagnosis. This step is described in the README as an automatic process that runs before image prompts are written.

Installing the Skill and Running a First Image Generation

Prerequisites are Claude Code CLI or Codex, Python 3.10 or later, and an API key for an OpenAI-compatible image generation service. Clone the repository:

git clone https://github.com/liangdabiao/ecom-details-image.git
cd ecom-details-image

Create a .env file in the project root with the API configuration:

IMG_BASE_URL=https://api.openai.com/v1
IMG_MODEL=gpt-image-1.5
IMG_API_KEY=your-api-key-here

The skill accepts IMG_BASE_URL, IMG_MODEL, and IMG_API_KEY as the primary variable names, but also reads OPENAI_BASE_URL, OPENAI_API_BASE, OPENAI_IMAGE_MODEL, OPENAI_MODEL, and OPENAI_API_KEY as aliases. Without an API configured, the skill still runs but outputs prompts only and does not call any image generation endpoint.

With Claude Code running in the project directory, describe the request in natural language, for example asking to generate an Amazon detail page set based on a product photo in the data/ directory. For the generate_image.py script directly:

python3 .claude/skills/ecom-details-image/scripts/generate_image.py \
  --prompt-file my-prompt.txt \
  --image data/product.jpg \
  --output-dir generated-images \
  --size 1024x1536 \
  --format png

The script uses Python's standard library only, requiring no pip install step.

The 25 Scene Templates and How They Are Organized

The skill ships 25 JSON template files in .claude/skills/ecom-details-image/references/templates/. Each template covers one type of e-commerce image and is matched by trigger keywords in the natural language request. The templates span the full range of product listing needs: white-background hero shot (01), lifestyle scene (02), flat lay (03), detail close-up (04), poster or banner (05), social media content for Instagram or Xiaohongshu (06), UGC-style buyer photo simulation (07), model display (08), before-and-after comparison (09), packaging and unboxing (10), infographic with product specifications (11), creative concept (12), size chart (13), multi-product combination (14), live-stream scene (15), virtual try-on (16), exploded view (17), ghost mannequin for apparel (18), multi-angle grid (19), editorial magazine style (20), seasonal campaign (21), luxury atmosphere (22), device mockup (23), storefront display (24), and sports campaign (25).

For an Amazon PDP listing, the skill generates 5 main images at 1024x1024 (hero, feature close-up, usage scene, comparison, and a CTA with guarantees) and 9 detail page images at 1024x1536 (opening hook, pain point amplification, mechanism explanation, core benefits infographic, usage steps, scene coverage, comparison selection, trust signals, and FAQ or risk-reversal).

Dual Mode: Prompt Output and Direct Image Generation

The skill runs in two modes. In Prompt mode, it produces a written Visual Brief (target, subject, audience, style), the conversion-driven diagnostic result, the Campaign Style Lock block, the planned image sequence, the final image prompts, and a list of negative constraints. This output can be used with any image generation tool independently of this skill.

In Generate mode, the skill writes each prompt to an individual prompt file and calls generate_image.py for each image, then returns the list of output file paths. The --n parameter on the script controls how many variants to generate per prompt. Output files go to the directory specified by --output-dir, which defaults to generated-images. Generated images are gitignored by default and are not committed to the repository. The .env file and any .env.* variants are also gitignored.

Limitations and What the Skill Cannot Do

The skill's image quality is entirely dependent on the API provider and model chosen. The README notes that different providers support different subsets of the size, quality, and format parameters; using an unsupported combination silently falls back or errors depending on the provider. The --image reference photo parameter (used to pass an existing product photograph to improve product likeness) requires the API server to support image input, which not all providers do.

The skill does not include a model for editing existing images, only generating new ones. There is no built-in review or approval step between prompt generation and image output; the Campaign Style Lock sets visual consistency at the prompt level but cannot guarantee that two images rendered by a generative model will actually look visually consistent at the pixel level. The README also states that marketing claims about product effects in generated images must be supported by real evidence; the skill itself places no enforcement on this.

Compared to Calling the Image API Without a Skill

Calling GPT-Image-2 or a similar API directly requires writing image prompts from scratch for each image type and managing the Campaign Style Lock consistency manually. A developer building a full Amazon PDP listing needs to know which 14 images to generate, what size each should be, how to structure a brief-to-prompt workflow, and how to keep a consistent visual style across all of them. That domain knowledge is encoded in ecom-details-image's 25 templates and its Campaign Style Lock mechanism.

The trade-off is that the skill introduces a dependency on Claude Code or Codex as the execution environment, and the prompt templates may not match every product category or brand aesthetic. A team with a graphics designer who already writes structured image briefs may not benefit from the template layer. For teams who use Claude Code or Codex regularly and want to reduce the time from product photo to complete listing images, the 25 pre-built templates and the Campaign Style Lock address the most common friction points.

Editorial conclusion

E-commerce sellers on Amazon, Shopify, Taobao, or similar platforms who use Claude Code or Codex and need a structured, template-driven approach to generating full product listing image sets will find ecom-details-image reduces the prompt-engineering work significantly. Teams whose primary tool is a standalone image editor (Photoshop, Figma) or a design platform like Canva will not get direct value from this skill. Before running it, set IMG_BASE_URL, IMG_MODEL, and IMG_API_KEY in .env; confirm that your chosen API provider supports the size and format parameters your templates require, since support varies across providers.

Frequently asked questions

Official sources

1. Issues
2. liangdabiao/ecom-details-image on GitHub
3. Project website
4. README