DEV Community: jingqiu jia

Amazon Listing & Ads Skill Suite: From SKU Evidence to Paused Ad Drafts

jingqiu jia — Tue, 21 Jul 2026 10:31:26 +0000

Canonical bilingual article: https://www.jiajingqiu.com/amazon-listing-ads-skill-suite/

Amazon listing and advertising work usually breaks in one of two places: content is drafted before the SKU evidence is complete, or an advertising “plan” quietly becomes a live account change before anyone has reviewed it.

I rebuilt four working packages into one modular skill suite that keeps those boundaries explicit. It takes a product from evidence collection to listing copy, paused campaign drafts, and report analysis—without inventing product claims and without writing to an Amazon Ads account.

Six focused skills

Amazon Listing Collector — captures SKU facts, source provenance, competitor structure, and missing-evidence flags.
Amazon Review Analysis — separates verified customer language, recurring objections, use cases, and unresolved risks.
Amazon Keyword Library Builder — consolidates and classifies search language without prematurely assigning ad match types.
Amazon Listing Generator — turns evidence into compliant title, bullets, description, and backend-search-term drafts.
Amazon FAD Initialization — owns campaign structure, match type, bids, budgets, and Amazon Bulk draft generation.
Amazon Ad Report Analyzer — reads one supported Sponsored Products or Sponsored Brands CSV, recomputes performance metrics, and produces reviewable action candidates.

The root skill routes work to the correct module, so collection, content generation, campaign planning, and performance analysis stay separate.

The operating sequence

The workflow is intentionally staged:

SKU evidence → review evidence → keyword library → listing draft → paused ad draft → report analysis

Each stage produces a structured artifact that the next stage can inspect. If a product claim has no source, it remains a gap. If a report type is ambiguous, analysis stops instead of guessing. If a recommendation could change spend, it stays pending human review.

Safety contract

The suite is designed for production preparation, not unattended account mutation:

Every stateful Amazon Bulk row is generated as paused.
Positive keyword match types are assigned only in the FAD layer; upstream research skills emit neutral ad candidates.
Campaign structure, match type, bid, and budget decisions have one clear owner.
The analyzer recalculates CTR, CPC, CVR, ACOS, and ROAS from raw fields rather than trusting spreadsheet formulas.
Zero-sales rows report ACOS as NA, not an artificial zero.
Analysis outputs are marked pending_human_review.
There are no Amazon credentials, network writes, account mutations, or automatic Bulk uploads in the public package.

Policy-sensitive rules are kept in dated references. For example, Amazon announced US listing-title and item-highlight changes taking effect on July 27, 2026; the suite treats that as a dated marketplace constraint rather than a timeless copywriting rule.

Worked food-storage example

A checked demonstration for a food-storage-container SKU produces a 51-row paused Bulk draft across six planned campaigns. Its configuration uses a USD 30 daily ceiling, with USD 27 allocated and USD 3 held in reserve. The readiness gate is 66/100, so the output remains a draft for review.

Those numbers describe the planning artifact. They are not GMV, CTR, conversion, or performance claims.

What is public

The bilingual methodology, module boundaries, safety rules, and worked-example interpretation are public on my portfolio. The implementation page and downloadable ZIP packages are access-controlled, while the GitHub source repository remains private.

Read the full Chinese/English case study:

https://www.jiajingqiu.com/amazon-listing-ads-skill-suite/

中文说明

这套技能不是“一键开广告”，而是把商品证据、评论洞察、关键词、Listing 文案、广告草稿和投放报表拆成六个职责清楚的模块。所有广告草稿默认暂停，任何涉及预算、竞价、否词或账户修改的动作都必须经过人工复核。公开案例中的预算和行数只是已验证的规划产物，不代表真实投放业绩。

I am open to technical review, research collaboration, and implementation work around evidence-grounded commerce AI systems.

A Storyboard Is Not a Production System: Building a SKU-Level Brand Film Skill

jingqiu jia — Fri, 10 Jul 2026 07:56:47 +0000

AI image models are good at producing attractive product shots. That does not mean those shots can become one continuous brand film.

The recurring failures are structural:

the SKU changes between shots;
the person, wardrobe, location, or light resets;
the product performs an action that was never verified;
a six-panel board is treated as one video keyframe;
visual review happens after delivery instead of acting as a release gate.

I rebuilt my Brand Film Product Skill around a stricter contract between evidence, direction, generation, and review.

1. Separate Brand Evidence from Product Truth

Brand PDFs, websites, product pages, briefs, and permitted brand-video material become a traceable Brand Signal Pack. The final SKU remains controlled by a separately approved Product Anchor and product function lock.

Brand references can influence palette, material language, culture, rhythm, scene logic, and camera function. They cannot silently replace the real product.

2. Direct the Product Relation, Not the Category Label

A general system cannot maintain a special shot template for every product. The runtime instead compiles a category-neutral Product Relation Profile:

observable start state;
required setup;
verified action;
hand, body, surface, fixture, container, or spatial contact;
supported result;
observable end state;
human-presence policy.

This relation controls what may happen on screen. The product name does not select a canned storyboard.

3. Make Continuity and Visual Variety Coexist

The director layer creates six story changes across 18 shots: context, preparation, relation, function, meaning, and memory.

Each shot receives a scene action, shot function, lens, camera height, subject angle, focus behavior, foreground layer, movement, transition, product role, and continuity lock.

Continuity preserves identity, product state, geography, light direction, prop count, movement direction, and contact physics. It does not mean repeating the same medium shot.

4. Generate Three Boards, Then Derive Video Inputs Locally

The image model is called exactly three times. Each call creates one 12:5 storyboard canvas containing six 16:9 panels.

The final board is normalized to 1920x800, with a centered 1920x720 content region. Local processing derives six 640x360 shot frames from every board.

This keeps the user delivery compact while giving the video model a valid per-shot keyframe. It also enforces a downstream image aspect-ratio range of 0.4-2.5 for Seedance-compatible handoff.

5. Treat Visual QA as a Release Gate

Finalization binds the current board hashes to eight review dimensions:

SKU fidelity;
human identity or no-person policy;
action physics;
lighting and shadow;
material texture;
composition diversity;
continuity;
AI artifacts.

A failed or pending review cannot create the final five-file delivery.

Current Verification

56 unit tests;
18 continuous shots for both 60-second and 90-second modes;
three board-level image calls;
five files in the user delivery;
one complete mock package and one valid blocked fixture.

The complete implementation note is available at the canonical article.

The code, tests, mock package, and Chinese technical summary are available in the public GitHub repository.

Multimodal Agent Skills: From Predictability to Production Workflows

jingqiu jia — Fri, 03 Jul 2026 04:04:02 +0000

Author: Jia Jingqiu - English web edition: 2026-07-01
Original canonical version: https://www.jiajingqiu.com/agent-skills-multimodal/

Abstract

Multimodal agents are moving from "can call tools" toward "can execute complex workflows reliably." In production, the bottleneck is often not model capability but skill design: when a skill should trigger, how much context it should load, which steps it should follow, how it should choose branches, how it should avoid stale instructions, and how success should be evaluated. Inspired by Matt Pocock's framework for writing great agent skills, this paper proposes a multimodal multi-skill architecture for commerce workflows. Instead of a single large skill, a production system should compose small, inspectable skills for product truth, evidence gating, routing, keyframes, generation prompts, video QA, publication acceptance and failure memory. The goal is not more instructions. The goal is a more predictable process.

1. Thesis: skills are instruments for predictability

A skill is not valuable because it makes an agent sound smarter. A skill is valuable when it turns a repeated task into a more predictable process. A brainstorming skill may produce different ideas each time, but it should reliably understand the goal, generate candidates, filter them and suggest next actions. In the same way, a multimodal production skill should reliably protect product facts, inspect evidence, choose routes and reject weak outputs.

This distinction matters because multimodal output can be visually convincing while commercially wrong. A video can look polished while the package drifts. A product image can look premium while the logo, material or scale is wrong. A report can read fluently while it never checks the screenshots. Skill design is the layer that makes the agent slow down, inspect the right evidence and leave an auditable trail.

The first principle of multimodal skill systems is predictability: every skill should stabilize one process, not promise one magical output.

2. Why multimodal work needs many skills

A commerce video task is not one task. It is a chain of smaller decisions across text, image, video, audio, product pages, platform rules and business goals. If everything is placed inside one giant skill, the agent sees too many future goals at once and often rushes to the final artifact.

Stage	Input	Output	Main Risk
Product truth	Links, photos, titles, specs, reviews	Product Truth Card	Facts get polluted by style words
Evidence gate	Images, screenshots, listings, historic assets	Ready / needs evidence / blocked	The system generates before evidence is sufficient
Intent routing	Raw user text, target platform, available assets	Task type, platform, route	TikTok, Amazon and site-hero standards get mixed
Keyframes	Product Truth Card, platform goal	Storyboard and keyframe prompts	The scene looks good but proves nothing
Multimodal QA	Candidate image or video	Accept, repair or reject	The review rewards aesthetics instead of truth
Publication and memory	Final asset, channel page, QA result	Acceptance record and next-time rule	Successful and failed decisions are not reusable

3. A taxonomy of multimodal skills

01 Product Truth Skill

Extract product name, category, material, shape, logo, packaging, visual anchors, supported claims and unknowns. It should not write creative copy.

02 Evidence Gate Skill

Decide whether the task is ready, needs more evidence or must be blocked before generation. This is the safety valve before expensive output.

03 Router Skill

Convert raw user text into structured intent: modality, product category, platform, task stage and risk. Style requests belong in generation payload, not retrieval intent.

04 Storyboard and Keyframe Skill

Turn product truth into scenes, actions, product anchors, on-screen text, voiceover and QA risks. Video should often be keyframe-first.

05 Generation Prompt Skill

Use approved facts, references and scene plans to build model-specific prompt contracts. It should execute, not invent missing facts.

06 Multimodal QA Skill

Inspect product shape, material, hand-object contact, action logic, temporal fidelity, audio-visual alignment and commercial readability.

07 Publication Acceptance Skill

Verify file existence, format, visible page, platform fit, product truth and acceptance evidence. "Generated" is not the same as "usable."

08 Failure Memory Skill

Store failure labels, evidence, repair actions and next-time rules so future routing can avoid repeated mistakes.

4. Multi-skill architecture

A production-grade multimodal agent should not begin with a universal skill. It should begin with a small router and a set of specialized skills. The router preserves the user's original request, extracts structured intent and points to the next skill.

raw_user_text
  -> Router Skill
  -> Product Truth Skill
  -> Evidence Gate Skill
  -> Platform / Task Route
  -> Storyboard or Keyframe Skill
  -> Generation Prompt Skill
  -> Multimodal QA Skill
  -> Repair or Publish
  -> Failure Memory Skill

The boundary matters. The router should not write prompts. The product-truth skill should not do style expansion. The evidence gate can stop generation. The QA skill must label failures and propose repair actions. The memory skill must produce next-time rules, not vague retrospectives.

5. Invocation design: model invoked or user invoked

Model-invoked skills reduce user effort but increase context load because their descriptions sit in the agent's environment. User-invoked skills keep the agent leaner but increase cognitive load on the operator. A multimodal system should choose based on risk and frequency.

Skill Type	Recommended Trigger	Reason
Evidence gate	Model-invoked	High-risk pre-generation check.
Product truth	Model-invoked or router-called	Most commerce tasks need it.
Router	User-invoked	The user remembers one entry point.
Storyboard / keyframe	Router-called	Not every task needs video planning.
Generation prompt	User-invoked or explicit route	Avoid accidental generation before evidence is ready.
QA and acceptance	Model-invoked before publication	Risk control should be hard to skip.
Failure memory	Automatic at the end	Each completion or failure should produce learning data.

6. Product Truth Card and clean skill routing

The clean route is not a long prompt that mixes facts, style and task intent together. It is a data boundary: preserve the user's original request, extract a narrow retrieval intent, freeze product facts, pass style into generation only, then verify the candidate output with multimodal QA.

raw_user_text
  -> retrieval_intent
  -> product_truth_card
  -> generation_payload
  -> multimodal_verification

Layer	Used For	Must Not Do
raw_user_text	Evidence, replay and debugging. Keep the original request intact.	Do not feed it directly into skill retrieval.
retrieval_intent	Skill selection only: task type, platform, input asset, target action and product-truth status.	Do not include style words such as cinematic, premium, dark, streetwear or low-AI-feel.
product_truth_card	Visible facts, unknowns, claim boundaries, forbidden mutations and identity references.	Do not write marketing copy or invent missing selling points.
generation_payload	Scene, camera, lighting, subtitle, voiceover, CTA and style instructions.	Do not override the Product Truth Card.
multimodal_verification	Accept, repair or reject based on product identity, action logic, realism and commercial readability.	Do not score beauty alone.

The hard gate is simple: if a Product Truth Card does not exist, the system should not enter storyboard, script or video-prompt generation. "Do not change the product" is too weak as a prompt sentence; the product facts need to be a locked state that later skills cannot override.

Generation priority

Product geometry first, then color, label, logo, packaging, visible accessories, known claims, platform format, scene logic and finally creative style.

Model route

Use image-to-video or reference-to-video when product appearance matters. Pure text-to-video is better for concept films than SKU-level product fidelity.

TikTok branch

Discovery commerce: hook attention first, then prove the product action clearly enough for a viewer who was not searching for it.

Amazon branch

Intent commerce: the buyer is already comparing. Prioritize clarity, trust, feature proof, claim safety and doubt reduction.

7. Information design: keep SKILL.md small

The main skill file should be a control surface, not a knowledge dump. Put the trigger, core steps and completion criteria in SKILL.md . Move branch-specific material into references, templates and examples that the agent opens only when needed.

multimodal-commerce-skills/
  router/SKILL.md
  product-truth/SKILL.md
  product-truth/templates/product_truth_card.json
  evidence-gate/SKILL.md
  evidence-gate/references/evidence_requirements.md
  storyboard-keyframe/SKILL.md
  storyboard-keyframe/templates/storyboard_table.md
  generation-prompt/SKILL.md
  generation-prompt/templates/prompt_contract.json
  multimodal-qa/SKILL.md
  multimodal-qa/references/failure_labels.md
  publish-acceptance/SKILL.md
  failure-memory/SKILL.md

This is progressive disclosure for agents. Most tasks should load only the steps. Platform rules, failure taxonomies, templates and examples should live behind context pointers.

8. Leading words for multimodal agents

A leading word compresses a behavior into a short reusable phrase. The phrase should appear in the skill, the templates, the QA labels and the agent's own operational language. This makes the desired behavior easier to repeat.

Leading Word	Meaning	Use
product truth	The product facts cannot drift.	All commerce generation.
evidence-first	Inspect source evidence before generation.	Listings, reviews, RAG and QA.
visual anchor	Shape, logo, color, material and usage action must be preserved.	Image and video fidelity.
keyframe-first	Plan inspectable frames before video generation.	Complex actions and product demos.
commercial readability	The buyer can understand the value without internal context.	Landing pages and video QA.
next-time rule	A failure becomes a future routing rule.	Failure memory.

9. Pruning: remove sediment and no-ops

Multimodal skills often grow by sediment. Every failed generation adds another warning. Every platform adds another exception. Every bad output adds another style phrase. Eventually the skill becomes long, duplicated and stale.

Use deletion tests. If removing a paragraph does not change the agent's behavior, it is probably a no-op. If a rule applies only to one branch, move it to that branch. If a concept appears in multiple files, choose one source of truth. If a style request is repeated as prose, turn it into a structured field.

Each rule must change behavior.
Each concept should have one source of truth.
Branch-specific references should live outside the main skill file.
Style phrases should become parameters or leading words.
Failure notes should first go into failure memory, then be promoted only if they repeatedly matter.

10. Evaluation framework

A multi-skill system needs evaluation at four layers: invocation, process, output and memory.

Invocation

Did the right skill fire at the right time? Did model-invoked skills increase context load too much? Can the user remember the entry points?

Process

Did the agent complete every step, do enough inspection and choose the correct branch before moving forward?

Output

Did the asset preserve product truth, fit the platform, align with evidence and reduce repair time?

Memory

Are repeated failures decreasing? Are next-time rules retrieved and used in future routing decisions?

11. Minimal router template

The router should be small. It should preserve raw user text, extract retrieval intent and route the work without absorbing every downstream instruction.

# Multimodal Commerce Router

Use this when a user gives product links, product images, videos,
ecommerce pages, or asks for multimodal generation, QA, repair or publication.

1. Preserve raw_user_text.
2. Extract retrieval_intent:
   modality, product category, platform, task stage, risk.
3. Route:
   - facts missing -> product-truth
   - evidence unclear -> evidence-gate
   - video plan needed -> storyboard-keyframe
   - prompt needed after approval -> generation-prompt
   - asset exists -> multimodal-qa
   - final upload/check needed -> publish-acceptance
   - failure observed -> failure-memory
4. Keep style requests in generation_payload, not retrieval_intent.

12. Relationship to Product-Truth Feedback Training

Product-Truth Feedback Training (PTFT) defines what data should be captured around a generation: product truth, route choice, QA label, failure evidence, repair action and preference signal. The multi-skill system is the operating layer that produces that data reliably.

PTFT Module	Skill-Layer Implementation
Product Truth Card	Product Truth Skill
Failure Memory Retriever	Failure Memory Skill
Model Router	Router Skill
Video QA Scorer	Multimodal QA Skill
Preference Ranking	Candidate comparison and acceptance skill
Repair Policy	Repair action from QA and failure memory

In short, PTFT says what should be learned. The skill system says how an agent reliably produces the evidence needed to learn it. Product Truth Card routing adds the missing runtime boundary: facts are frozen before creative generation starts.

13. Conclusion

The next step for multimodal agents is not a longer prompt and not a single massive manual. It is a set of small, composable, auditable skills. Product truth, evidence gates, routing, keyframes, generation prompts, QA, acceptance and failure memory should each be explicit. A mature multimodal system does not simply generate polished assets. It leaves clearer judgments, fewer repeated errors and more reusable production intelligence after every run.