Amazon Keyword Alignment Diagnostic [CLAUDE/AGENT SKILL]
Type an ASIN and a target keyword. Get back a structured diagnostic telling you exactly how aligned your listing is with that keyword (i.e. how SEMANTICALLY SIMILAR IT IS) - and which specific phrases to fix.Most "keyword tools" you can buy fall into two camps. The cheap ones (Helium 10, Jungle Scout) tell you "use the keyword more often." Useful but mechanical. The expensive ones tell you "your listing is misaligned" but the diagnosis is opaque: what does misaligned mean, and what specifically should you change?This skill takes the second approach but makes it specific and actionable. It turns your listing (and competitor listing) text into vector embeddings and calculates their vector similarity with the search term (and each other for top three competitors). Every finding ties back to a concrete distance number and a specific phrase in your title or bullets.Your AI agent reads the results, cross-references the segment distances with the phrase-level diagnosis, and tells you "Bullet 3 talks about installation kit contents but doesn't mention the keyword - consider leading with 'screen protector for iphone' and putting the kit details in bullet 4 or 5." That's an action plan.What it producesGive it an ASIN + keyword. The skill:1. Fetches your listing (title, bullets, description) from Real-Time Amazon Data via RapidAPI2. Fetches the current top organic search results for the keyword3. Picks the top 3 competitors (excluding you)4. Embeds the keyword + every listing's text via Qwen3-Embedding-8B5. Computes per-segment cosine distances (title, bullets, description, whole)6. Builds a rank-vs-distance dot plot of the SERP7. Computes top-3 cluster tightness (how hard is it to break in?)8. Runs a leave-one-out test on every phrase in your title and bullets - which ones pull toward the keyword, which pull away?The output is a self-contained HTML report + a structured JSON summary. The HTML is meant to be opened in your browser; the JSON is meant for your AI agent to translate into a plain-English diagnosis.Here's what the report containsHeader - Status pill (ALIGNED / DRIFTING / MISALIGNED), your ASIN, your current rank (or "not in top 16" warning), top-3 competitor ASINs, and per-segment distance bars.Where you sit on the search results page - A dot plot of every listing on Amazon's first page, positioned by their semantic distance to the keyword (x-axis) and SERP rank (y-axis). Your listing is the blue star, top 3 are green, the rest are gray. The best spot is top-left (high rank, close to keyword).How your title and bullets compare to the top 3 - Horizontal bars of distance per segment, head-to-head. Look for red rows where your listing is the worst.How hard is it to break into the top 3? - Cluster tightness verdict in plain English: OPEN PLAYING FIELD / MODERATE COMPETITION / LOCKED DOWN. (A LOCKED DOWN verdict means the top 3 are saying almost the same thing - wording alone won't crack it.)What each part of your listing is doing - Per-phrase leave-one-out test. Each phrase gets a Helps / Hurts / Neutral label with the impact number. So you know exactly which bullet to rewrite and why.What makes this differentThe same embedding-based alignment score that drives the report is what large e-commerce ranking systems use internally. Amazon's catalog uses BERT-style embeddings; Google's shopping graph uses similar semantic matching. This skill makes that signal accessible without shipping your data to anyone.Two output layers:Self-contained HTML report — visual, ready to share with your team or paste into a Slack thread. Base64-embedded charts, no external assets, works offline.Structured JSON for the AI agent — every section is a typed field your agent reads, cross-references, and turns into specific copy recommendations. The pipeline provides the evidence; the agent makes the judgments.What you do with itDiagnose a stuck listing. Run the diagnostic for a keyword you know you should rank for. See whether the problem is alignment (your listing is genuinely off-topic for the keyword) or something else (the top 3 are tighter than you, your listing isn't even on page 1, the cluster is locked down by reviews and price).Find the hurting phrases. The phrase-level diagnosis points to specific title and bullet phrases that are pulling your listing away from the keyword. Test rewriting them - re-run the diagnostic - see if the distance drops.Pre-launch copy QA. Before you ship a new variant, run the diagnostic against the keyword you want to own. Catch the misalignment before it costs you weeks of ranking time.Compare variants. Re-run after every copy edit. The semantic distance number tells you whether you're getting closer to the keyword or further. Tighten the loop between writing and measuring.Audit a competitor's listing. Run the diagnostic against a competitor's ASIN for the keyword they rank for. See which phrases they're using that you're not. (The skill accepts any ASIN, not just ones you own.)Why it isn't a SaaSIt's an AI Agent skill. Runs on your computer. You bring two API keys:- RapidAPI / Real-Time Amazon Data - Amazon listing + SERP data. Free tier gives ~20 diagnostics/month; paid tier ($25/month) covers hundreds.- OpenRouter - embeddings only (Qwen3-Embedding-8B by default). Pay-as-you-go: a typical diagnostic costs about three-tenths of a cent. $5 lasts most sellers months.No subscription. No data leaves your machine except the API calls themselves. One-time purchase.If you're paying $50–100/month for a keyword tool and still don't know which specific bullet is hurting you, this pays itself back in the first hour.What's in the zipPython source with MIT-style license - modify it, fork it. AGENT.md is a step-by-step install runbook your AI assistant reads and executes; you don't run any commands in a terminal, you just paste API keys when prompted. HUMAN.md lists what you can ask once it's installed. INSTALL.md is the quick reference if you'd rather do it yourself. HTML reports are written to ~/.amz-nsr/reports/ so you have a permanent diagnostic history on your machine.Setup is about three minutes plus key creation. Most of that is your AI agent copying files and confirming your keys work.What you needPython 3.10+, an AI coding agent (Claude Code is the primary target; ChatGPT Codex, OpenCode, Google Antigravity, Cursor, Cline, Continue, and Aider also work - the install script detects your host and adapts), a RapidAPI account with Real-Time Amazon Data subscription, and an OpenRouter account with a few dollars of credits. Windows, macOS, Linux all supported.What it doesn't do- No keyword discovery from scratch. You bring your own target keyword. (For finding keywords from an ASIN, the sister skill Amazon Keyword Discovery does that.)- No listing publishing or direct edits to Seller Central. We diagnose, you apply.- No search-volume estimates or rank tracking. Different tools.- No image, review, or copy-quality analysis. (For a bundled audit including images and reviews, the sister skill Amazon Listing Auditor & Image Analyzer does that.)- No multi-keyword batches. One diagnostic per (ASIN, keyword) pair.- SERP is page-1 only (~16 organic results).Honest limitations the AI agent knows about- The skill measures semantic alignment, not ranking. Amazon's ranking also depends on sales velocity, review count/rating, price, ad performance - signals this skill doesn't see. If your distance is on par with the top 3 but you rank lower, the gap is elsewhere.- Phrase diagnosis is correlation, not causation. "Hurts" means removing that phrase makes the listing closer to the keyword in semantic space. That's a useful diagnostic - but it's not the same as "remove this and you'll rank higher."- Cosine distance is not a percentage. "0.34 from the keyword" is not "34% off." It's a unitless distance in the embedding space. The thresholds (0.15 aligned, 0.25 misaligned) come from where Amazon's top organic results cluster, not from any percentage scale.Why this existsI was testing whether a privacy screen protector ranks for "iphone screen protector." Generic keyword tools said "yes, your title contains the keyword." But the listing wasn't on page 1. I wanted to know why - was it the title, the bullets, the description, the cluster, or just that the keyword was wrong for the product?Generic tools couldn't answer that. Embedding-based alignment could. I built a pipeline, ran it on 80+ keywords, found that title alone explained a lot but bullets often did more damage than the title. The phrase-level leave-one-out test showed me which specific bullet phrases were pulling the listing away from the keyword.That's what this skill is. It's the diagnostic I wanted and couldn't buy.
Get it → aiplus3.gumroad.com