zach-listing-health-checker

Prerequisites

This public version of the Skill is self-contained and does not depend on any private workspace files, internal reference libraries, or brand-specific protocols.

Before starting execution, it is recommended to first read through the methodology section of this Skill itself, focusing on:

Page accessibility determination
Abnormality criteria for Buy Box / Add to Cart / delivery status
Search visibility verification logic

If you already have your own Listing diagnostic framework, you can use it as supplementary background; however, execution of this Skill does not depend on external private materials.

Listing Health Checker — Complete Methodology

1. Skill Positioning

Core Concept

Scrape Amazon's server-side rendered HTML via curl + BeautifulSoup, without relying on any API or third-party data tools.

Reason: What we want to verify is "what a consumer can see when they open Amazon." Data returned by any API may be inconsistent with the front-end page (caching, regional differences, permission differences). The value of this skill lies inWhat you see is what you get。

The core data of an Amazon product page (title, price, seller, BSR, reviews, etc.) is all in the server-side rendered HTML and does not require JavaScript execution. curl with the correct browser Headers can stably retrieve the complete page (~2.4MB HTML).

Script Directory

The script is located at skills/zach-listing-health-checker/scripts/：

browser_utils.py — General-purpose web scraping module (curl wrapper, site configuration, anti-scraping detection), reusable by other Skills
fetch_amazon_page.py — Product page scraping, extracts 9 check data items, outputs JSON
fetch_amazon_search.py — Search results page scraping, checks ASIN search visibility, outputs JSON

Workflow Position

新品上架流程：
  zach-new-product-listing-writer → zach-launch-checklist-generator
      → 【zach-listing-health-checker：上架验收】
      → zach-ad-campaign-builder → 广告投放

日常运营：
  定期巡检 → 【zach-listing-health-checker】→ 发现问题 → 人工修复 → 复检

Upstream/Downstream

Direction	Skill	Relationship
Upstream	zach-new-product-listing-writer	Acceptance is required after Listing creation is completed
Upstream	zach-launch-checklist-generator	One of the execution steps of the listing checklist
Downstream	Manual repair	Manual intervention is required after problems are detected
Downstream	Recheck (invoke this Skill again)	Re-verify after repair

2. Input Parameters

Parameter	Required	Default Value	Description
ASIN	✅ Yes	—	10-character alphanumeric, usually starting with B0
Site code	No	US	See the list below for supported sites
Seller name	No	—	Used to verify whether Sold By is correct
Core keywords	No	—	Comma-separated, used for search visibility verification

Supported Site Configuration

Site code	Domain	Default postal code	Currency
US	amazon.com	90001	USD
UK / GB	amazon.co.uk	SW1A 1AA	GBP
DE	amazon.de	10115	EUR
FR	amazon.fr	75001	EUR
IT	amazon.it	00100	EUR
ES	amazon.es	28001	EUR
CA	amazon.ca	M5V 2T6	CAD
JP	amazon.co.jp	100-0001	JPY
MX	amazon.com.mx	06600	MXN
AU	amazon.com.au	2000	AUD

3. Detailed Definition of Check Items

3.1 Page Accessibility

Check Content: Whether the page renders product information normally.

Status	Judgment Condition
✅ Normal	The page contains core elements such as product title, image, price, etc.
❌ Abnormal	Dog page appears, 404, "Looking for something?", "Currently unavailable", CAPTCHA page

Common Abnormal Scenarios：

ASIN delisted → Dog page or "Currently unavailable"
ASIN merged into other variations → automatic redirect
Regional restriction → "This item does not ship to your location"

3.2 Price and Promotions

Check Content: Current selling price, strikethrough price, discount, coupon.

Status	Judgment Condition
✅ Normal	A clear selling price is displayed
⚠️ Needs Attention	Price differs significantly from expectation (requires user judgment)
❌ Abnormal	No price displayed, displays "See price in cart", or price is $0

Record Fields：

Current selling price
Strikethrough price (List Price / Was Price)
Discount percentage
Coupon amount or percentage
Whether there is a "Subscribe & Save" discount

3.3 Seller Information (Buy Box)

Check Content: Sold by and Ships from information.

Status	Judgment Condition
✅ Normal	Sold by displays the seller name specified by the user
❌ Abnormal	Sold by is not the specified seller (Buy Box lost)
⚠️ Needs Attention	User did not specify a seller; only record current information

Record Fields：

Sold by: seller name
Ships from: shipper (Amazon / seller name / third party)
Whether it is FBA (Ships from Amazon)

3.4 Cart Status

Check Content: Whether there is an Add to Cart / Buy Now button.

Status	Judgment Condition
✅ Normal	Both Add to Cart and Buy Now are displayed
⚠️ Needs Attention	Only Add to Cart without Buy Now, or displays "See All Buying Options"
❌ Abnormal	No purchase button, or displays "Currently unavailable"

3.5 Shipping Information

Check Content: Estimated delivery time and Prime status.

Status	Judgment Condition
✅ Normal	There is a clear estimated delivery date, and it is within 7 days
⚠️ Needs Attention	Delivery time 7-14 days
❌ Abnormal	Delivery time exceeds 14 days, or no shipping information

Record Fields：

Estimated delivery date
Whether there is a Prime badge
Shipping fee (free/specific amount)

3.6 Category and Node

Check Content：

Department selector next to the search bar
Sales node path in the breadcrumb navigation (usually above the main image)

Status	Criteria
✅ Normal	Category information displays normally
⚠️ Manual confirmation required	Category information displays normally, but manual confirmation is required as to whether it is the expected node

Record fields：

Search bar department name
Complete breadcrumb path (e.g. Musical Instruments › Electronic Music, DJ & Karaoke › Karaoke Equipment › Systems › Portable Systems）

Note: The "correctness" of category nodes requires manual judgment; the skill is only responsible for scraping and displaying, and does not make automatic judgments.

3.7 BSR ranking

Check content: Best Sellers Rank in categories at each level.

Status	Criteria
✅ Normal	Has BSR ranking data
⚠️ Needs attention	Significant ranking drop (requires historical comparison)
❌ Abnormal	No BSR ranking (may indicate the product has not been properly listed or the category is abnormal)

Record fields：

Category name at each level + ranking number
Example:#152 in Musical Instruments → #3 in Portable Karaoke Systems

3.8 Negative review monitoring

Check content: The number and content of negative reviews (1-3 stars) in the reviews on the first page.

Status	Criteria
✅ Normal	0 negative reviews on the first page
⚠️ Needs attention	1-2 negative reviews on the first page
❌ Abnormal	3 or more negative reviews on the first page

Record fields：

Overall rating (star level)
Total number of reviews
Number of negative reviews on the first page
For each negative review: star level, title, brief content, date
Negative review trend judgment: on the first check, mark "First check, no historical comparison baseline"; when historical reports are available, compare changes in the number of negative reviews

3.9 Search visibility

Check content: After searching with core keywords, whether the product appears on the first page of search results.

Status	Criteria
✅ Normal	Found in an organic position on the first page
⚠️ Needs attention	Found only in a sponsored position, not found in an organic position
❌ Abnormal	Not found at all on the first page (may be suppressed or search-invisible)

Key operations：

When searching, ensure "All Departments" is selected; do not be limited to a subcategory
Distinguish between organic positions (Organic) and sponsored positions (Sponsored)
Record the specific position number

4. Execution steps (detailed)

Step 1: Parameter parsing and preparation

Extract ASIN, marketplace code, seller name, and core keywords from user input
Validate ASIN format (10 alphanumeric characters)
Look up the domain and default postal code based on the marketplace code
If the user does not provide a marketplace code, use US by default
Construct the product page URL:https://{domain}/dp/{ASIN}

Step 2: Scrape the product page

Run fetch_amazon_page.py The script scrapes the product page and extracts structured data:

python3 skills/zach-listing-health-checker/scripts/fetch_amazon_page.py {ASIN} --site {站点代码}

The script outputs JSON containing the following fields:

page_status: page status (ok / dog_page / unavailable / captcha / fetch_failed)
title: product title
price: current price, list price, discount, coupon
seller：sold_by、ships_from
cart：add_to_cart、buy_now、see_all_buying_options
delivery: shipping text, Prime badge
category: search bar category, breadcrumb path
bsr: rankings and categories at each level
ratings: rating stars, total number of reviews
reviews_on_page: first-page review details (stars, title, date, content, whether negative review)
variants: variation information
stock: stock status
anomalies: list of anomaly alerts

Step 3: Parse the check results

Compare the JSON data returned by the script item by item against the judgment criteria in Section 3, and mark a status for each check item:

✅ Normal
⚠️ Needs attention
❌ Abnormal

For fields that the script could not extract (value is empty or missing), mark them as "⚠️ Unable to obtain" and do not speculate.

Step 4: Search visibility check

⛔ Perform this step only when the user has provided core keywords.

For each core keyword, run the fetch_amazon_search.py script:

python3 skills/zach-listing-health-checker/scripts/fetch_amazon_search.py "{keyword}" {ASIN} --site {站点代码}

The script outputs JSON containing:

target_found: whether the target ASIN is on the first page
target_position: position number
target_type: organic (organic position) or sponsored (sponsored position)
search_department: search scope
first_page_results: list of all results on the first page (including ASIN, title, position, type)
captcha: whether blocked by CAPTCHA

Mark the search visibility status according to the judgment criteria in Section 3.9.

Note: When multiple ASINs search the same keyword, only scrape the search results page once, and look for all target ASINs in the results.

Step 5: Generate the health check report

Following the report template in Section 5, organize all check results into a Markdown report.

Overall assessment logic：

🟢 All passed: all 9 items are ✅
🟡 Needs attention: there are ⚠️ but no ❌
🔴 Has abnormalities: any item is ❌

Step 6: Save the report

Save the report to:

outputs/listing-health-check/{品牌名或ASIN}/{YYYY-MM-DD}_{ASIN}_健康检查报告.md

If the brand name cannot be determined from the page, use the seller name or ASIN as the directory name.

Step 7: Output summary

Output to the user in the terminal:

Overall assessment status (🟢/🟡/🔴)
Brief list of abnormal items and items needing attention
Save path of the report file

5. Output report template

---
created: YYYY-MM-DD HH:MM
topic: {ASIN} Listing 健康检查
type: 健康检查报告
data_sources: 亚马逊官网页面抓取（curl + BeautifulSoup）
---

# {ASIN} Listing 健康检查报告

> 检查时间：YYYY-MM-DD HH:MM
> 站点：{站点代码} ({域名}) | 邮编：{邮编}
> 商品标题：{完整标题}

## 总体评估

| 状态 | 说明 |
|------|------|
| 🟢 / 🟡 / 🔴 | {一句话总结，如"链接健康，所有指标正常"} |

通过：X/9 | 需关注：X | 异常：X

---

## 逐项检查结果

### 1. ✅/❌ 页面可访问性
- **状态**：正常 / 异常
- **详情**：{具体描述}

### 2. ✅/⚠️/❌ 价格与优惠
- **当前售价**：${XX.XX}
- **划线价**：${XX.XX} / 无
- **折扣**：{X% off} / 无
- **优惠券**：{金额或百分比} / 无
- **Subscribe & Save**：{折扣} / 无

### 3. ✅/❌ 卖家信息（Buy Box）
- **Sold by**：{卖家名}
- **Ships from**：{发货方}
- **期望卖家**：{用户指定} → ✅ 匹配 / ❌ 不匹配 / 未指定

### 4. ✅/⚠️/❌ 购物车状态
- **Add to Cart**：有 / 无
- **Buy Now**：有 / 无
- **Buy Box 持有**：是 / 否

### 5. ✅/⚠️/❌ 配送信息
- **预计送达**：{日期}
- **Prime**：是 / 否
- **配送费**：{免费 / 金额}
- **判断**：正常（≤7天）/ 偏慢（7-14天）/ 异常（>14天）

### 6. ✅/⚠️ 类目与节点
- **搜索栏大类**：{大类名称}
- **面包屑路径**：{完整路径}
- **提示**：请人工确认节点是否为期望类目

### 7. ✅/⚠️/❌ BSR 排名

| 层级 | 类目 | 排名 |
|------|------|------|
| 大类 | {类目名} | #{排名} |
| 子类1 | {类目名} | #{排名} |
| 子类2 | {类目名} | #{排名} |

### 8. ✅/⚠️/❌ 差评监控
- **总评分**：{X.X} 星（{X,XXX} 条评论）
- **首页差评数**：{X} 条
- **差评趋势**：首次检查，无历史对比基线 / 较上次 {增加/减少} {X} 条

差评详情：

| 星级 | 标题 | 日期 | 内容摘要 |
|------|------|------|----------|
| ⭐{X} | {标题} | {日期} | {内容} |

### 9. ✅/⚠️/❌ 搜索可见性

| 关键词 | 搜索范围 | 是否找到 | 位置 | 类型 |
|--------|----------|----------|------|------|
| {keyword1} | All Departments | 是/否 | #{位置} | 自然/广告 |
| {keyword2} | {范围} | {结果} | {位置} | {类型} |

---

## 问题清单与行动建议

| 优先级 | 问题 | 建议操作 |
|--------|------|----------|
| 🔴 高 | {问题描述} | {具体建议} |
| 🟡 中 | {问题描述} | {具体建议} |

---

## 原始数据快照

> 以下为脚本抓取的原始关键信息，供核对。

{保留核心原始数据，便于日后审计}

6. Data integrity rules

This skill strictly follows the following data principles:

Single data source: All information comes from scraping Amazon official website pages (curl + BeautifulSoup), and does not use Sorftime MCP or any other third-party data tools.
Do not speculate about information not obtained: Fields that the script cannot extract are marked as "⚠️ Unable to obtain" and are never fabricated.
Mark data timeliness: The report clearly marks the check time and states that "the results only represent a page snapshot at the time of checking".
Distinguish facts from judgments：
- Raw information scraped from the page = 📊 Data facts
- Recommendations based on inspection results = 💡 Analytical inference
Negative review trends require historical comparison: The first inspection only records a snapshot and does not make a judgment on "whether new negative reviews were added"; comparison is only made when historical reports are available.

7. Limitations and Countermeasures

Limitation	Description	Countermeasure
JS dynamic content	curl retrieves server-rendered HTML; content dynamically loaded by JS may be missing	If key information is missing, mark it as "⚠️ May not have been retrieved due to dynamic loading"
Anti-scraping mechanisms	Amazon may return a CAPTCHA or a simplified page	The script automatically detects CAPTCHAs and marks the report as "❌ Blocked by Amazon, manual check recommended"
Regional differences	No postal code is actually set, which may affect price and delivery display	State the postal code and marketplace used in the report
Search personalization	Search results are affected by algorithms	Note that "search results are a snapshot at a specific moment and may actually vary depending on user profiles"
Single snapshot	Cannot detect temporal changes such as "a sudden surge of new negative reviews"	Recommend running regularly and comparing with historical reports

8. Use Cases

Scenario 1: New product listing acceptance

/zach-listing-health-checker B0XXXXXXXXX US MyBrand "main keyword, secondary keyword"

Run 24-48 hours after listing, with focus on:

Whether the page is normal
Whether the Buy Box is held by you
Whether the search keywords are visible

Scenario 2: Daily inspection

/zach-listing-health-checker B0XXXXXXXXX

Weekly routine check, with focus on:

Changes in the number of negative reviews
Whether the Buy Box is lost
Whether the price is correct

Scenario 3: Anomaly troubleshooting

帮我检查 B0XXXXXXXXX，最近销量突然下降，看看链接有没有问题

Focus on troubleshooting:

Whether it is suppressed (not visible in search)
Whether the Buy Box has been taken over
Whether there is an outbreak of new negative reviews

Scenario 4: Batch check (multiple ASINs)

When the user provides multiple ASINs, run the complete inspection process one by one, and finally output a summary table.

9. Data Flow with Other Skills

本技能不消费其他技能的输出，也不产出供其他技能消费的数据。
它是一个独立的"健康巡检"工具，输出人可读的诊断报告。

唯一的"数据流"是历史报告对比：
  本次报告 ↔ 上次报告（同一 ASIN）→ 差评趋势判断

10. Dependencies

Python 3: Run the scraping script
beautifulsoup4: HTML parsing (pip install beautifulsoup4）
curl: Built into the system, used for HTTP requests
Bash tool: Used to execute Python scripts
Write tool: Used to save report files
Read tool: Used to read historical reports (negative review trend comparison)
Glob tool: Used to find historical report files

No Sorftime MCP required, no external API required. The scripts are all located in the skills/zach-listing-health-checker/scripts/ directory.

Risks and Boundaries

risk-level: low — Pure analysis/information gathering, only reads public front-end pages, does not involve any account operations

Upstream / Downstream

Upstream: None (directly input ASIN or URL)
Downstream：zach-listing-rufus-optimizer(content diagnosis),zach-asin-sales-anomaly-analyzer(anomaly troubleshooting)

After completion

Report completion status: DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT

About this skill

Prerequisites

1. Skill Positioning

Core Concept

Script Directory

Workflow Position

Upstream/Downstream

2. Input Parameters

Supported Site Configuration

3. Detailed Definition of Check Items

3.1 Page Accessibility

3.2 Price and Promotions

3.3 Seller Information (Buy Box)

3.4 Cart Status

3.5 Shipping Information

3.6 Category and Node

3.7 BSR ranking

3.8 Negative review monitoring

3.9 Search visibility

4. Execution steps (detailed)

Step 1: Parameter parsing and preparation

Step 2: Scrape the product page

Step 3: Parse the check results

Step 4: Search visibility check

Step 5: Generate the health check report

Step 6: Save the report

Step 7: Output summary

5. Output report template

6. Data integrity rules

7. Limitations and Countermeasures

8. Use Cases

Scenario 1: New product listing acceptance

Scenario 2: Daily inspection

Scenario 3: Anomaly troubleshooting

Scenario 4: Batch check (multiple ASINs)

9. Data Flow with Other Skills

10. Dependencies

Risks and Boundaries

Upstream / Downstream

After completion