liangdabiao/ecom-details-image: an ecommerce image Skill for Claude Code and Codex

The gap this fills between a product photo and a finished listing

Most ecommerce teams do not lack image models. They lack a repeatable way to go from one product photo to a coherent set of assets: a main image that reads at thumbnail size, detail-page panels that explain the product, and social crops that do not look like a different brand. The README frames the project as a Skill for Claude Code, Codex and OpenClaw, which means the interaction happens in natural language inside an agent session rather than through a web form. You point at a file such as data/NEW002.jpg, describe the need, and the skill either returns an executable visual brief plus prompts, or calls an image API and writes files into generated-images. The intended user is an operator who already lives in a coding agent: a solo seller, a small agency, or an in-house designer who would rather script a batch than click through a design tool. The 25 templates are the substance here. They cover white-background hero shots, lifestyle scenes, flat lays, macro details, posters, UGC-style photos, model shots, before-and-after comparisons, packaging, infographics, size charts, multi-product groupings, livestream scenes, virtual try-on, exploded views, ghost mannequins, multi-angle grids, magazine editorial, seasonal campaigns, luxury atmospherics, device mockups, storefront displays and sports campaigns. That list is the real product; the Python script is plumbing.

Campaign Style Lock and the diagnosis step behind the image sequence

Two mechanisms separate this from a prompt pack. The first is Campaign Style Lock, which the README describes as automatically locking palette, warm and cool tone, typography, background, lighting and layout across multiple images so a set stays visually consistent. That is a real problem in practice: generate fourteen images from fourteen independent prompts and the whites drift, the shadows point different ways, and the detail page looks assembled rather than designed. Locking those attributes is an attempt to fix it at the prompt layer rather than in post. The second is conversion-driver diagnosis. The skill classifies a request as visually driven, pain-point driven or emotional-value driven, then generates an image sequence suited to that classification. The Amazon PDP example makes the output concrete: five main images at 1024x1024 and nine detail images at 1024x1536, each with a stated job. H1 carries the headline claim, H2 is the material close-up, H3 matches a use scene, H4 contrasts the ordinary option with the upgraded one, H5 handles offer, shipping and call to action. The detail sequence runs from who the product is for, through pain amplification, mechanism explanation, benefits, steps, scenarios, comparison, trust signals, and finally FAQ with risk reversal. Whether the diagnosis is accurate is not something the repository documents, and the classification is worth checking against your own category before trusting the sequence.

Installing the skill and generating your first image set

The prerequisites are an installed and logged-in Claude Code CLI or equivalent, Python 3.10 or later, and an OpenAI-compatible image API if you want the skill to produce files rather than prompts. Cloning is the first step.

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

Next, create a .env file in the project root. The README documents three variables, and the repository's .env.example points at a third-party endpoint with gpt-image-2 as the model, so the defaults are not OpenAI's own service. The README also lists environment variable aliases: OPENAI_BASE_URL, OPENAI_API_BASE, OPENAI_IMAGE_MODEL, OPENAI_MODEL and OPENAI_API_KEY.

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

With that in place, start Claude Code and describe the job in plain language. The README's first example is a white men's shirt and an Amazon detail page set.

基于 data/NEW002.jpg 这款男士白衬衫，生成 Amazon 详情页全套图片

The skill then produces the five main images and nine detail images described above. If you would rather bypass the agent entirely, the generation script takes a prompt directly, and this is the fastest way to confirm that your API credentials work before running a full set.

python3 .claude/skills/ecom-details-image/scripts/generate_image.py \
  --prompt "clean product hero image, white background, studio lighting" \
  --size 1024x1024

For a real product run, pass a prompt file and a reference photo. The --image flag is what nudges the generated product toward the actual item rather than a generic stand-in, and --output-dir keeps a batch together.

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

Other documented flags are --quality with low, medium or high, --n for the number of images, and --env-file to point at a specific configuration file instead of letting the script search upward for one.

Where the skill breaks down: reference drift, cost and the wrong-fit cases

The honest limitation is that this is a prompt-and-API wrapper, not a consistency engine. Campaign Style Lock works by describing the same palette, lighting and layout in every prompt. It cannot guarantee that a model honours those instructions across fourteen separate calls, and nothing in the repository documents a verification pass that checks whether the outputs actually match. If the generated shirt has a slightly different collar in H2 than in H1, the skill will not catch it. Reference images reduce that risk but do not eliminate it, and the README does not state how strongly the --image flag constrains the output. Cost is the second constraint. A fourteen-image PDP set means fourteen API calls, and the README documents no batching, retry or caching behaviour, so a failed call in the middle of a run is something you handle yourself. Third, this is the wrong tool if you need deterministic output. Product photography for a regulated category, or a catalogue where every image must match a brand guideline to the pixel, needs a human retoucher or a template-based renderer, not a generative model with a style hint. Finally, the skill assumes you are comfortable in a terminal and inside an agent session. There is no web interface, no queue, and no review screen. It is a command-line workflow wearing a natural-language coat.

How this differs from running a general image prompt library

The closest alternative is the open source project the README credits for its prompt templates, buluslan/gpt-image2-ecommerce, along with coolqoo/1click-ecom-detailpage, which the README cites as the source of inspiration and preliminary work. The practical difference is packaging and workflow. A prompt library gives you text you paste into a chat window or an API call yourself; you own the sequencing, the file naming, and the consistency problem. This project wraps the same kind of prompts in a skill definition plus a zero-dependency Python script, so the agent can pick a template, assemble the sequence, and write files to disk in one pass. That matters if you generate sets repeatedly, because the sequence logic and the output structure are encoded rather than remembered. It matters less if you generate one image occasionally, where a plain prompt library is simpler and has no .env to configure. The other difference is the emphasis on conversion structure. The H1 through H5 and D1 through D9 layout is a marketing argument baked into the template order, not just a set of visual styles. If you disagree with that argument, you are editing JSON templates rather than picking different prompts.

Maintenance, licence and what a fork actually costs you

The repository is not archived, and the last push was on 2026-05-15. That is roughly four months before today, so it is not abandoned, but it is also not moving quickly, and the README does not describe a release process or a versioning scheme. No releases were retrieved. The licence is not stated anywhere in the repository, which is the single biggest adoption risk here: without a licence file or a stated identifier, you do not have clear permission to redistribute or embed the skill in a commercial product, and the templates are partly derived from credited third-party projects whose own terms you would need to check. Treat that as a question for the author before you build a business process on top of it. Upgrade cost is low in the ordinary case because there is no package to install and no dependency tree to resolve; the script uses only the Python standard library, so a git pull is the upgrade. The risk sits in the templates. If you edit the 25 JSON files to match your brand, a future pull will conflict with your changes, and the README gives no guidance on extending templates in a separate directory. Copy the templates you use into your own repository rather than editing them in place.

Editorial conclusion

Adopt it if you already work inside Claude Code or Codex and want a repeatable brief-to-prompt pipeline for ecommerce visuals, with the option to call an image API directly. Skip it if you need a standalone web app, a hosted service, or a documented licence and release history. Before committing, open .claude/skills/ecom-details-image/SKILL.md and one of the 25 template JSON files to check that the prompt structure matches your catalogue, and confirm the licence with the author, because the repository does not state one.

Frequently asked questions

Official sources

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