linkfox-aigc-imagegen-brand-gene-extract

Brand Gene Extract

Based on product images and user brand gene parameters, extract a unified brand visual language (Brand DNA), and output structured JSON for consumption by downstream atomic skills.

Applicable Scenarios

Scenario	Description
Image set orchestration invocation	Invoked by `linkfox-aigc-imagegen-cloth` / `linkfox-aigc-imagegen-product`(image set orchestration path) in step three, to define a unified visual gene for the entire image set
Brand gene change	Re-extract after the user modifies the primary color/font/platform/region
First brand definition	First extraction when there is no brand gene result in the context

Not Applicable

When a complete brandGeneJson already exists and no changes are needed (reuse directly, do not repeatedly invoke this skill)
Pure background replacement/image cutout/compositing and other image editing operations
Non-visual brand story copy

Input Parameters

Parameter	Type	Default	Description
images	list[image]	—	List of product images uploaded by the user (at least 1), used to analyze product colors and temperament
brandKey	object	—	Brand gene information input by the user (see field descriptions below)

brandKey Field Descriptions

Field	Type	Default	Description
brandColor	string	""	Brand primary color (HEX value); if non-empty, use directly; if empty, extract automatically
fontStyle	string	""	Font style; if non-empty, use directly; if empty, extract automatically
brandName	string	""	Brand name, used for brand placement strategy
language	string	"English"	Target market language
platform	string	"Amazon"	Publishing platform (Amazon/TikTok/Shopee, etc.)
salesRegion	string	"United States"	Sales region/country

Pipeline Steps

Step 1: Parameter Parsing and Decision Routing

Input：brandKey、images
Operation：
1. Parse brandKey the value of each field in
2. Primary color decision：brandColor non-empty → use directly; empty → mark as "auto-extract"
3. Font decision：fontStyle non-empty → use directly; empty → mark as "auto-extract"
4. Fill default values：language if empty, default to "English";platform if empty, default to "Amazon";salesRegion if empty, default to "United States"
5. Convert images into an accessible URL list (imageUrlList), for passing to textgen in step 3
Output: Decision routing table (which fields are user-provided and which need automatic extraction) + imageUrlList
Purpose: Guide the prompt assembly in step 2

Step 2: Assemble the brand visual gene extraction prompt

Input: The decision routing table from step 1,brandKey All fields
Action: Assemble the following brand visual DNA extraction instruction with the brandKey parameter into a complete prompt, and pass it to step 3:

Role: You are a top brand visual expert and creative director. Based on the product images and parameters, build a unified visual language to ensure a high degree of brand consistency across different scenarios.

A. Unified Visual Theme (UNIFIED_VISUAL_THEME)
1. Brand Color：
  - Define a core color with a "worldview", not just a color palette
  - Uniqueness: The entire project may define only 1 core HEX color value
  - Source: Must take into account the color of the product itself and possess extremely high aesthetics
  - ⚠️ Black/White/Gray Protocol (CRITICAL): Unless the product itself is black, white, or gray, using black, white, or gray as the primary color is prohibited; a specific color value must be output (e.g., #EAF86C)
2. Background Strategy: Mustcompletely output the following 4 subfields; none may be omitted, and each must provide specific content (must not be left blank, and must not contain only the field name):
  - Background Strategy - Style Definition: Based on salesRegion , create an overall environment style with cultural localization. Pursue a 100% photographic realistic environment; layered background-layer effects are strictly prohibited; focus on lifestyle and emotional resonance. Example:"现代北欧极简家居，原木与暖白色调，落地窗自然采光，符合美国中产审美"
  - Background Strategy - Scene Keywords: Specific scene/prop keywords separated by commas. Example:"原木长桌, 亚麻桌布, 绿植, 陶瓷器皿, 晨光"
  - Background Strategy - Lighting: Clear light direction, color temperature, and atmosphere (this is a required field, most easily omitted, and must be output). Example:"柔和自然侧光，暖色温 4000K，营造清晨慵懒氛围，轻微长投影增强立体感"
  - Brand Injection: How the brand primary color / Logo / identity elements are naturally integrated into the scene (this is a required field, most easily omitted, and must be output). Example:"品牌主色作为抱枕/标签点缀色出现，Logo 以低饱和压印形式出现在道具上，不喧宾夺主"
B. Absolute Typography Lock (LOCKED_TYPOGRAPHY)
1. Font Style: Lock in exactly one style from the following library:
  - Geometric sans-serif: Jost, League Spartan, Montserrat, Manrope, Outfit
  - Bold sans-serif: Bebas Neue, Oswald, Barlow Condensed, Anton, Fjalla One
  - Classic elegant serif: Bodoni Moda, Playfair Display, Prata, Cormorant Garamond, DM Serif Display
  - Rounded playful font: Nunito, Quicksand, Varela Round, Fredoka, Baloo 2
  - Playful handwritten style: Pacifico, Permanent Marker, Amatic SC, Caveat, Luckiest Guy
2. Color Strategy：
  - Heading Color: Must use the brand primary color or reversed white; when the color at the bottom of the heading is the brand primary color or the same color family, automatically trigger "flexible reverse white"; secondarily, consider using a color in the same family as the brand primary color (colors close to black are prohibited, and the color must not be too dark)
  - Body Color: Distinguished from the heading color to ensure readability
  - ⚠️ Output Format Note: The color strategy output format is ["Heading Color"：颜色值] and ["Body color"：颜色值], this is a color definition rather than text content
3. Flexible inverse permission: when using a dark background or a solid brand-color block, authorization switches to matte white (#FFFFFF) text
4. Typography restrictions: uniformly non-italic, with standard leading
Output requirements: output the complete JSON strictly according to the "Output Format" below; do not output any explanatory text or code block markers.
Output: the complete textgen prompt string
Purpose: used as the prompt input for step 3

Step 3: Call linkfox-aigc-textgen to perform visual reasoning

Input: the prompt from step 2, the imageUrlList
Operation: according to linkfox-aigc-textgen SKILL.md's invocation method, call textgen to perform visual reasoning. The content produced in this step must beread back into context for field extraction(step 4),notchained into downstream image generation, so use textgen'sdefault mode(not --content-only): write the following fields into a JSON parameter file, pass it in via --stdin to run, then parse stdout.<textgen根目录> is obtained via skill:linkfox-aigc-textgen by resolving the absolute path of the directory containing its SKILL.md;<本skill根目录> = the absolute path of the directory containing this SKILL.md.
⚠️ The intermediate parameter file goes into the session data/ directory. First get the directory:
```
DATADIR=$(python <本skill根目录>/scripts/save_brand_gene.py --datadir)
```
⚠️ To construct brand_gene_params.json , you must use the Write toolto write to $DATADIR/brand_gene_params.json(the prompt contains special characters such as quotes and backslashes, and embedding JSON in a shell heredoc is prone to parsing failures). If generating via the command line, only use python -c together with json.dumps, and do not manually concatenate JSON strings.
```
python <textgen根目录>/scripts/aigc_textgen.py --stdin < "$DATADIR/brand_gene_params.json"
```
The JSON parameter file contains the following fields:
- prompt: the brand visual gene extraction instruction assembled in step 2 (including the "Output Format" requirement)
- imageUrls: the imageUrlList
- model：GEM_3_1_PROoutput in step 1 (requires visual understanding and complex reasoning capabilities)
- thinkingLevel：high
Output: parse textgen stdout to obtain content(parse according to linkfox-aigc-textgen SKILL.md's "Output Contract").
Purpose: used as assembly material for step 4

Step 4: Assemble brandGeneJson

Input: the contentparsed in step 3 (line breaks may be ⏎ placeholders; restore them to newline characters before extraction)
Operation: extract each field of the brand visual gene from this content , and assemble it yourself into brandGeneJson
Fallback for missing fields (mandatory): after assembly,you must check one by onewhether all fields in the "Output Format" are present. If the model output omits a field (in practice, the most easily omitted are 背景策略-光影 and Brand Injection（品牌植入）），you must not directly deliver incomplete JSON; you must fill it in as a fallback in the following order:
1. First, infer a reasonable value for the field from the remaining text of content ;
2. When there is no inferable content, combine the already determined primary color / style definition to generate a fallback description consistent with the overall tone (e.g., for lighting use "natural soft side light, warm color temperature, enhanced three-dimensionality"; for brand placement use "primary color as accent, Logo subtly integrated into props"). Final brandGeneJson must have all fields complete,forbiddenmissing fields or field values that are empty strings may appear.
Output：brandGeneJson(a JSON list of length 1, with all fields complete)
Write to disk (mandatory): after assembly is completemustwrite to the session directory and retain the path for downstream reuse:
1. Use the Write tool to write brandGeneJson to $DATADIR/brand_gene_assembled.json（DATADIR same as step 3); or
2. run the write-to-disk script (recommended, automatically registers _meta.json）：
```
python <本skill根目录>/scripts/save_brand_gene.py "$DATADIR/brand_gene_assembled.json"
```
  stdout will print Saved full response: <绝对路径> (<N> bytes)——record that absolute path in the context, and subsequent S3 image-set orchestration consumes it through --brand-gene-file <绝对路径> or the manifest's brand_gene_json .
Purpose: pass through to the downstream image generation pipeline (linkfox-aigc-imagegen-cloth 's seeding images/selling point images/A+ images and other types / linkfox-aigc-imagegen-product , etc.) as the brandGeneJson parameter

Artifact write-to-disk

Artifact	Directory	Description
`brand_gene_params.json`	`<session>/data/`	textgen input (step 3 intermediate file)
`brandGeneJson` final result	`<session>/data/linkfox-aigc-imagegen-brand-gene-extract-<ts>.json`	via `save_brand_gene.py` written to disk, for reuse by image set S3 and single-image `--brand-gene-file` reuse

Path protocol:<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/（<session> taken from SESSION_ID), consistent with the repository CLAUDE.md"Output File Location".

Core Rules

A. Primary color and font logic

If brandColor has a value → in the output JSON, "brandColor (brand primary color)" directly uses that value
If fontStyle has a value → in the output JSON, "font style" directly uses that value
If either value is empty → automatically extract that value using the rules in the core variables

B. Other value logic

Fields such as "background strategy-style definition" and "color strategy-Heading" are by default all obtained using the rules in the core variables, and are not affected by the pass-through of brandColor/fontStyle in brandKey.

Output Format

Strictly output in the following JSON format, as a list of length 1:

[
  {
    "brandColor": {
      "brandColor (品牌主色)": "颜色名称与HEX值",
      "背景策略-风格定义": "基于 salesRegion 的风格描述",
      "背景策略-场景关键词": "关键词1, 关键词2, ...",
      "背景策略-光影": "光影氛围描述",
      "Brand Injection（品牌植入）": "品牌元素如何植入场景"
    },
    "fontStyle": {
      "字体策略": "选定的字体家族名称",
      "字体风格": "选定的具体字体名称",
      "颜色策略-Heading": "[\"Heading Color\"：颜色值/反白逻辑]",
      "颜色策略-Body/Sub": "[\"Body color\"：颜色值]",
      "灵活反白": "You are authorized to switch to Matte White (#FFFFFF) text whenever using a dark background or a solid brand-color panel.",
      "排版": "Non-italic, standard leading"
    }
  }
]

Error Handling

Case	Handling
images is empty	Stop execution and prompt the user to upload at least 1 product image
brandKey is completely empty	Fill all fields with default values (salesRegion=United States, language=English, platform=Amazon), and use automatic extraction for primary color and font
The product is pure black, white, and gray, and no colored primary color can be extracted	Allow black, white, and gray to be used as the primary color (the only exemption condition of the black-white-gray protocol)

Invocation Method

This skill is invoked by the image set orchestration layer in step three; invocation timing:

First invocation: when brand gene style extraction has not been performed in the context
Re-invocation: when the user explicitly requests modification of the brand gene (scenario G)

Reuse rule: Extraction results can be reused in the same context without repeated calls.

Solve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

API Key not configured: environment variable not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
response 401 or 402 status code
response indicates insufficient compute or balance: message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Known limitations

Brand primary color extraction is based on GEM_3_1_PRO visual understanding of product images, which may differ from professional designers' judgment
Font styles are limited to the preset 5 categories and 25 fonts; fonts outside the library cannot be selected
Cultural localization of background strategy depends on semantic understanding of salesRegion, not a structured regional database
The brand gene JSON must be persisted to session save_brand_gene.py via data/, and cannot exist only in the conversation context
Depends on linkfox-aigc-textgen skill availability; if the textgen call fails, brand gene extraction cannot be completed