SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillszach-search-term-report-analyzer

zach-search-term-report-analyzer

Marketing & growth

View repository

Updated 10-15 16:46

About this skill

Prerequisites

This public version of the Skill is self-contained and does not depend on private workspace files, internal knowledge bases, store configurations, or team data sources.

Before starting execution, it is recommended to first read the materials included with this Skill:

  • references/field_mapping.md — SP / SB / SD field mapping
  • references/decision_rules.md — Search term decision rules
  • references/term_classification.md — Classification criteria for brand terms, competitor terms, attribute terms, and scenario terms
  • references/output_template.md — Report and CSV output templates
  • scripts/clean_search_term_report.py — Raw report cleaning and standardization script
  • scripts/analyze_search_term_decisions.py — Single ASIN decision analysis script
  • scripts/fetch_listing_context.py — Optional Amazon front-end Listing context scraping script

Positioning

Ad search term reports are not only used to find negative keywords. They also serve three purposes:

  1. Find terms that continuously consume budget but have weak conversion
  2. Find scaling candidates with better CVR, ACOS, or trend performance
  3. Extract attribute terms, scenario terms, and Listing feedback clues from users' real search language

This Skill outputs analysis recommendations and action candidates; it will not directly modify ads, budgets, bids, or negative keyword settings on the user's behalf.

Input parameters

Parameter Required Default value Description
Search term report file Yes - CSV / XLSX / XLSM / XLS; prefer the official Amazon Ads export file
Brand No Identified from report fields or file name Can also use --brand to specify explicitly
ASIN No Automatically identify a single candidate When there are multiple candidates, the user must select one
Marketplace No US Used for optional Listing scraping
Report type No Automatically identify SP / SB / SD; mark when identification fails UNKNOWN
Target ACOS No The report's own benchmark Use --target-acos 0.20 to pass explicitly for greater stability
Listing context No Attempt live fetch by default Can use --listing-context-file to provide local title/bullet text

Execution flow

Step 1: Identify the input file and analysis target

  1. Read the search term report uploaded or specified by the user.
  2. Run the cleaning script to identify fields, report type, brand candidates, and ASIN candidates:
python3 skills/zach-search-term-report-analyzer/scripts/clean_search_term_report.py <input_file>
  1. If multiple ASINs are identified, first list the candidates for the user to choose; do not mix analysis.
  2. If the brand cannot be identified, allow the user to pass it explicitly with --brand ; the brand is only used for grouping, file naming, and brand term identification.

Step 2: Standardize fields

According to references/field_mapping.md unify raw fields into internal fields:

  • date
  • brand
  • asin
  • campaign_name
  • ad_group_name
  • targeting
  • match_type
  • search_term
  • impressions
  • clicks
  • spend
  • orders
  • sales
  • cvr
  • acos
  • roas

Missing fields are handled as "use if available, skip if not"; but core fields date + search_term + clicks + spend Must stop when missing.

Step 3: Establish the ASIN baseline and time windows

  1. By default, use a single ASIN as the unit of analysis.
  2. Establish the ad CVR baseline for this ASIN over the past 30 days:orders / clicks。
  3. Separately aggregate clicks, spend, orders, CVR, ACOS, and trend changes for the 7 / 14 / 30-day windows.
  4. If the user provides --target-acos, use it to judge cost pressure; otherwise use the ASIN report's own ACOS as a reference.

Step 4: Fetch or read the Listing context

Default behavior: the script will attempt to visit the Amazon front-end page by ASIN and marketplace, and extract title / bullets / description / breadcrumb.

Use when testing stably or when network access is restricted:

--skip-live-listing-fetch
--listing-context-file skills/zach-search-term-report-analyzer/examples/listing-context-sample.md

Listing context is only used to enhance the judgment of 'relevant terms, attribute terms, scenario terms, weakly relevant terms'; a failed fetch must not block the basic ad analysis.

Step 5: Perform search term decision analysis

Read references/decision_rules.md and references/term_classification.md, and output for each search term:

  • Main category:brand_term / competitor_term / asin_term / core_category_term / attribute_term / scenario_term / irrelevant_term / uncertain_term
  • Action label:scale_up / hold_test / reduce_bid / negative_candidate / observe / listing_feedback / manual_review
  • Confidence:high / medium / low
  • Explanation: explain how clicks, spend, CVR, ACOS, trend, and Listing relevance jointly support this judgment

Step 6: Output the report and details

Default output to:

outputs/search-term-report-analyzer/{brand_or_unknown}/

Script command example:

python3 skills/zach-search-term-report-analyzer/scripts/analyze_search_term_decisions.py \
  <input_file> \
  --brand ExampleBrand \
  --asin B0PUBLIC01 \
  --target-acos 0.20 \
  --listing-context-file skills/zach-search-term-report-analyzer/examples/listing-context-sample.md \
  --skip-live-listing-fetch

Output file list

File Format Path
Main report .md outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_搜索词报告分析.md
Detail table .csv outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_搜索词分析明细.csv
Exception list .csv outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_异常清单.csv
Run summary .json outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_run_summary.json

Risks and boundaries

  • This Skill does not：
    • Does not directly modify ad bids, budgets, negative keywords, or ad structure
    • Does not upload user reports or retain real sales data
    • Does not rely on private store configurations or internal knowledge bases
    • Does not force CVR / ACOS conclusions when fields are insufficient
  • Requires manual review：
    • Multiple ASINs are mixed in the same report
    • The strategy for brand terms, competitor terms, or ASIN-type search terms is unclear
    • The Listing fetch fails and term relevance depends heavily on product selling points
    • Clicks are low, spend is low, or the 7 / 14 / 30-day signals conflict with each other
  • risk-level = medium：
    • This Skill will provide ad action suggestions, but any bid, budget, or negative keyword execution requires manual completion after user confirmation.

Upstream / Downstream

  • Upstream：
    • Amazon Ads search term report provided by the user
    • Optional Listing context file
  • Downstream：
    • Manual ad operations: review negative keyword candidates, bid control candidates, and scaling candidates
    • Listing optimization: feed attribute terms, scenario terms, and demand terms back into the title, bullet points, A+, or creatives

After completion

Report completion status:

  • DONE — Report, details, exception list, and summary have all been generated
  • DONE_WITH_CONCERNS — Generated, but there are high-impact items requiring manual review
  • BLOCKED — Core fields are missing, files are unreadable, or the ASIN cannot be determined
  • NEEDS_CONTEXT — The user needs to supply the brand, ASIN, marketplace, target ACOS, or Listing context

Inform the user:

  1. Analysis object: brand, ASIN, marketplace, report type
  2. Result summary: negative keyword candidates, cost control candidates, scaling candidates, number of Listing feedback terms
  3. File paths: main report, detail table, exception list, and run summary