SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsecommerce.listing-keyword-optimizer

ecommerce.listing-keyword-optimizer

Marketing & growth

View repository

Updated 10-16 01:36

About this skill

📖 Analysis Philosophy: Think First, Then Fetch

IMPORTANT — Working Directory: All scripts in this skill MUST be executed with the working directory set to the absolute path of the directory containing this SKILL.md file (the skill root directory). Always cd into this directory before running any command. Do NOT use relative paths or shell shortcuts like ~ in paths, as they may not be resolved by the execution environment.

Listing Keyword Optimizer

Product Understanding Step

Before running this skill, if the user provides a product, image, ASIN, listing, product ID, or product idea, first identify:

  • product type/category
  • main use case
  • key physical, design, or functional features
  • target marketplace, country, or platform
  • user's analysis goal

Use this product understanding to choose parameters, filters, competitors, regions, keywords, or analysis dimensions before executing the script.

Core Question

— What keywords should I use in my listing, and where should they go?

When to Use

  • User asks "what keywords for my listing"
  • User wants to optimize title/bullets/description
  • User mentions "listing optimization" or "keyword": " placement"
  • User has a product and needs keyword strategy
  • User asks about "backend search terms"

Differs From / Not Applicable

  • Use keyword-research, keyword-opportunity-finder, or keyword-reverse-lookup to discover keywords first.
  • Use this skill when the user wants keywords assigned to title, bullets, description, or backend terms.
  • Do not use for market sizing, ranking tracking, or competitor business metrics.

Data Sources

Source Endpoint Purpose
Jungle Scout /api/v1/tools/jungle-scout/keywords/by-keyword Keyword expansion, volume, difficulty
Jungle Scout /api/v1/tools/jungle-scout/keywords/by-asin Competitor keyword reverse lookup
Amazon Search /api/v1/tools/research/amazon/search Product data, competitor listings
ABA (Amazon Brand Analytics) /api/v1/tools/research/aba/intelligentQuery Search Frequency Rank validation

Parameters

Parameter Type Required Default Description
keyword string Yes* - Main product keyword
asin string Yes* - Target ASIN (yours or competitor)
marketplace string No Target marketplace
category string No auto Product category for context
product_title string No auto from ASIN Product title when the user provides listing/product context
product_description string No - Product description or short brief for relevance filtering
features / product_features array No - Key product attributes, materials, use cases, or design features
target_audience string No - Intended buyer or usage audience
product_brand string No auto from ASIN Own brand; excluded from competitor brand filtering
max_title_chars int No 200 Max title length
bullet_count int No 5 Number of bullet points
brand_blocklist array No auto-detect Competitor brand names to exclude from title
bullet_features object No auto-detect Custom bullet grouping {name: [signal_words]}
min_relevance int No 25 Minimum product relevance score for keyword inclusion

*Either keyword or asin required

Brand Blocklist (for brand_blocklist parameter)

Both brand_blocklist and bullet_features auto-detect from competitor data when not provided:

  • brand_blocklist: Extracts brand names from competitor listings' brand field
  • bullet_features: Detects product category (skincare/electronics/fitness/general) from keyword + titles, then uses category-specific bullet groupings

Agent can override either for fuller coverage.

Example (wireless earbuds with custom brands):

python3 scripts/listing_keyword_optimizer.py '{"keyword": "wireless earbuds", "brand_blocklist": ["apple", "airpods", "samsung", "sony", "bose", "jabra", "beats", "jbl", "anker", "tozo", "raycon"]}'

Output Structure

The output will be a structured markdown report, following this format:

Listing Keyword Optimization Report: [Keyword or ASIN]

1. Executive Summary

  • Main Keyword: [main_keyword]
  • Analyzed ASIN: [asin] (if provided)
  • Analysis Market: [market]
  • Analysis Date: [analysis_date]
  • Product Category: [product_context.category]
  • Core Insight: [insights.summary]

2. Title Keyword Recommendations

  • Suggested Title: [title_keywords.suggested_title]
  • Character Count: [title_keywords.char_count] (Mobile Preview: [title_keywords.mobile_preview])
  • Keyword Classification:
Priority Keyword Search Volume
Must Have [title_keywords.must_have[0].keyword] [title_keywords.must_have[0].volume]
Should Have [title_keywords.should_have[0].keyword] [title_keywords.should_have[0].volume]
Nice to Have [title_keywords.nice_to_have[0].keyword] [title_keywords.nice_to_have[0].volume]

3. Bullet Point Keyword Recommendations

  • Suggested Bullet Points and Keywords:
Bullet No. Feature Suggested Keywords (Top 3) Search Volume (Example)
1 [bullet_keywords.bullet_1.feature] [bullet_keywords.bullet_1.keywords[0].keyword], [bullet_keywords.bullet_1.keywords[1].keyword] [bullet_keywords.bullet_1.keywords[0].volume]
2 [bullet_keywords.bullet_2.feature] [bullet_keywords.bullet_2.keywords[0].keyword], [bullet_keywords.bullet_2.keywords[1].keyword] [bullet_keywords.bullet_2.keywords[0].volume]
... ... ... ...
(Showing all bullet point recommendations, up to 3 keywords per bullet with example search volume)

4. Description Keyword Recommendations

  • Long-tail and Supplementary Keyword Examples:
Keyword Type Example Keyword Search Volume (Example)
Long-Tail [description_keywords.long_tail[0].keyword] [description_keywords.long_tail[0].volume]
Supplementary [description_keywords.supplementary[0].keyword] [description_keywords.supplementary[0].volume]

5. Backend Search Terms Recommendations

  • Backend Term Status:
Type Keywords
Recommended [backend_terms.recommended]
Misspellings [backend_terms.misspellings]
To Avoid [backend_terms.avoid]
  • Byte Usage: [backend_terms.bytes_used] bytes used, [backend_terms.bytes_remaining] bytes remaining

6. Keyword Coverage Analysis

  • Keyword Allocation and Coverage:
Section Keywords Covered Percentage of Total Keywords
Total Keywords [keyword_map.total_keywords] 100%
Title [keyword_map.title_coverage] [Calculated Percentage]%
Bullet Points [keyword_map.bullet_coverage] [Calculated Percentage]%
Description [keyword_map.description_coverage] [Calculated Percentage]%
Backend Search Terms [keyword_map.backend_coverage] [Calculated Percentage]%

7. Competitor Analysis Insights

  • Competitors Analyzed: [competitor_analysis.titles_analyzed]
  • Common Phrases in Competitors: [competitor_analysis.common_phrases]
  • Common Words in Competitors: [competitor_analysis.common_words]

8. Amazon Brand Analytics (ABA) Validation

  • Search Frequency Rank (SFR): [aba_validation.search_frequency_rank]
  • Search Volume Tier: [aba_validation.search_volume_tier]

9. Actionable Recommendations

  • [First recommendation from insights.recommendations]
  • [Second recommendation from insights.recommendations]
  • ... (Listing all key recommendations)

10. Attached Visualizations

  • Keyword Priority Matrix
  • Placement Allocation
  • Coverage Analysis
  • Competitor Comparison

Default Practical Output

The script also returns a compact listing_copy object for direct use:

{
  "listing_copy": {
    "title": "Readable Amazon-style title",
    "bullets": ["Bullet 1", "Bullet 2", "Bullet 3", "Bullet 4", "Bullet 5"],
    "backend_search_terms": "space separated backend terms"
  },
  "self_check": {
    "status": "PASS or REVIEW",
    "warnings": []
  }
}

Keyword Placement Strategy

Title (Most Important)

  • Characters: 150-200 max (mobile truncates at ~80)
  • Priority: Highest volume + most relevant
  • Rule: Main keyword FIRST, then modifiers
  • Avoid: Keyword stuffing, ALL CAPS, special characters

Bullet Points (Feature-Focused)

  • Characters: ~500 per bullet
  • Priority: Feature + benefit keywords
  • Rule: One main keyword per bullet, natural flow
  • Pattern: FEATURE - Benefit - Keywords

Description (Long-Tail)

  • Characters: 2000 max
  • Priority: Long-tail, semantic variations
  • Rule: Natural sentences, storytelling
  • Avoid: Duplicate title keywords

Backend Search Terms

  • Characters: 250 bytes
  • Priority: Misspellings, synonyms, Spanish terms
  • Rule: No repeats from title/bullets
  • Avoid: Brand names, ASINs, subjective claims

⚠️ MANDATORY: Charts & Display Rules

  1. Generate charts by default for full analytical reports — use --chart with an output directory unless the user asks for a quick text-only result or chart data is unavailable.
  2. Send generated charts to the user — when charts are created, share all chart PNGs immediately.
  3. All chart styling is driven by ecommerce_chart_helpers.py which reads from chart_style.json (derived from references/display-rules.md). Do NOT hardcode colors in scripts.

Usage

# By keyword
python3 scripts/listing_keyword_optimizer.py '{"keyword": "yoga mat"}'

# By ASIN (reverse engineer competitor)
python3 scripts/listing_keyword_optimizer.py '{"asin": "B07RL88DD2"}'

# With category context
python3 scripts/listing_keyword_optimizer.py '{"keyword": "yoga mat", "category": "Sports"}'

# With product understanding context
python3 scripts/listing_keyword_optimizer.py '{
  "keyword": "dive bag",
  "product_title": "Mesh scuba gear bag for fins and snorkel equipment",
  "features": ["mesh drainage", "large fin compartment", "shoulder strap"],
  "target_audience": "recreational scuba divers",
  "brand_blocklist": ["YETI", "TYR"]
}'

# Generate charts
python3 scripts/listing_keyword_optimizer.py '{"keyword": "yoga mat"}' --chart /tmp/charts

Charts Generated

  1. Keyword Priority Matrix — Volume vs Difficulty scatter
  2. Placement Allocation — Where each keyword goes
  3. Coverage Analysis — Keyword distribution across sections
  4. Competitor Comparison — Your coverage vs top competitors

Workflow

┌─────────────────────────────────────────────────────────────┐
│ 1. INPUT: keyword, ASIN, or product context │
│ 1.5 UNDERSTAND: Fetch ASIN detail or use provided title/features/audience │
│ 2. EXPAND: Get related keywords from Jungle Scout │
│ 3. VALIDATE: Check competitor listings and detect competitor brands │
│ 4. FILTER: Remove off-product and competitor-brand keywords │
│ 5. CATEGORIZE: Title / Bullet / Description / Backend │
│ 6. GENERATE: Readable title, bullet copy, backend terms │
│ 7. REVIEW: Check readability, brand conflicts, and relevance drift │
│ 8. OUTPUT: Compact listing copy + detailed keyword analysis │
└─────────────────────────────────────────────────────────────┘

If the review step flags brand conflicts or low-relevance visible keywords, revise filters and rerun before giving final listing copy.

Insights Generated

  • 🎯 Must-have keywords (high volume, high relevance)
  • 💎 Hidden gems (medium volume, low competition)
  • ⚠️ Over-competitive keywords to de-prioritize
  • 📈 Trending keywords to include
  • 🚫 Keywords to avoid (irrelevant, trademarked)

Limitations

  • Amazon title limits vary by category (check Seller Central)
  • Backend terms have strict byte limits
  • Some keywords may be restricted in certain categories
  • A+ Content keywords not indexed (description replacement)
  • Keyword indexing can take 24-48 hours

Environment Variables

Variable Required Description
NEXSCOPE_PROXY_BASE Yes NexScope proxy base URL
NEXSCOPE_API_KEY Yes NexScope proxy API key

References

  • references/amazon-listing-guidelines.md — Official Amazon rules
  • references/keyword-placement-best-practices.md — Placement strategies
  • references/display-rules.md — Output formatting rules