Retail Content Generator

Overview

Generates product titles, descriptions, and attributes at scale while maintaining brand voice consistency. Optimizes content for three discovery channels: traditional search engines (SEO), generative AI engines like AI-powered search engines (GEO), and answer engines like voice assistants and featured snippets (AEO). Works from CSV/Excel product data or any product catalog connector.

Workflow

<Definition - Data Source Cascade> Try in order, stop at first success:

1. Product catalog MCP connector detected (PIM, Shopify, commerce platform): pull product data directly.
2. File path provided (.csv, .xlsx): parse with run_python.
3. Product details pasted in chat: parse structured data from message.
4. Nothing available: ask user to upload a file or provide product details. </Definition - Data Source Cascade>

<Definition - SEO Optimization> Traditional search engine optimization:

• Primary keyword in first sentence and product title.
• Keyword density 1-2% (natural, not forced).
• Secondary keywords in body and attributes.
• Meta description suggestion: 150-155 characters with keyword + benefit.
• Structured heading hierarchy for crawlability. </Definition - SEO Optimization>

<Definition - GEO Optimization> Generative Engine Optimization (for AI-powered search engines and assistants):

• Include at least one citable factual claim per description: specific measurements, materials, certifications, origin, or peer-reviewed comparisons.
• Use concise, authoritative declarative statements that AI engines can quote verbatim.
• Structure information in a way that answers implicit questions (what is it, what makes it different, who is it for).
• Cite verifiable specs: "100% organic cotton, OEKO-TEX certified" rather than "made from quality materials."
• Avoid subjective superlatives ("best", "amazing") that AI engines cannot verify or cite. </Definition - GEO Optimization>

<Definition - AEO Optimization> Answer Engine Optimization (for voice assistants, featured snippets, People Also Ask):

• Include one direct-answer sentence per product that answers "What is [product]?" in under 30 words.
• Format key specs as scannable list (bullet points or pipe-separated) for featured snippet extraction.
• Include a natural FAQ pair: one question a shopper would ask, with a direct 1-2 sentence answer.
• Use schema-friendly language: "This [product] is designed for [audience] who need [benefit]." </Definition - AEO Optimization>

<Definition - Tone Calibration> The mandatory approval gate before batch processing:

1. Analyze brand voice source (style guide or example descriptions).
2. Extract: sentence length, vocabulary level, punctuation style, emotional register, forbidden words.
3. Generate 3-5 sample descriptions spanning different product types.
4. Present to user for approval. Only proceed to batch after explicit "looks good" or equivalent.
5. If user requests changes, regenerate samples incorporating feedback until approved. </Definition - Tone Calibration>

<Definition - Quality Metrics> Checked after each batch:

• Repetition: no phrase (3+ words) appears in more than 20% of descriptions in the batch.
• Word count: within 10% of target content_length.
• Readability: Flesch-Kincaid grade level appropriate for target audience (typically 8-10 for retail).
• Keyword presence: primary keyword appears in every description (SEO mode).
• Citable claim present: at least one verifiable fact per description (GEO mode).
• Direct answer present: under-30-word "What is this?" sentence exists (AEO mode). </Definition - Quality Metrics>

<Workflow - Setup description="First-run brand voice establishment and data source detection." tools=[run_python, file_read, file_write] triggers=["first time", "setup content generator", "configure brand voice", "reset voice"]

[Decide] Check if {{config_directory}}/content-generator-config.json exists:

• EXISTS: Load saved brand voice profile and data preferences. Proceed to Generate Content workflow.
• DOES NOT EXIST: Continue with setup below. Validate: File existence determined. If fails: Assume first run.

[Decide] Detect product data source per <Definition - Data Source Cascade>:

• Product catalog connector available: probe for product list.
• File path provided in product_data input: verify with file_read.
• Product details pasted in chat: parse from message.
• Nothing: proceed to ask user. Validate: Data source type determined. If fails: [Ask user] "Please upload a CSV/Excel with your product data, or paste a few products directly."

[Decide] Is brand_voice_guide provided?

• File path provided: read and analyze for tone markers.
• Text description provided (e.g., "playful and casual"): use as tone direction.
• Not provided: check if existing product descriptions are available in the product data for reference.
• Nothing at all: ask user for 3 adjectives describing their brand personality. Validate: At least one tone signal is available. If fails: [Ask user] "Describe your brand voice in 3 adjectives (e.g., 'warm, expert, conversational')."

[Agent] Analyze brand voice source using run_python. Extract:

• Average sentence length (short/medium/long).
• Vocabulary level (casual/professional/technical).
• Punctuation style (exclamation marks, ellipses, fragments allowed?).
• Emotional register (neutral/enthusiastic/aspirational/authoritative).
• Forbidden patterns (words or structures to avoid).
• Person/voice (first person we, second person you, third person). Validate: At least 4 of 6 dimensions extracted. If fails: Use the 3-adjective fallback and infer defaults.

[Agent] Save brand voice profile and data source config to {{config_directory}}/content-generator-config.json. Validate: Config written. If fails: Present config as text for user reference.

</Workflow - Setup>

<Workflow - Generate Content description="Main workflow: load data, calibrate tone, generate in batches with QA." tools=[run_python, file_write, file_read, file_read_image, open_in_session_tab, web_search] triggers=["generate product descriptions", "write product content", "create listings", "product copywriting", "bulk content generation", "optimize for AI search"]

[Agent] Load {{config_directory}}/content-generator-config.json for brand voice profile. Validate: Config loaded with tone parameters. If fails: Route to Setup workflow.

[Agent] Load product data from source (file or connector). Parse into structured dataframe with run_python. Identify columns: SKU/ID, product_name, category, attributes, material, dimensions, price, image_path. Validate: At least product_name column identified. Total product count determined. If fails: [Ask user] "I could not parse the product data. Which column contains the product name?"

[Decide] Are product images available (image_path column or attached files)?

• Yes: flag for visual enrichment in generation step.
• No: proceed without visual details. Validate: Image availability determined. If fails: Assume no images.

[Decide] Is "seo" in optimization_modes?

• Yes: [Agent] Research primary keywords per product category using web_search. Identify 1 primary + 2-3 secondary keywords per category (not per product).
• No: Skip keyword research. Validate: Keywords identified per category, or skip confirmed. If fails: Use product_name + category as default keywords.

[Agent] Generate 3-5 tone calibration samples spanning different product types from the data. Apply per <Definition - Tone Calibration>:

• Match brand voice profile.
• Apply SEO keywords (if seo mode).
• Include one citable factual claim (if geo mode).
• Include one direct-answer sentence under 30 words (if aeo mode). Validate: Samples generated with all active optimization modes visible. If fails: Generate simpler samples without optimization layers, then add them after tone is approved.

[Ask user] Present calibration samples using <Template - Calibration Samples Presentation>. Validate: User approves or provides specific feedback. If fails: Incorporate feedback and regenerate samples. Repeat until approved.

[Agent] Begin batch generation. Process batch_size products at a time using run_python. For each product:

• Generate title (SEO keyword front-loaded if seo mode).
• Generate description at target content_length.
• Embed citable claim (GEO): specific measurement, material, certification, or comparison.
• Embed direct-answer sentence (AEO): "What is [product]?" answer in under 30 words.
• Include FAQ pair: one natural question + 1-2 sentence answer.
• If image available: use file_read_image to extract visual details and incorporate.
• Tag output with SKU/ID for PIM mapping. Validate: Batch complete with all fields populated per product. If fails: Flag incomplete products and continue with remainder.

[Agent] Run quality assurance per <Definition - Quality Metrics>:

• Repetition check: no 3+ word phrase in >20% of batch descriptions.
• Word count: within 10% of target.
• Keyword presence (SEO mode): primary keyword in every description.
• Citable claim present (GEO mode): at least one verifiable fact per description.
• Direct answer present (AEO mode): under-30-word sentence exists per description.
• Readability: Flesch-Kincaid grade 8-10. Validate: All metrics pass. If fails: Regenerate failing descriptions with targeted fixes (e.g., "add material spec" for GEO, "shorten answer sentence" for AEO).

[Ask user] Present batch for review using <Template - Batch Review Presentation>. Validate: User approves batch. If fails: Revise flagged products and re-present.

[Decide] Are there more products remaining?

• Yes: Loop back to batch generation step.
• No: Proceed to export. Validate: Remaining count determined. If fails: Check dataframe length vs processed count.

[Agent] Compile all generated content into output file (format per output_format input: csv, xlsx, json, or markdown). Use the column structure defined in <Template - Output Columns>. Validate: Output file written with correct row count matching input products. If fails: Retry file write. If format-specific error, fall back to CSV.

[Agent] Open output file in session tab using open_in_session_tab. Validate: File displayed. If fails: Provide file path.

[Agent] Present summary using <Template - Generation Summary>. Validate: Summary presented. If fails: N/A.

</Workflow - Generate Content>

<Template - Calibration Samples Presentation>

Here are {{sample_count}} sample descriptions in your brand voice. Each includes:
- [SEO] keyword integration (highlighted)
- [GEO] citable factual claim (highlighted)
- [AEO] direct-answer sentence (highlighted)

{{samples}}

Please review and tell me if the tone and optimization balance feels right, or what to adjust.

</Template - Calibration Samples Presentation>

<Template - Batch Review Presentation>

Batch {{batch_number}} complete: {{product_count}} products. QA results: {{qa_pass_fail_summary}}.

Here are 3 representative samples from this batch. Full batch available in the output file.

{{representative_samples}}

Approve to continue, or flag specific products for revision.

</Template - Batch Review Presentation>

<Template - Output Columns> sku, product_name, generated_title, generated_description, seo_keywords, geo_claim, aeo_answer, faq_question, faq_answer </Template - Output Columns>

<Template - Generation Summary>

{{total_products}} product descriptions generated in {{elapsed_time}}.
Optimization applied: {{optimization_flags}}.
Output: {{filename}} (open in tab).
QA summary: {{pass_rate}}% passed all checks.

</Template - Generation Summary>