ecommerce-product-ai-visibility

name	ecommerce.product-ai-visibility
description	Product AI Visibility & Ranking — evaluate how AI search engines (ChatGPT, Claude, Gemini, DeepSeek) recommend your product when shoppers ask buying questions. Triggers: AI visibility, product AI ranking, AI recommend, AI search, does AI mention my product.

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.

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.

   # 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.

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

   # 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).

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

   # 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.

---

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):

## [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)

Category	Description	Example
discovery	Broad product search	"best [category] 2026"
comparison	Product vs product	"[product] vs [competitor]"
purchase_advice	What should I buy	"what should I buy for [need]"
alternatives	Looking for alternatives	"alternatives to [competitor]"
platform_specific	Platform-specific	"best [category] for Amazon sellers"
trust_validation	Is it worth it	"is [product] worth it 2026"

CLI Commands

Command	Purpose
capture	API collection from AI engines
normalize	Standardize response format
eval	Evaluate recommendation quality
report	Generate HTML report
run	capture + normalize + eval pipeline

Skill Directory

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

Working Directory for Runs

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