ecommerce-visual-copywriting-skill, an Agent Skill for e-commerce image briefs

A skill that plans before it writes a single headline

The ecommerce-visual-copywriting-skill repository is a SKILL.md agent skill for e-commerce visual work. The project description puts it as AI-powered visual strategy for main images, PDP and A+ pages, copywriting, localization, evidence-aware compliance and image prompts, and it is compatible with Claude, Codex, Cursor and Workbuddy style agents that read a SKILL.md file. The primary language of the repository is Python, mostly for the verification tooling rather than for the skill logic itself.

The README states the aim directly, that it is not about writing another paragraph of advertising copy. The skill first works out why a user would buy, then fixes a visual style and the truthfulness of the product claims, then builds an evidence ledger, and only then outputs per-image instructions covering the picture, the in-image copy, the design notes and the image generation prompt. The workflow diagram makes the order explicit: product material and packaging and qualification documents and reference images go into task routing, then the evidence ledger, then the purchase drivers, then a campaign style lock, then a storyboard, then per-image execution drafts, then a five-dimension quality gate, and out comes something a designer or an image model can execute directly.

That ordering is the product. Most image-generation prompts fail not because the model cannot render but because nobody decided which purchase decision each image is supposed to resolve. This skill makes that decision the first step and holds the output to it, with one buying decision per image.

The evidence ledger and the Feature to Evidence chain

Two mechanisms carry the weight of the whole approach, and both are named explicitly in the README.

The first is the evidence ledger. Every key selling point is tagged as confirmed, supported, pending proof, or prohibited, so a claim that nobody can substantiate is visible as such before any copy is written. The second is the chain from Feature to Advantage to Benefit to Evidence, which exists because parameters on their own do not tell a shopper what the parameter does for them. The chain is the difference between a specification sheet and a reason to buy.

Two more rules support the ledger. Reference Fidelity and negative constraints lock the packaging, the logo, the structure and the specifications to the reference image, so the generated picture is recognisably the product that will be shipped rather than a plausible cousin of it. And the claim grading happens after the ledger, not before, so a stronger-sounding headline cannot outrun the evidence behind it.

The quality gate at the end is described as a hard block with a pass or fail result, and the README is explicit that this replaces an unanchored numeric score such as 80 out of 100. That is a small design decision with a large effect on how the output reads. A score invites the agent to average its way to a number, while a pass or fail forces the question of whether a rule was broken.

Four modes, including one for reviewing what already exists

The skill defines four execution modes, and choosing between them is part of the task routing in the workflow.

Standard mode is for when the direction is unclear, the cost of rework is high, or the user asks to confirm first. In that mode the skill produces the strategy and the storyboard, waits, and only then executes. One-shot delivery is for when the user explicitly asks for everything at once or the input is complete, and the instruction is not to pause mechanically. Review and revision mode applies when there are already main images, a detail page, copy or prompts, and the skill finds problems and makes the minimum necessary changes. Designer handoff mode uses the fixed output structure to produce per-image task cards for someone who is about to start work.

Review mode addresses a failure the README lists explicitly, the case where a user only wants to change an existing detail page and the agent instead rebuilds everything from scratch. The minimum-change rule is the useful part, because a detail page is often a finished asset with live traffic behind it, and rewriting it wholesale discards work that someone else already validated.

The number of images is also not fixed. Five is described as a default, and the README says the count is adjusted to the platform and the product rather than padded to hit five.

The storyboard and the per-image execution card

The output has two layers, a strategy layer and a storyboard layer, and then the per-image cards.

The strategy layer contains the purchase drivers, which the README groups as visual, pain point, parameter, trust and emotion, the top three reasons to buy, the evidence ledger, the Feature to Advantage to Benefit to Evidence chain, the campaign style lock, and a list of missing information, assumptions and risks. Listing the assumptions in the deliverable is a deliberate choice, since a plan that hides its gaps reads as more finished than it is.

The storyboard assigns a role to each image, and the canonical sequence is five slots. KV1 is the hero image, which has to say at a glance what is being sold and why to click. KV2 is the benefit image, which turns the core specification into a user benefit. KV3 is proof, using real evidence to build trust. KV4 is the scene, letting the target user see themselves in it. KV5 is specification or call to action, carrying specifications, bundles, choices or the action itself.

Each per-image card is written to be executed without further interpretation. It lists the visual task, the picture with composition, camera, light and background, the in-image copy, the first visual focal point, the design notes, the generation prompt, the negative prompt or prohibited items, the evidence source, and compliance or platform remarks. The negative prompt is where packaging deformation, a wrong logo, changed specifications, garbled text and abnormal people get ruled out in advance.

Installing the skill with npx skills add or by copying files

The documented install is a single command:

npx skills add feichanggege/ecommerce-visual-copywriting-skill

After that you talk to the agent in the ordinary way. The README's example asks for seven product images plus an A+ visual plan for Amazon US, with each image containing the picture, English in-image copy, design notes, a generation prompt and a negative prompt, and with two explicit constraints: do not ask for confirmation midway, and mark assumptions rather than inventing information. A shorter request is also acceptable, asking for a set of main images and a detail page that can be handed straight to a designer.

There is a manual installation path for people who want to see exactly what is being copied into their agent configuration. On macOS and Linux:

git clone https://github.com/feichanggege/ecommerce-visual-copywriting-skill.git
mkdir -p ~/.codex/skills/ecommerce-visual-copywriting
cp -r ecommerce-visual-copywriting-skill/SKILL.md \
      ecommerce-visual-copywriting-skill/SKILL.en.md \
      ecommerce-visual-copywriting-skill/agents \
      ecommerce-visual-copywriting-skill/references \
      ecommerce-visual-copywriting-skill/examples \
      ~/.codex/skills/ecommerce-visual-copywriting/

The Windows PowerShell equivalent is given separately in the README. The package layout is what the manual path reveals. SKILL.md is the canonical runtime entry point, SKILL.en.md is the English companion, agents/openai.yaml holds ChatGPT UI metadata, and three reference files carry the substance: compliance-rules.md for the evidence and compliance framework, platform-playbooks.md for the multi-platform visual strategy, and output-contracts.md for the designer delivery, review and localization templates.

The refusal list is the most useful part of the skill

The README has a safety boundary section, and it lists what the skill will not do. It will not fabricate test reports, certifications, patents, approval numbers, sales figures, reviews, rankings or user testimonials. It will not write a pending-proof item as an established fact. It will not cross medical, food, health or platform compliance boundaries because a user asked for it to be punchier. It will not launder a prohibited efficacy claim with a disclaimer. It will not treat historical platform experience as a current hard platform rule. And it will not change the product packaging, logo, specifications or structure for visual effect.

The compliance framework in references/compliance-rules.md backs those refusals, and the platform rules are split into two categories on purpose. Long-term stable visual strategy comes from references/platform-playbooks.md, while current image sizes, main image restrictions, prohibited words, qualification requirements and review rules are supposed to be verified against the platform's own latest sources when they are needed, rather than written into the skill as fixed truth.

That distinction is the honest part of the design and also its weak point. A skill can tell an agent to check, but it cannot make the check happen, and a model that has internalised a rule from its training data will happily keep applying it. The verification script is the other guard. Before publishing, run:

python tools/verify-skill.py

The README describes it as a pre-release structure and privacy check, and it also suggests running the official skill validator or packager over SKILL.md frontmatter and the package structure at the same time.

Where the skill stops, and what it produces instead

The clearest limitation is that the output is a plan, not an asset. Every deliverable is a brief: the picture described in words, the copy that goes on it, the design notes, the prompt to feed a model. Rendering is left to a designer or an image model, and the README is careful about the showcase images, saying they illustrate the form of the deliverable and do not represent legal opinions, platform review commitments or commercial performance evidence for the products shown.

The second limitation is coverage. The supported platforms are listed as a table of Chinese marketplaces, Taobao, Tmall, JD, Pinduoduo and Douyin store, against cross-border and direct-to-consumer channels including Amazon listings, A+ and Brand Story, Shopify and DTC product pages, TikTok Shop, Temu, Shopee and Lazada. The visual strategy covers those, and the cross-border localization guidance is about rewriting rather than translating, with market, units, scenario and expression habits considered. What it does not cover is the long tail of marketplaces and the rules that change weekly.

The third limitation is the platform-rule dependency, and it follows directly from the two-category split described earlier. The skill refuses to treat old experience as current policy, which is correct, but it also means the agent can only be as current as the sources it manages to check. For a team that ships across several marketplaces, that verification loop becomes the real work, and the skill saves effort on the strategy side while leaving the compliance side to you.

Editorial conclusion

ecommerce-visual-copywriting-skill suits a small e-commerce team or a seller who works with an AI agent and needs a repeatable brief format for main images, detail pages and Amazon A+ content, especially across several markets. It does not suit anyone who wants finished, rendered product images, because it produces plans and prompts rather than assets, and it does not replace checking current platform rules yourself. Before you rely on it, run python tools/verify-skill.py to confirm the package is intact, read references/compliance-rules.md for the claim boundaries it enforces, and confirm the platform playbooks in references/platform-playbooks.md still match what your marketplaces actually enforce today.

Frequently asked questions

Official sources

1. feichanggege/ecommerce-visual-copywriting-skill on GitHub
2. Issues
3. License: MIT
4. README
5. Releases