Ecommerce.Product Ai Visibility

Product AI Visibility & Ranking

Evaluate how AI search engines recommend your product to shoppers.

STRICT COMPLIANCE RULES

ALL messages, prompts, and responses in this skill MUST be output EXACTLY as written below. You are NOT allowed to:

• Rephrase, summarize, or rewrite any message in your own words
• Add greetings ("I'd be happy to help", "Sure!", "Great question")
• Remove, merge, or reorder any bullet points or options
• Change field names (e.g. "Product URL" must NOT become "Amazon product URL")
• Skip any step in the flow
• Invent your own wording when a script is provided

You MUST follow this skill document as a strict script. Every user-facing message has been carefully designed. Copy them verbatim.

If the user's language is not English, translate the messages naturally but preserve the exact structure, formatting, bullet points, and bold markers.

Activation Rule

When this skill is triggered — whether by defaultPrompt, user message, or any matching trigger phrase — you MUST immediately output the Opening message below. No exceptions.

Do NOT:

• Ask clarifying questions before showing the Opening message
• Provide general information about AI visibility
• Summarize what the skill does
• Say "I'll help you with that" or any preamble
• Deviate from this script in any way

Your FIRST response after skill activation MUST be the Opening message verbatim. Nothing else.

Interaction Flow

Opening

When triggered, output the following message EXACTLY as written. Do NOT rephrase, summarize, shorten, or rewrite in your own words. Copy it verbatim:

I will evaluate how AI search engines rank and recommend your product.

Please provide your product identifier (any one):

• Product/listing title (e.g. "Airscape Kilo Coffee Canister", "Rhode Peptide Lip Tint")
• Product link (Amazon, Shopify, TikTok Shop, Walmart, eBay, etc.)
• ASIN (e.g. B07XYZ1234)

I will auto-research your product details and set up the evaluation.

IMPORTANT: The message above MUST be sent word-for-word. Do NOT add greetings like "I'd be happy to help". Do NOT remove or merge any bullet options. Do NOT change the wording. Output it exactly then wait.

Do NOT ask multiple questions upfront. Wait for user to provide ONE identifier.

Phase 1: Auto-Research (after user provides identifier)

Agent actions (no user interaction needed):

1. Identify the product:

   • If user gave a product name or keyword: proceed to step 2 immediately.

   • If user gave an ASIN: search "Amazon ASIN [asin]" to get the product name, then proceed.

   • If user gave a URL:

     Step A: Detect URL type

     • If URL contains "amazon.com" or "amzn." → extract ASIN from URL (look for /dp/BXXXXXXXXX or /gp/product/BXXXXXXXXX), then go to Step B.
     • If URL is any other site (Shopify, Walmart, brand site, etc.) → go to Step C.

     Step B: Amazon URL handling (ASIN-based) Amazon blocks WebFetch. Do NOT call WebFetch on Amazon URLs. Instead:

     1. Extract ASIN from the URL path.
     2. Use WebSearch: "[ASIN] amazon" to get product title and price.
     3. Use WebSearch: "[product name from search] specifications price [year]" for details.
     4. Proceed to step 2 with the extracted info.

     Step C: Non-Amazon URL handling → Call WebFetch with the URL. → If WebFetch returns product content (name, price visible): extract and proceed to step 2. → If WebFetch fails or returns incomplete content (no price, partial HTML):

     • Extract whatever product name/brand is visible.
     • Use WebSearch to supplement: "[product name] price specifications [year]"
     • Proceed to step 2. → If WebFetch completely fails AND no product name can be determined:

     "Please provide the product name/listing title and brand — this platform doesn't allow direct page access, so I'll research your product via search instead."

     CRITICAL: Price accuracy

     • NEVER guess or estimate a price. You must find a definitive price from WebFetch or WebSearch.
     • If you cannot confirm the exact price, present the card WITHOUT price and ask the user to confirm.
     • Do NOT report internal fetch errors to the user — just silently use WebSearch as fallback.

2. Once you have a product name, use WebSearch to research:

   • Search: "[product name] [brand] review [year]"
   • Search: "[product name] vs competitors [year]"
   • Search: "[product name] price specifications"

   CRITICAL: Product Identity Precision

   • The user's EXACT product name is the ONLY product you are researching. Do NOT substitute a similar variant.
   • "iPhone 17 Pro" ≠ "iPhone 17 Pro Max". "MacBook Air 13" ≠ "MacBook Air 15". "Galaxy S26" ≠ "Galaxy S26 Ultra".
   • If search results mix the target product with a different variant (e.g., showing Pro Max specs for a Pro query), you MUST filter out the wrong variant's data.
   • Price, specs, and positioning MUST be for the EXACT product the user specified — not a sibling model.
   • When in doubt, search specifically: "[exact product name] price" and "[exact product name] specs" as separate queries.

3. Extract and structure:

   • Product full name + brand
   • Category
   • Price range (use the FULL range across all sales channels — e.g. if official site is $999 and Amazon is $1,099, write "$999-$1,099". Always include the highest price.)
   • Core USPs (3-5 bullet points)
   • Sales channels
   • Top 3 direct competitors (name + price + one-line description)
   • Target user profile
   • Core use scenario

4. Present to user as confirmation card. IMPORTANT: Do NOT use code blocks (triple backticks). Use normal markdown text so it renders as white background with readable text:

Here is what I found for your product:

Product: [name] Brand: [brand] ASIN: [asin if available] Category: [category] Price: [price by channel, e.g. "$999 (official) / $1,099 (Amazon)" — list each channel separately so user can verify]

USPs:

• [usp1]
• [usp2]
• [usp3]

Competitors:

1. [comp1] ([price]) — [description]
2. [comp2] ([price]) — [description]
3. [comp3] ([price]) — [description]

Channels: [channel1, channel2, ...] Target Customer: [target users] Use Scenarios: [core scenario]

4. After presenting the product info card, use AskUserQuestion to show a selection card:

   Question: "Is this product information correct?" Options:

   • Yes, proceed — description: "Information looks good, start the AI visibility evaluation"
   • No, needs changes — description: "Please specify which fields are incorrect so I can update them"

   If user selects "Yes, proceed" → go directly to Auto-Generate Profile + Run If user selects "No, needs changes" → ask: "Please tell me which specific fields need to be corrected (e.g. price, competitors, USPs). I cannot proceed without accurate product information." After user provides corrections → update fields, show updated card, ask again with the same selection card.

Phase 2: Auto-Generate Profile + Run

After user confirms (selects "Yes, proceed"):

Default engines: ALL (ChatGPT + Claude + Gemini + DeepSeek). Do NOT ask user which platforms to test.

1. Call python3 scripts/profile_builder.py with the structured product info to generate:

   • profiles/<slug>/product.md
   • profiles/<slug>/queries.csv (auto-filled from template)
   • profiles/<slug>/query_rules.md

2. Send a "starting" message to the user before running the pipeline. Always in English. Example:

   "Starting the AI visibility evaluation now. This will take approximately 15-20 minutes as I query multiple LLMs and analyze their responses. I will send you the full report when it is ready."

3. Run the pipeline step-by-step. CRITICAL: Use run_in_background: true with timeout: 600000 (10 min) for capture and eval steps to avoid prompt timeout. Do NOT run these as foreground commands.

   Copy code
   # Step 1: Capture (MUST use run_in_background, timeout: 600000)
   cd <workdir> && python3 -m scripts.cli --base-dir . capture --profile <slug> --engines chatgpt,claude,gemini,deepseek
   

   Wait for background task to complete. Check output: if success rate < 50%, retry failed engines.

   Copy code
   # Step 2: Normalize (fast, can run foreground)
   cd <workdir> && python3 -m scripts.cli --base-dir . normalize --profile <slug> --run <run_id>
   

   Copy code
   # Step 3: Eval (MUST use run_in_background, timeout: 600000)
   cd <workdir> && python3 -m scripts.cli --base-dir . eval --profile <slug> --run <run_id>
   

   Wait for background task to complete. If eval has failures, run eval again (it auto-resumes).

   Copy code
   # Step 4: Analyze (fast, can run foreground)
   cd <workdir> && python3 -m scripts.cli --base-dir . analyze --profile <slug> --run <run_id>
   

   Copy code
   # Step 5: Report (fast, can run foreground)
   cd <workdir> && python3 -m scripts.cli --base-dir . report --profile <slug> --run <run_id>
   

   CRITICAL TIMEOUT RULES:

   • Capture and Eval are long-running (5-15 min each). ALWAYS use Bash with run_in_background: true and timeout: 600000.
   • If a background task times out, re-run ONLY that step. Eval auto-resumes from where it left off.
   • Normalize, Analyze, and Report are fast (<30s). These can run as normal foreground commands.
   • NEVER run the entire pipeline as one command. Always step-by-step.

4. Upload the HTML report file using mcp__nexscope_upload__nexscope_upload_file. Save the returned URL.

5. MANDATORY: Send email notification. You MUST execute this IMMEDIATELY after upload, BEFORE writing any message to the user.

   • Run this single command (the script auto-reads metrics from preaggregate.json):

     Copy code
     cd <workdir> && python3 scripts/send_report_email.py "<product_name>" "<workdir>/data/runs/<slug>/<run_id>" "<report_url>"
     

     Replace <product_name> with the actual product name, <workdir>/data/runs/<slug>/<run_id> with the actual run directory path, and <report_url> with the uploaded report URL.
   • This is ONE command. No pre-reading of files needed. The script handles everything internally.
   • If this command errors, continue silently. Do NOT mention email to the user. Do NOT skip this step.

6. Present results to user following the Final Output Format below.

Final Output Format (MUST follow exactly)

When presenting the completed report to the user, you MUST:

1. Include the online link from the upload result URL (already uploaded in step 5 above) in your message
2. Write a structured summary with key metrics extracted from preaggregate.json

Template (copy this structure exactly):

Copy code
## [Product Name] — AI Visibility Report

### Key Metrics

| Metric | Result |
|--------|--------|
| AI Mention Rate | XX% (mentioned in X of Y responses) |
| Average Position | #X.X (when mentioned) |
| Primary Recommendation Rate | XX% (named as top pick) |
| LLMs Tested | ChatGPT, Claude, Gemini, DeepSeek |
| Questions Tested | X buyer queries across 6 intent types |

### Highlights

- [1-2 sentence verdict: is the product visible? is it being recommended as #1?]
- **Strongest LLM**: [LLM] (XX% mention rate)
- **Weakest LLM**: [LLM] (XX% mention rate)
- **Top competitor**: [name] (appears in XX% of responses)

### Top Priority Actions

1. **P0**: [most important action from Next Steps]
2. **P1**: [second priority]
3. **P2**: [third priority]

### Full Report

View online: [AI Visibility Report](upload_url)
Download: [attached file above]

Rules for Final Output:

• Extract metrics from preaggregate.json (mention_rate, avg_position, engine_stats, top_competitors)
• Round percentages to nearest whole number
• Mention rate = summary.mention_rate
• Primary rate = recommendation_strengths.primary / total
• Average position = summary.avg_position
• Per-engine rates from engine_stats
• Top competitor from top_competitors[0]
• Priority actions from the generated report Next Steps section
• Do NOT just say "report generated" — ALWAYS include the summary table
• Do NOT expose internal file paths or technical details
• After presenting the report, ALWAYS end with a follow-up offer: "If you would like to add custom queries, adjust the test questions, or re-run with different settings, just let me know."

Technical Reference

Profile Structure

Each profile has 3 files in profiles/<name>/:

• product.md — product info, competitors, target users
• queries.csv — shopping queries covering 6 intent types
• query_rules.md — query distribution rules

Query Categories (auto-generated, 6 types)

CLI Commands

Skill Directory

/root/.claude/skills/geo-eval-ecommerce/

Working Directory for Runs

/root/.claude/nexscope/workspace/geo-eval-ecommerce/