Skill: leooooooow/aes-product-description-writer (version 1.1.0)

--- name: aes-product-description-writer description: Write high-converting product descriptions optimized for specific platforms and audiences. Use when creating new product listings, rewriting underperforming descriptions, adapting descriptions across platforms (Amazon, Shopify, Walmart), or generating batch descriptions for catalog launches. --- # Product Description Writer Write product descriptions that convert browsers into buyers — structured for the platform, optimized for search, and grounded in what makes the product worth buying. ## Quick Reference | Decision | Guidance | |---|---| | **Framework selection** | Use AIDA for new/innovative products, PAS for problem-solving products, FAB for technical/feature-rich products, Before-After-Bridge for lifestyle/aspirational products. See `references/description-frameworks.md`. | | **Tone calibration** | Match the brand's existing voice. If no brand guide exists, default to confident-but-conversational. Avoid hyperbole ("revolutionary", "best ever") unless the product genuinely leads its category. | | **Keyword integration** | Primary keyword in title and first 50 words of description. Secondary keywords distributed naturally — never stuffed. Target 1-2% keyword density. See `references/seo-guidelines.md`. | | **Benefit vs. feature balance** | Lead every bullet point with the benefit, then support with the feature. "Stay warm in -20°F weather (800-fill down insulation)" not "800-fill down insulation." | | **Platform formatting** | Amazon: 5 bullet points, 200 chars each max, Title ≤200 chars. Shopify: HTML-capable, use headers and formatting. Walmart: similar to Amazon but shorter bullets. See `references/description-frameworks.md`. | | **Length calibration** | Short description: 25-50 words. Standard bullets: 5-7, each 15-25 words. Long description: 150-300 words. Adjust based on product complexity and price point — expensive products need more copy. | | **SEO compliance** | Every description must include: primary keyword in title, 2-3 secondary keywords in body, meta description ≤155 chars, alt-text suggestions for images. See `references/seo-guidelines.md`. | | **Output structure** | Follow the structured output template. Include all variants requested. Never deliver a description without the quality checklist pass. See `references/output-template.md`. | ## Solves 1. **Blank page paralysis** — Seller has product specs and photos but cannot translate them into compelling copy that drives purchases. The skill provides a structured framework to move from raw inputs to polished descriptions. 2. **Feature-dump descriptions** — Existing descriptions list specifications without connecting them to customer benefits, resulting in low conversion despite good traffic. 3. **Platform mismatch** — A description written for one platform (e.g., a Shopify store) needs adaptation for another (e.g., Amazon) with different formatting rules, character limits, and SEO requirements. 4. **Inconsistent brand voice** — Multiple products in a catalog have descriptions that feel like they were written by different people, undermining brand cohesion and trust. 5. **SEO-invisible listings** — Products rank poorly in marketplace and Google search because descriptions lack keyword optimization, structured formatting, and search-friendly patterns. 6. **Batch catalog launches** — Seller is launching 10-50+ products simultaneously and needs consistent, high-quality descriptions at scale without sacrificing quality for speed. 7. **Low conversion despite traffic** — Product pages receive adequate views but underperform on add-to-cart rates, suggesting the description fails to overcome purchase objections or communicate value. ## Modes ### Mode A — Single Product Description A deep, crafted description for one product. Use this mode when you need maximum quality for a hero product, a product launch, or a high-traffic listing that justifies dedicated attention. **When to use:** New product launches, hero/flagship products, underperforming listings that need rewriting, products with complex features requiring careful explanation. ### Mode B — Batch Description Generation Descriptions for multiple products sharing a category, brand voice, or template structure. Use this mode when launching a product line or updating a catalog section. **When to use:** Catalog launches, seasonal collection updates, platform migration (e.g., moving all listings from Shopify to Amazon), brand voice standardization across existing products. ## Core Job Transform raw product information into purchase-motivating descriptions that: 1. **Communicate value** — Answer "why should I buy this?" within the first sentence 2. **Overcome objections** — Address the top 3-5 reasons a shopper might hesitate 3. **Optimize for search** — Integrate keywords naturally so the listing ranks for relevant queries 4. **Match the platform** — Follow platform-specific formatting, character limits, and best practices 5. **Maintain brand voice** — Sound like the brand, not like generic marketplace copy ## Inputs ### Required - Product name and category - Key features (specs, materials, dimensions, etc.) - Target platform (Amazon, Shopify, Walmart, Etsy, general ecommerce) - Target audience (who is this product for?) ### Strongly recommended - Brand voice guidelines or examples of existing copy - Primary and secondary keywords (or keyword research data) - Price point and competitive positioning (budget, mid-range, premium) - Top 3 customer pain points the product solves - Key differentiators vs. competitors ### Optional but valuable - Customer reviews or testimonials to mine for language - Product photos or image descriptions (for alt-text and visual cue integration) - Existing description to improve (for rewrites) - Competitor listing URLs for positioning context - Seasonal or promotional context ## Workflow — Mode A: Single Product Description ### Step 1: Product Understanding Before writing a single word, build a complete mental model of the product: - **What is it?** Category, type, variant - **Who is it for?** Primary buyer persona, secondary audiences - **What problem does it solve?** The core pain point or desire it addresses - **What makes it different?** The 1-3 features that separate it from alternatives - **What might stop someone from buying?** Top objections (price, quality doubts, fit uncertainty, competitor preference) If the user hasn't provided enough information to answer these questions, ask before proceeding. A great description requires great inputs. ### Step 2: Framework Selection Choose the description framework based on product type and audience (see `references/description-frameworks.md`): | Product Type | Recommended Framework | |---|---| | Innovative/new-to-market | AIDA (Attention-Interest-Desire-Action) | | Problem-solving (health, home repair, organization) | PAS (Problem-Agitate-Solution) | | Technical/spec-heavy (electronics, tools, equipment) | FAB (Feature-Advantage-Benefit) | | Lifestyle/aspirational (fashion, home decor, wellness) | Before-After-Bridge | ### Step 3: Keyword Integration Planning Before writing, map keywords to description sections: - **Title:** Primary keyword + brand + key differentiator - **First bullet/sentence:** Primary keyword, natural usage - **Body bullets:** One secondary keyword per bullet, distributed naturally - **Long description:** Primary keyword once in first paragraph, secondary keywords throughout - **Meta description:** Primary keyword within first 70 characters Never sacrifice readability for keyword insertion. If a keyword doesn't fit naturally, use a close variant or place it in a less visible field (backend keywords on Amazon, meta tags on Shopify). ### Step 4: Draft Creation Write the complete description package: 1. **Product title** — 2-3 variants optimized for the target platform 2. **Bullet points** — 5-7 benefit-led bullets, each following the pattern: [Benefit] — [Supporting feature/proof] 3. **Short description** — 25-50 word hook for category pages, ads, or social sharing 4. **Long description** — 150-300 words following the chosen framework, structured with scannable formatting 5. **SEO meta description** — ≤155 characters, includes primary keyword and a call to action ### Step 5: Objection Handling Review the draft and ensure it addresses the top purchase objections: - **Price objection:** Communicate value relative to alternatives or per-use cost - **Quality doubt:** Include materials, certifications, warranty, or social proof references - **Fit/compatibility:** Specify dimensions, compatibility, or use cases clearly - **Trust gap:** Reference brand history, review count, or guarantees - **Comparison shopping:** Highlight differentiators without naming competitors directly ### Step 6: Platform Optimization Adapt the draft to the target platform's requirements: - **Amazon:** Title �j$200 chars, 5 bullet points �j$500 chars each, A+ Content HTML if applicable, backend search terms - **Shopify:** HTML formatting, heading tags for SEO, schema-friendly structure - **Walmart:** Title ≤75 chars (ideal), concise bullets, Walmart-specific category requirements - **Etsy:** Story-driven, handmade/artisan emphasis, 13 tag slots - **General ecommerce:** Clean HTML, mobile-responsive formatting considerations ### Step 7: Quality Review Run the complete quality checklist (see `assets/quality-checklist.md`). Verify: - All required output sections are present - Keywords are integrated naturally (not stuffed) - Benefits lead features in every bullet - Tone matches brand voice guidelines - Platform character limits are respected - No superlatives without substantiation - Grammar, spelling, and formatting are clean ## Workflow — Mode B: Batch Description Generation ### Step 1: Template Development Before writing individual descriptions, create a reusable template: - Establish the shared brand voice and tone - Define the bullet point structure (consistent pattern across products) - Set keyword integration rules for the category - Create placeholder patterns: [BENEFIT] — [FEATURE] for [AUDIENCE] ### Step 2: Product Grouping Group products by similarity to maximize template reuse: - Same category (all kitchen tools, all running shoes) - Same audience (all products for new parents) - Same price tier (all premium items) ### Step 3: Sequential Generation Write descriptions in groups, maintaining consistency: - Write the first product in each group with full attention (it becomes the reference) - Use that reference to maintain voice and structure for subsequent products - Vary opening hooks and specific language to avoid repetition across the catalog ### Step 4: Cross-Product Review After all descriptions are drafted: - Read all descriptions in sequence to catch repetitive phrases - Verify each product's unique differentiators are clearly communicated - Ensure no two products in the same category could be confused based on their descriptions - Confirm keyword distribution doesn't create internal competition (different products targeting identical keywords) ## Writing Rules ### The Benefit-First Rule Every feature mention must be preceded or accompanied by its benefit. The customer cares about outcomes, not specifications. **Wrong:** "Made with 18/10 stainless steel construction" **Right:** "Resists rust and staining for years of daily use — crafted from 18/10 stainless steel" ### The Specificity Rule Vague claims feel like marketing. Specific claims feel like information. **Wrong:** "Keeps your drinks cold for a long time" **Right:** "Keeps drinks ice-cold for up to 24 hours, even in 95°F heat" ### The Scanability Rule Online shoppers scan, they don't read. Structure descriptions for scanning: - Front-load the most important information - Use bullet points with bold lead-ins - Keep paragraphs to 2-3 sentences maximum - Use white space deliberately ### The One-Sentence Test If you can't summarize the product's core value in one sentence, the description isn't focused enough. Write that sentence first, then build around it. ### The Competitor-Blind Rule Never mention competitors by name. Instead, use comparative language: "Unlike typical [category] products..." or "Where most [products] fall short..." ## Worked Example 1 — Kitchen Product (Single Product, Amazon) **Input provided:** - Product: Silicone Spatula Set, 4-piece, heat-resistant to 600°F - Brand: HomeChef Essentials (mid-range, quality-focused) - Target: Home cooks upgrading from cheap utensils - Keywords: silicone spatula set, heat resistant spatula, cooking utensils set - Price: $18.99 - Differentiators: one-piece construction (no seams), dishwasher safe, includes 4 sizes **Framework selected:** FAB (feature-rich kitchen product) **Output:** **Title Options:** 1. HomeChef Essentials Silicone Spatula Set (4-Piece) — Heat Resistant to 600°F, One-Piece Seamless Design, Dishwasher Safe Cooking Utensils 2. HomeChef Essentials 4-Piece Silicone Spatula Set — 600°F Heat Resistant, Seamless One-Piece Construction, BPA-Free Kitchen Utensils Set **Bullet Points:** - **Cook with confidence at any temperature** — Heat resistant to 600°F, these silicone spatulas handle everything from delicate sauces to high-heat searing without melting, warping, or releasing harmful chemicals. BPA-free and FDA-approved food-grade silicone. - **No seams means no trapped food or bacteria** — Unlike spatulas with separate heads and handles, our one-piece seamless construction eliminates the gap where food particles hide. Cleaner cooking, every time. - **Four sizes for every cooking task** — Includes large turner (12"), standard spatula (10"), small scraper (8.5"), and mini spatula (6") so you always have the right tool. From flipping pancakes to scraping the last bit from a jar. - **Dishwasher safe and built to last** — Toss them in the top rack after cooking. The reinforced silicone core maintains shape and flexibility through hundreds of wash cycles without cracking or fading. - **Non-scratch safe for all cookware** — Soft silicone edges protect non-stick coatings, ceramic, stainless steel, and cast iron surfaces. No more worrying about damaging your expensive pans. **Short Description:** 4-piece silicone spatula set with seamless one-piece construction, heat resistant to 600°F. Dishwasher safe, BPA-free, and gentle on all cookware surfaces. Includes 4 sizes from 6" to 12". **Long Description:** The HomeChef Essentials Silicone Spatula Set gives you the right tool for every cooking task — without the hygiene concerns of traditional spatulas. Our one-piece seamless construction means no gaps where food particles and bacteria can hide, a common problem with two-piece spatulas that separate over time. Each spatula is heat resistant to 600°F and made from BPA-free, FDA-approved food-grade silicone. Whether you're folding delicate batter or scraping fond from a cast-iron skillet, these spatulas perform without melting, warping, or scratching your cookware. The set includes four essential sizes: a large turner for flipping, a standard spatula for stirring and folding, a small scraper for jars and bowls, and a mini spatula for precision tasks. All four are dishwasher safe and maintain their shape and flexibility wash after wash. Upgrade from spatulas that crack, stain, and trap food — cook cleaner with HomeChef Essentials. **SEO Meta Description:** 4-piece silicone spatula set, heat resistant to 600°F. Seamless one-piece design, dishwasher safe, BPA-free. Free shipping on orders $25+. ## Worked Example 2 — Fashion Product (Single Product, Shopify) **Input provided:** - Product: Women's Merino Wool Crewneck Sweater - Brand: Everthread (premium basics, minimalist aesthetic) - Target: Professional women 28-45, capsule wardrobe builders - Keywords: merino wool sweater women, women's crewneck sweater, capsule wardrobe essentials - Price: $128 - Differentiators: 100% extra-fine 17.5 micron merino, machine washable, temperature-regulating **Framework selected:** Before-After-Bridge (lifestyle/aspirational product) **Output:** **Title Options:** 1. The Essential Merino Crewneck — Women's 100% Extra-Fine Merino Wool Sweater 2. Women's Extra-Fine Merino Wool Crewneck Sweater — Machine Washable, Temperature-Regulating **Bullet Points:** - **Feels like cashmere, performs like technical gear** — 17.5-micron extra-fine merino wool is soft against skin, naturally temperature-regulating, and moisture-wicking. Comfortable from the morning commute to evening dinner. - **Machine wash. Seriously.** — Unlike most merino sweaters that demand hand-washing, ours is engineered for the washing machine. Cold cycle, lay flat to dry. Premium quality without precious maintenance. - **The perfect layer, every season** — Merino wool naturally regulates body temperature. Warm when it's cool, breathable when it's warm. One sweater that works October through April. - **Minimal pilling, maximum longevity** — Extra-fine, long-staple fibers resist the pilling that plagues cheaper wool sweaters. This crewneck looks as good on wear 100 as wear 1. - **Capsule wardrobe essential** — Clean crewneck silhouette pairs with everything from tailored trousers to weekend denim. Available in 8 foundational colors designed to work together. **Short Description:** 100% extra-fine merino wool crewneck sweater. Machine washable, naturally temperature-regulating, and built to last. The one sweater your capsule wardrobe is missing. **Long Description:** <h3>Before Everthread</h3> Your sweater drawer is a compromise. Cheap knits that pill after three wears. "Dry clean only" wool that spends more time at the cleaners than on your body. Synthetic blends that trap heat in the office and leave you shivering on the walk home. <h3>After Everthread</h3> One sweater that actually works. Soft 17.5-micron extra-fine merino that regulates your temperature naturally — warm when you need warmth, breathable when you don't. Machine washable because life is too short for hand-wash-only labels. And a clean crewneck silhouette that works with your entire closet, not just one outfit. <h3>The Bridge</h3> The Essential Merino Crewneck is built from 100% extra-fine merino wool, the same grade used in premium European knitwear. Long-staple fibers resist pilling, so this sweater maintains its shape and softness through hundreds of wears. We engineered the knit structure for machine washing — cold cycle, lay flat to dry — because premium shouldn't mean high-maintenance. Available in 8 colors designed as a collection: each pairs with every other. Build your capsule, stop overthinking your morning. **SEO Meta Description:** Women's extra-fine merino wool crewneck sweater. Machine washable, temperature-regulating, pill-resistant. The capsule wardrobe essential. Free shipping & returns. ## Common Mistakes 1. **Leading with features instead of benefits.** "Made with 304 stainless steel" means nothing to most shoppers. "Resists rust and staining for years of daily use" tells them why they should care. Always lead with the outcome, then support with the feature. 2. **Writing for yourself instead of the buyer.** The product creator is excited about materials and engineering. The buyer wants to know how it improves their life. Shift perspective from "we made" to "you get." 3. **Ignoring the platform's formatting constraints.** An Amazon title over 200 characters gets truncated. Shopify descriptions without HTML formatting look like walls of text. Always format for the specific platform. 4. **Keyword stuffing that destroys readability.** "Our silicone spatula set silicone cooking utensils silicone kitchen tools" reads like spam and hurts both conversion and SEO. Keywords should feel invisible to the reader. 5. **Using unsupported superlatives.** "The best spatula ever made" invites skepticism. "Heat resistant to 600°F, higher than 90% of silicone spatulas on the market" invites trust. Substantiate every strong claim. 6. **Writing identical structures for every product.** When all 20 products in a catalog start with the same sentence pattern, the listing page feels generated and impersonal. Vary your openings and structures. 7. **Forgetting mobile readers.** Over 60% of ecommerce browsing happens on mobile. Long paragraphs, tiny details, and complex formatting break on small screens. Test your descriptions at 375px width mentally. 8. **Neglecting the short description.** The short description appears in search results, category pages, and social shares. It's often the only copy a shopper reads before deciding to click or scroll past. Give it real attention. 9. **Skipping objection handling.** Every product has purchase barriers — price, quality doubts, sizing uncertainty, competitor comparison. Great descriptions address these proactively instead of hoping the shopper won't think of them. 10. **Not adapting for the product's price tier.** A $15 product needs concise, punchy copy. A $500 product needs detailed justification, story, and trust-building. Match description depth to price and purchase consideration level. ## Resources | Resource | Path | Description | |---|---|---| | Output Template | `references/output-template.md` | Structured templates for Mode A and Mode B deliverables | | Description Frameworks | `references/description-frameworks.md` | AIDA, PAS, FAB, and Before-After-Bridge frameworks with platform-specific formatting rules | | SEO Guidelines | `references/seo-guidelines.md` | SEO best practices for product descriptions across major platforms | | Quality Checklist | `assets/quality-checklist.md` | Pre-delivery quality checklist with 45+ validation items |

path: references/output-template.md
content: # Product Description Writer — Output Template

Use this template for all product description deliverables.

---

## Mode A — Single Product Output

### 1. Product Summary

| Field | Value |
|---|---|
| Product | [Name] |
| Brand | [Brand name] |
| Category | [Product category] |
| Target platform | [Amazon / Shopify / Walmart / Etsy / General] |
| Target audience | [Primary buyer persona] |
| Price point | [Price] |
| Positioning | [Budget / Mid-range / Premium] |
| Framework used | [AIDA / PAS / FAB / Before-After-Bridge] |
| Primary keyword | [keyword] |
| Secondary keywords | [keyword 1, keyword 2, keyword 3] |

### 2. Product Title

Provide 2-3 title variants optimized for the target platform.

**Variant 1:** [Title — optimized for search]
**Variant 2:** [Title — optimized for click-through]
**Variant 3 (optional):** [Title — brand-forward variant]

**Platform character limit:** [State the limit and confirm all variants comply]

### 3. Bullet Points

Write 5-7 bullet points following the benefit-first pattern.

Each bullet should follow this structure:
**[Benefit headline in bold]** — [Supporting detail with feature, proof point, or specificity]

- **[Benefit 1]** — [Feature/proof]
- **[Benefit 2]** — [Feature/proof]
- **[Benefit 3]** — [Feature/proof]
- **[Benefit 4]** — [Feature/proof]
- **[Benefit 5]** — [Feature/proof]

**Character count per bullet:** [Confirm each bullet respects platform limits]

### 4. Short Description

25-50 words. Used for category pages, search results, social sharing, and ad copy.

[Short description text]

**Word count:** [N]

### 5. Long Description

150-300 words following the selected framework. Use HTML formatting if the platform supports it.

[Long description text]

**Word count:** [N]
**Framework applied:** [Name]

### 6. SEO Meta Description

≤155 characters. Includes primary keyword and ideally a call to action or value proposition.

[Meta description text]

**Character count:** [N]

### 7. Keyword Integration Map

| Keyword | Placement | Type |
|---|---|---|
| [Primary keyword] | Title, first bullet, first paragraph of long description | Primary |
| [Secondary keyword 1] | Bullet 2, long description body | Secondary |
| [Secondary keyword 2] | Bullet 4, short description | Secondary |
| [Secondary keyword 3] | Long description closing paragraph | Secondary |

### 8. Additional Deliverables (if requested)

- **Image alt-text suggestions:** [2-3 alt-text suggestions for product images]
- **Backend search terms (Amazon):** [Comma-separated backend keywords not already in visible copy]
- **Social media snippet:** [140-character product hook for social sharing]

---

## Mode B — Batch Output

### 1. Batch Summary

| Field | Value |
|---|---|
| Brand | [Brand name] |
| Category | [Shared category] |
| Products in batch | [N] |
| Target platform | [Platform] |
| Brand voice | [Brief voice description] |
| Template pattern | [Describe the shared structure] |
| Date generated | [ISO date] |

### 2. Shared Elements

**Brand voice notes:** [2-3 sentences describing the consistent voice across all descriptions]

**Bullet structure pattern:** [The pattern all products follow, e.g., "Benefit — feature — proof point"]

**Keyword strategy:** [How keywords are distributed to avoid internal competition]

### 3. Individual Product Descriptions

Repeat for each product:

#### Product [N]: [Product Name]

**Title:** [Optimized title]

**Bullets:**
- [Bullet 1]
- [Bullet 2]
- [Bullet 3]
- [Bullet 4]
- [Bullet 5]

**Short description:** [25-50 words]

**Long description:** [150-300 words]

**Meta description:** [≤155 chars]

**Primary keyword:** [keyword]

---

### 4. Cross-Product Consistency Check

| Check | Status |
|---|---|
| Voice consistent across all products | [ ] |
| No repeated opening phrases across products | [ ] |
| No keyword cannibalization between products | [ ] |
| Each product's unique differentiator is clear | [ ] |
| All platform constraints met for all products | [ ] |
| Formatting consistent (bold patterns, bullet structure) | [ ] |


path: references/description-frameworks.md
content: # Description Frameworks Reference

Copywriting frameworks for structuring product descriptions. Each framework is suited to different product types and audiences. Choose based on the product's primary selling angle.

---

## 1. AIDA — Attention, Interest, Desire, Action

### Definition
A linear persuasion sequence that first grabs attention, builds intellectual interest, creates emotional desire, then prompts action.

### Best for
New-to-market products, innovative products, products with a strong "wow factor" or visual appeal. Works well when the product's existence is the selling point.

### Structure
1. **Attention:** A bold opening that stops the scroll — a surprising fact, a provocative question, or a vivid image
2. **Interest:** Specific details that build credibility and engagement — features that matter, comparisons, technical proof
3. **Desire:** Emotional connection — how the product improves the buyer's life, social proof, aspirational imagery
4. **Action:** Clear next step — add to cart, limited availability, bonus offer, guarantee

### Ecommerce Application
- **Title:** Attention element (the hook)
- **First bullet:** Interest (the standout feature)
- **Bullets 2-4:** Desire (benefits, social proof, lifestyle connection)
- **Last bullet or CTA:** Action (urgency, guarantee, bundle offer)

### Example Snippet
**Attention:** "The kitchen timer that actually understands cooking."
**Interest:** "Three independent countdown zones with voice alerts — track your roast, pasta, and sauce simultaneously without touching a screen."
**Desire:** "Join 50,000+ home cooks who stopped burning side dishes. Rated 4.8 stars by people who cook dinner every night."
**Action:** "Order today with our 60-day no-questions-asked return policy."

---

## 2. PAS — Problem, Agitate, Solution

### Definition
Identifies a pain point the buyer experiences, intensifies the emotional weight of that problem, then presents the product as the resolution.

### Best for
Problem-solving products: health and wellness, home organization, pain relief, cleaning products, productivity tools. Any product where the buyer's motivation is escaping discomfort rather than pursuing pleasure.

### Structure
1. **Problem:** Name the specific pain point the buyer recognizes
2. **Agitate:** Amplify the problem — show its consequences, frequency, or hidden costs
3. **Solution:** Present the product as the direct answer, with proof it works

### Ecommerce Application
- **Title:** Solution-oriented (includes the benefit, not just the product)
- **First bullet:** Problem statement (connect with the buyer's frustration)
- **Bullet 2:** Agitation (why existing solutions fail, the cost of inaction)
- **Bullets 3-5:** Solution details (how this product specifically solves it, with proof)

### Example Snippet
**Problem:** "Tired of waking up with neck pain that takes hours to fade?"
**Agitate:** "Standard pillows lose their shape within months, forcing your neck into unnatural positions night after night. You spend $5,000 on a mattress but sleep on a $15 pillow that's working against you."
**Solution:** "The CerviRest Contour Pillow maintains its ergonomic shape for 3+ years with medical-grade memory foam. Designed with orthopedic input to keep your cervical spine aligned in any sleep position."

---

## 3. FAB — Feature, Advantage, Benefit

### Definition
A structured approach that connects every product feature to its competitive advantage and ultimate customer benefit. Ideal for products where specifications matter and need translation.

### Best for
Technical products, electronics, tools, equipment, cookware, sporting goods — any product where buyers compare specs but ultimately care about outcomes.

### Structure
1. **Feature:** The specific product attribute (material, dimension, technology)
2. **Advantage:** What this feature does better than alternatives
3. **Benefit:** How this translates to the buyer's experience

### Ecommerce Application
- **Each bullet point** follows the FAB sequence
- **Title:** Highlights the most compelling FAB chain
- **Long description:** Groups related FAB chains into logical sections

### Example Snippet
**Feature:** "2,500mAh rechargeable lithium battery"
**Advantage:** "Delivers 40% more runtime than standard 1,800mAh batteries in this category"
**Benefit:** "Run your power drill for a full day of deck-building without stopping to recharge"

**Bullet format:** "Build all day without recharging — the 2,500mAh lithium battery delivers 40% more runtime than standard drill batteries, giving you 6+ hours of continuous use on a single charge."

---

## 4. Before-After-Bridge

### Definition
Paints a picture of the buyer's current situation (Before), shows them the improved reality (After), then explains how the product bridges the gap.

### Best for
Lifestyle products, fashion, home decor, wellness, beauty, subscription services. Products where the emotional transformation matters more than technical specifications.

### Structure
1. **Before:** The buyer's current reality — relatable, specific, slightly uncomfortable
2. **After:** The improved reality — aspirational but believable
3. **Bridge:** The product as the connection between the two states

### Ecommerce Application
- **Short description:** Compressed Before-After-Bridge in 25-50 words
- **Long description:** Full narrative with each section as a paragraph or headed section
- **Bullets:** Each bullet can be a mini Before-After for different product aspects

### Example Snippet
**Before:** "Your morning routine is a negotiation with your closet. Nothing matches, half your clothes need ironing, and you're already running late."
**After:** "You open your closet and everything works together. Five minutes to get dressed, zero stress, and you actually like what you see in the mirror."
**Bridge:** "Our 12-piece capsule collection is designed as a system — every piece pairs with every other piece. Built from wrinkle-resistant fabrics that look polished straight from the drawer."

---

## Platform-Specific Formatting Rules

### Amazon

- **Title:** �j$200 characters. Format: Brand + Product Name + Key Feature + Size/Variant + Color
- **Bullet points:** 5 bullets, each ≤500 characters (200-250 ideal for readability). Start each with a CAPITALIZED benefit phrase
- **Product description:** ≤2,000 characters. HTML is limited (bold, line breaks). No external links
- **A+ Content:** If Brand Registered — use modules for enhanced images and comparison charts
- **Backend search terms:** 250 bytes. No commas needed, no repetition of title words
- **Prohibited:** Subjective claims without evidence, time-sensitive language ("sale", "limited"), competitor mentions, HTML in bullets

### Shopify

- **Title:** No strict limit, but �j$70 characters recommended for SEO (Google truncation)
- **Description:** Full HTML support — use `<h2>`, `<h3>`, `<ul>`, `<strong>`, `<p>` for structure
- **Meta description:** ≤155 characters, manually set or auto-generated from first paragraph
- **SEO considerations:** H1 is typically the product title. Description should use H2/H3 for subsections. First 160 characters are critical for Google snippet
- **Rich media:** Can embed video, comparison tables, size charts within description HTML

### Walmart

- **Title:** ≤75 characters ideal (≤200 max). Format: Brand + Product + Key Attribute + Size
- **Short description:** ≤500 characters, appears above the fold
- **Long description:** �j$4,000 characters, supports basic HTML
- **Key features:** Up to 10 bullet points, ≤80 characters each (shorter than Amazon)
- **Content standards:** No promotional language ("best seller"), no pricing, no competitor mentions

### Etsy

- **Title:** ≤140 characters. Keyword-rich, comma-separated attributes common
- **Description:** No HTML. Plain text with line breaks. Story-driven copy performs best
- **Tags:** 13 tags, ≤20 characters each. Multi-word phrases encouraged (long-tail keywords)
- **Style:** Handmade/personal narrative works. First-person acceptable. Emphasize craftsmanship, materials, maker story


path: references/seo-guidelines.md
content: # SEO Guidelines for Product Descriptions

Keyword and search optimization best practices for ecommerce product descriptions across major platforms. Use this reference alongside the Description Frameworks and Output Template.

---

## Keyword Research Fundamentals

### Keyword types for product descriptions

**Primary keyword:** The single most important search term for this product. Appears in the title, first bullet, and first paragraph of the long description. One per product — never split focus.

**Secondary keywords:** 3-5 supporting terms that capture related searches. Distributed across bullets and body copy. Should complement, not duplicate, the primary keyword.

**Long-tail keywords:** Specific 3-5 word phrases with lower volume but higher purchase intent. Examples: "stainless steel garlic press dishwasher safe" vs "garlic press." These convert better and face less competition.

**Semantic variations:** Synonyms and related terms that search engines associate with the primary keyword. "Running shoes" → "jogging sneakers," "athletic footwear," "trail runners." Include naturally — don't force.

### Keyword placement priority

1. **Product title** — Highest SEO weight on every platform. Primary keyword must appear here.
2. **First bullet point** — Second-highest weight. Primary keyword restated in a benefit context.
3. **First paragraph of long description** — Reinforces relevance for both platform search and Google indexing.
4. **Subsequent bullets** — One secondary keyword per bullet, naturally integrated.
5. **Meta description** — For Shopify/DTC sites. Primary keyword within first 70 characters.
6. **Image alt text** — Often overlooked. Include primary keyword + descriptive context.
7. **Backend search terms** — Amazon-specific. Use remaining keywords not in visible copy.

### Keyword density guidelines

- **Title:** 1-2 keyword instances maximum. More looks spammy.
- **Bullets (combined):** Primary keyword 1-2 times across all bullets. Each secondary keyword once.
- **Long description:** Primary keyword 2-3 times per 250 words. Secondary keywords 1-2 times each.
- **Overall density target:** 1-2% for primary keyword. Below 1% = missed opportunity. Above 3% = keyword stuffing risk.
- **Rule of thumb:** If the keyword placement feels forced when read aloud, remove one instance.

---

## Platform-Specific SEO

### Amazon Search (A9 / COSMO Algorithm)

Amazon's search algorithm ranks products based on relevance and performance.

**Relevance factors (what you control in copy):**
- Exact keyword match in title carries highest weight
- Backend search terms fill gaps without cluttering visible copy
- Bullet points are indexed — keywords here count
- Product description is indexed but weighted lower than title and bullets
- Category node selection affects which searches surface the product

**Performance factors (influenced by copy quality):**
- Click-through rate from search results — compelling titles and main images
- Conversion rate on the product page — persuasive bullets and descriptions
- Sales velocity — better copy → more sales → higher ranking (virtuous cycle)
- Review count and rating — not directly copy-related but affected by setting accurate expectations

**Amazon-specific SEO rules:**
- Do NOT repeat the brand name in backend search terms (it's already indexed from the brand field)
- Do NOT use commas in backend search terms — spaces are sufficient separators
- Backend search terms have a 250-byte limit — use every byte
- Include common misspellings in backend terms (not in visible copy)
- Include Spanish translations of key terms if selling in US market
- Avoid subjective claims ("best," "top-rated") — Amazon may suppress listings
- Do NOT include competitor brand names in any field — policy violation

**Title optimization for Amazon:**
```
[Brand] [Product Name] [Key Feature] [Size/Count] [Color/Variant]
```
- Primary keyword within first 80 characters (mobile truncation point)
- No promotional language ("Sale," "Free Shipping," "Best Seller")
- No special characters except hyphens and commas
- Capitalize first letter of each word (Title Case)

### Shopify / Direct-to-Consumer SEO

Shopify product pages are indexed by Google. Optimize for Google's algorithm.

**On-page SEO elements:**
- **Page title (H1):** Auto-set from product name. Keep ≤60 characters for full Google display.
- **Meta description:** Set manually in Shopify admin. ≤155 characters. Include primary keyword and a value proposition or CTA.
- **URL handle:** Auto-generated from title. Edit to be short and keyword-rich: `/products/merino-wool-hiking-socks` not `/products/ultra-premium-merino-wool-blend-hiking-socks-3-pack-grey`
- **Image alt text:** Describe the image AND include the primary keyword. "Merino wool hiking socks in charcoal grey — ankle height" not "product-image-001"
- **Structured data:** Shopify auto-generates Product schema. Verify it includes price, availability, and review data using Google's Rich Results Test.

**Content structure for Google:**
- Use H2 and H3 tags in the product description (Shopify supports full HTML)
- First 160 characters of the description may appear as Google's snippet — front-load value
- Internal links to related products help Google understand site structure
- Unique descriptions for every product — duplicate content hurts rankings

**Technical SEO checklist:**
- Page load speed under 3 seconds (compress images, minimize scripts)
- Mobile-responsive layout (Google uses mobile-first indexing)
- Canonical URLs set correctly for variant pages
- No blocked resources in robots.txt that prevent Google from rendering the page

### Walmart SEO

Walmart's search algorithm (similar to Amazon's) weighs:
- **Title relevance:** Primary keyword in title is essential
- **Content quality score:** Walmart rates listings on completeness. Fill all available fields.
- **Rich media:** Listings with video and enhanced content rank higher
- **Price competitiveness:** Walmart factors price into ranking more heavily than Amazon

**Walmart-specific rules:**
- Shorter titles preferred (≤75 characters ideal)
- Key features limited to 80 characters each — be concise
- No promotional language, pricing info, or competitor mentions
- Walmart Content Quality Score visible in Seller Center — aim for 95%+

### Etsy SEO

Etsy search uses a different model focused on relevance, listing quality, and recency.

**Etsy-specific optimization:**
- **Tags:** 13 tags available, each ≤20 characters. Use all 13. Multi-word phrases preferred over single words.
- **Title:** First 40 characters matter most. Front-load primary keyword.
- **Categories and attributes:** Selecting the most specific category improves relevance.
- **Listing renewal:** New and renewed listings get a temporary search boost.
- **Shop sections:** Organizing products into sections helps Etsy understand your catalog.

**Tag strategy:**
- Use long-tail phrases: "personalized leather wallet" not "leather" + "wallet" + "personalized" as separate tags
- Include gift-related tags if applicable: "gift for him," "anniversary gift"
- Mix broad and specific: "kitchen decor" (broad) + "ceramic spoon rest blue" (specific)
- Check Etsy's search bar autocomplete for real buyer search terms

---

## Keyword Cannibalization Prevention

When writing descriptions for multiple products in the same catalog:

- **Each product gets a unique primary keyword.** No two products should target the exact same primary keyword.
- **Map keywords before writing.** Create a keyword-to-product assignment table. Review for overlaps.
- **Differentiate by modifier:** If two products are similar, differentiate keywords by size, color, use case, or audience. "Women's running shoes" vs "Men's trail running shoes."
- **Use the Keyword Integration Map** (from the output template) to document placement and prevent accidental overlap.
- **Check existing catalog first.** Before assigning keywords to a new product, verify no existing product already targets that term.

---

## Content Quality Signals

Search algorithms increasingly evaluate content quality beyond keyword matching.

### Readability
- Write at a 6th-8th grade reading level for general consumer products
- Shorter sentences (≤20 words) perform better in bullets
- Avoid jargon unless the target audience expects it (e.g., technical products for professionals)
- Use active voice: "Cuts cooking time in half" not "Cooking time is reduced by half"

### Specificity over generality
- "Holds 24 oz" outperforms "Large capacity"
- "Machine washable at 140°F" outperforms "Easy to clean"
- Numbers, measurements, and concrete details signal quality to both algorithms and buyers

### Freshness
- Update product descriptions quarterly or when significant changes occur
- Refresh seasonal keywords before relevant shopping periods
- Update competitor-facing language when market positioning shifts

### User-generated content integration
- Reference review themes in descriptions: "Rated 4.8 stars for durability by 2,000+ customers"
- Address common review complaints proactively in the description
- Use the language buyers use in reviews — it's natural keyword research

---

## Common SEO Mistakes in Product Descriptions

1. **Keyword stuffing** — Repeating the same keyword 8+ times in a 200-word description. Hurts readability and may trigger penalties.
2. **Duplicate descriptions** — Using the same description across multiple products or platforms. Each listing needs unique copy.
3. **Ignoring backend fields** — Amazon backend search terms left empty means lost keyword coverage.
4. **Title keyword at the end** — Placing the primary keyword at position 150+ in a 200-character title. It gets truncated on mobile and loses SEO weight.
5. **Generic alt text** — "Product image" instead of "Stainless steel French press coffee maker 34oz." Lost image search traffic.
6. **Optimizing for the wrong keyword** — Targeting a high-volume keyword that doesn't match purchase intent. "Coffee" has volume; "French press coffee maker 34 oz stainless steel" has buyers.
7. **Neglecting mobile formatting** — Long paragraphs that work on desktop become walls of text on mobile. Use short paragraphs and bullets.
8. **Static keyword strategy** — Setting keywords once and never updating. Search trends shift seasonally and competitively.


path: assets/quality-checklist.md
content: # Product Description Writer — Quality Checklist

Use this checklist before delivering any product description output.

---

## Content Quality (9 items)

- [ ] Every bullet leads with a benefit, not a feature
- [ ] No bullet starts with the product name or brand name
- [ ] All claims are specific — no vague adjectives ("great," "amazing," "high-quality") without proof
- [ ] Numbers and measurements used wherever possible (dimensions, weights, capacities, percentages)
- [ ] No two bullets convey the same benefit in different words
- [ ] Short description is 25-50 words and stands alone as a compelling pitch
- [ ] Long description follows the selected framework structure (AIDA / PAS / FAB / BAB)
- [ ] Long description is 150-300 words
- [ ] All product claims are supportable — nothing the seller couldn't prove if challenged

## SEO Compliance (8 items)

- [ ] Primary keyword appears in the title
- [ ] Primary keyword appears in the first bullet point
- [ ] Primary keyword appears in the first paragraph of the long description
- [ ] Each secondary keyword appears at least once in the body copy
- [ ] Keyword density is 1-2% for primary keyword (not over-stuffed)
- [ ] Meta description is ≤155 characters and includes primary keyword
- [ ] No keyword cannibalization with other products in the same catalog
- [ ] Keyword Integration Map completed with all placements documented

## Brand Voice (6 items)

- [ ] Tone matches brand guidelines (if provided) or product positioning
- [ ] Consistent voice across all sections (title, bullets, descriptions)
- [ ] No competitor names mentioned anywhere in the copy
- [ ] No superlative claims without evidence ("best," "most," "#1")
- [ ] Language matches target audience sophistication level
- [ ] Brand name used correctly (spelling, capitalization, trademark symbols if required)

## Technical Accuracy (7 items)

- [ ] All product specifications verified against source data
- [ ] Materials, dimensions, and weights match product listing data
- [ ] Compatibility claims checked (fits Model X, works with System Y)
- [ ] Country of origin correctly stated if included
- [ ] Warranty and guarantee terms match actual policy
- [ ] Care instructions are accurate for the material/product type
- [ ] No claims that could create liability (medical, safety, regulatory)

## Platform Compliance (8 items)

- [ ] Title length within platform limit (Amazon ≤200, Shopify ≤70 recommended, Walmart ≤75, Etsy ≤140)
- [ ] Bullet count matches platform standard (Amazon: 5, Walmart: up to 10)
- [ ] Bullet character length within platform limit (Amazon ≤500, Walmart ≤80)
- [ ] No prohibited language for the target platform (check platform-specific rules)
- [ ] HTML formatting used only where platform supports it (Shopify/Walmart long desc: yes; Etsy: no)
- [ ] Backend search terms provided for Amazon listings (≤250 bytes)
- [ ] Product description length within platform limit
- [ ] Image alt-text suggestions provided if requested

## Formatting (5 items)

- [ ] Consistent bold pattern across all bullets (benefit phrase bolded)
- [ ] No orphan bullets (every bullet has both a benefit headline and supporting detail)
- [ ] Paragraphs in long description are ≤4 sentences each
- [ ] No walls of text — appropriate line breaks and structure
- [ ] Tables render correctly (Product Summary table, Keyword Integration Map)

## Batch-Specific Checks (7 items — Mode B only)

- [ ] Brand voice consistent across all products in the batch
- [ ] No repeated opening phrases across products
- [ ] No keyword cannibalization between products in the batch
- [ ] Each product's unique differentiator is clearly communicated
- [ ] Shared bullet structure pattern followed by all products
- [ ] Cross-Product Consistency Check table completed
- [ ] All products meet every platform constraint

---

**Total items: 50** (43 for Mode A, 50 for Mode B)
**Minimum passing: 40/43 (Mode A) or 45/50 (Mode B)**


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)