SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssif-keyword-scout

sif-keyword-scout

Coding & development

View repository

Updated 10-15 20:06

About this skill

Sif Keyword Intelligence Reconnaissance (Skill 1)

Agent Role

When executing this skill, also read and follow references/amazon-expert-guide.md：

  • As anAmazon keyword/PPC consultantinterpret the results in that role, and proactively guide the user when parameters are abnormal
  • Do not just run the script; when the S/A thresholds, category description, or SS/SSS counts are abnormal, explain the reason and suggest corrections

Human-Machine Collaboration Principles (Mandatory)

Prohibit "silently running through the entire process". This skill is a consultant + automation, not a batch script.

Rule Description
Must discuss before running In ingest_raw or any --mode process before that, you must confirm with the user the ASIN, stage, category, and data source
Three checkpoints See "Mandatory Pause Points" below —do not proceed to the next step without explicit user confirmation
Confirmation method The user replies with explicit permission such as "OK / continue / use the automatic value / do as you said"; silence or only giving an ASIN does not count as confirmation
Stop first on anomalies When a sanity check is triggered, first explain the reason and provide options, and wait for the user to choose before rerunning or continuing

Mandatory Pause Points (Three)

# Timing What the Agent does What the user confirms
① Table 1 compute-thresholds after,process before Show the S/A thresholds and bid/concentration medians; combined withstage + categoryexplain whether they are high/low Keep the automatic values, or specify --s-threshold / --a-threshold
② Three tables + cross --skip-word after completion, before writing insights_cross before Interpret the SSS/SS/S counts and Table 3 gaps/outlier terms; list the recommended primary-target SS list and terms that should be excluded Confirm the primary-target direction and whether to rerun Table 3 (change category/--sv-threshold）
③ Skill 2 compare_versions --skip-word after completion, before writing insights_tracker before Interpret additions/disappearances/share changes; give trial-run/pause/bid-adjustment suggestions Confirm whether to adjust placement according to the suggestions, or only archive for observation

Scripts and interpretation details → references/amazon-expert-guide.md each section.

Dependencies

Dependency Description
Python pip install pandas openpyxl matplotlib python-docx numpy
web-access Method B only required; third-party eze-is/web-access(author Yize Eze, MIT); path see references/path-setup.md

Final output: processing result directoryKeep only Excel (.xlsx）+ Word（.docx）. Charts are generated by the script as PNGs and thenembedded into Word, without keeping the charts/ directory. The insights_*.md written by the Agent is an intermediate draft (for Word to render the AI analysis section), and is automatically deleted after Word is generated.

Three input methods (automatically determined by the Agent)

Method What the user says What the Agent does
C Provide paths directly (fastest) Sends 3 xlsx paths, or a download folder ingest_raw.py Identify table types → copy to standard directory → run processing
A Manual export 「I've downloaded them myself」or place them in the specified directory Send manual-export-guide.md, or ingest_raw --from-dir
B Browser export 「You download them for me」 web-access + browser-export-sop.md

When the user provides file paths directly: no need to ask again about the download method, first resolve_workspace → run the pre-run briefing (Step 1) to get confirmation → call ingest_raw → continue from Step 5.

# 三个路径
python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --stage {阶段} --product-category "{类目}" \
  --product-type {标品|非标品} \
  --t1 "D:/Downloads/Sif关键词调研-....xlsx" \
  --t2 "D:/Downloads/asinKeywords_....xlsx" \
  --t3 "D:/Downloads/asinAdKwView_....xlsx"

# 或一个文件夹（自动识别）
python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --from-dir "D:/Downloads"

Step 0: Workspace and path initialization (at the start of each run)

python "{SKILL_SCOUT}/scripts/resolve_workspace.py"

Parse the JSON to get workspace、config_path、output_dir、download_dir、scripts.*、web_access , etc.

Situation Action
workspace_found: false Have the user specify the workspace root directory, or copy .sif-config.example.json → .sif-config.json
needs_output_dir: true Required reading first-time-setup.md, ask the user for the output root directory,do not fill in someone else's path → --init-output-dir
needs_download_dir: true Method B only: ask for the browser download directory → --init-download-dir(methods A/C can skip)
Return first_time_guide follow the steps in it to guide step by step, and run ASIN only after configuration is complete

The path belongs to the user: when packaging for others, send only .sif-config.example.json(empty fields); each person specifies their own on first use output_dir。

Details → references/path-setup.md · First conversation script → references/first-time-setup.md

Step 1: Pre-run briefing (ASIN + parameters + user confirmation)

Before calling ingest_raw or the processing script, complete the following conversation andwait for user confirmation：

  1. ASIN: if the user message contains an ASIN → use it directly; otherwise ask first
  2. Must-ask parameters(cannot be skipped):
1. 产品阶段：新品期 / 成长期 / 成熟期？
2. **产品类型**：标品 / 非标品？（决定默认门槛，见 `references/threshold-presets.md`）
3. 精确产品类目（影响表3 缺口词，如「不锈钢保温杯」而非笼统「水杯」）？

  1. Pre-run briefing(summarize in natural language, do not just paste commands):

    • This run will produce 4 sets of Excel + Word (Tables 1/2/3 + PD main-target keyword list)
    • If there is history → additionally produce a keyword library update report (Skill 2)
    • Data source: method A / B / C (if the user has already given file paths, state「direct connection」)
    • Expected to pause at pause points ①② to confirm the thresholds and main-target keyword direction with you

  2. Confirmation gate: only after the user explicitly replies do you proceed to Steps 2~3.

Category guidance rules → references/amazon-expert-guide.md

Step 2: Check ASIN history

python "{scripts.check_history}" --asin {ASIN} --output-dir "{output_dir}"

Save has_history、prev_path for use in Step 10.

Step 3: Create directories + ingest raw tables

Method C (file paths already available): after Step 0, directly call ingest_raw(see above), this step is merged and complete.

Method A/B (no standard-named files yet)：

python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --stage {阶段} --product-category "{精确类目}" --product-type {标品|非标品}

Parse stdout JSON:

Field Meaning
date / run_id YYYYMMDD, used for the filename suffix
run_path {ASIN}/{date}
raw_dir Raw data directory
result_dir Processing result directory
raw_files Standard filenames of the three raw tables
datetime_display The actual run time written to the history table (including hour and minute)

Directory structure:

{output_dir}/{ASIN}/{DATE}/
├── 原始数据/
│   ├── 关键词调研_{DATE}.xlsx
│   ├── 反查流量词_{DATE}.xlsx
│   └── 查广告词_{DATE}.xlsx
└── 处理结果/          ← 最终仅保留 xlsx + docx
    ├── {ASIN}_关键词分层分析_{DATE}.xlsx
    ├── {ASIN}_关键词调研分析报告_{DATE}.docx
    ├── {ASIN}_竞品弱点分析_{DATE}.xlsx
    ├── {ASIN}_竞品弱点分析报告_{DATE}.docx
    ├── {ASIN}_竞品缺口分析_{DATE}.xlsx
    ├── {ASIN}_竞品广告缺口分析报告_{DATE}.docx
    ├── {ASIN}_PD主攻词单_{DATE}.xlsx
    └── {ASIN}_PD主攻词单报告_{DATE}.docx

Intermediate artifacts (stats JSON,insights_*.md、charts/) are automatically deleted by the script after Word generation cleanup_intermediate_files .

Step 4: Retrieve the three raw tables (only for A/B and when Step 3 has not yet ingested)

Method Action
C Existing path Skip, Step 3's ingest_raw already completed
A Manual Send manual-export-guide.md; after the user finishes downloading, ingest_raw --from-dir or --t1/--t2/--t3
B Browser web-access + browser-export-sop.md; after downloading, likewise ingest_raw

Must-read before processing → references/table-schema.md

Step 5: Process Table 1 → Generate Word report

Calculation baseline:

python "{scripts.process_table1}" --mode compute-thresholds --input "{raw_dir}/关键词调研_{DATE}.xlsx"

Show the baseline to the user, and use amazon-expert-guide.md wording to ask whether to adjust the S/A thresholds.

Pause point ①: Only after the user confirms the thresholds (or explicitly says "use automatic values") execute the following process。

First round (Excel + stats, skip Word):

python "{scripts.process_table1}" --mode process --input "{raw_dir}/关键词调研_{DATE}.xlsx" --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --stage {阶段} --product-type {标品|非标品} [--s-threshold N --a-threshold N --s-conc-max 0.30] --skip-word

Agent writes the AI analysis section (mandatory):

  1. Read *_t1_stats_{DATE}.json
  2. As an Amazon consultant, write insights_t1.md(analysis text only, format per "insights writing guidelines" below)
  3. Do not write chart sections, charts are automatically embedded by Word

Second round (generate Word, automatically clean up intermediate files):

python "{scripts.process_table1}" --mode process ... --insights-file "{result_dir}/insights_t1.md"

Output:{ASIN}_关键词分层分析_{DATE}.xlsx + {ASIN}_关键词调研分析报告_{DATE}.docx

Step 6 / 7 / 8: Table 2, Table 3, cross-analysis

Process same as Table 1: first --skip-word → write insights_t2.md / insights_t3.md / insights_cross.md → with --insights-file rebuild Word.

# 表2
python "{scripts.process_table2}" --input "..." --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --skip-word
# → 写 insights_t2.md → 去掉 --skip-word 加 --insights-file

# 表3
python "{scripts.process_table3}" --input "..." --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --product-category "{精确类目}" --product-type {标品|非标品} [--sv-threshold 1000] --skip-word

# 交叉（输入必须是**处理后的**三表 Excel，不是原始数据目录）
python "{scripts.cross_analysis}" \
  --t1 "{result_dir}/{ASIN}_关键词分层分析_{DATE}.xlsx" \
  --t2 "{result_dir}/{ASIN}_竞品弱点分析_{DATE}.xlsx" \
  --t3 "{result_dir}/{ASIN}_竞品缺口分析_{DATE}.xlsx" \
  --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --skip-word
Parameter When to adjust Description
--product-type Every ASIN Default is non-standard product; for standard/non-standard product presets see threshold-presets.md
--sv-threshold Too few gap keywords in small category 0=use preset (non-standard 2000/standard 3000), can be lowered to 500–1000
--product-category Ask every time Affects keyword type determination

Cross --skip-word After completion do sanity check(e.g. gap keywords are 0, SSS is 0, etc.) → see amazon-expert-guide.

Pause point ②: Report the cross-analysis results and the suggested main-target SS list to the user; after confirmation write insights_cross.md and generate the PD Word. If Table 3 needs to be rerun, stop here and adjust the parameters.

Table 2 and Table 3's insights_t2/t3 can be written in parallel before pause point ②;The PD report and cross Word must come after pause point ②。

Insights writing guidelines (for Word rendering)

Syntax Description
## 标题 Section heading, renders as a Word Heading 2
- 列表项 Unordered list
**加粗** Bold text
| 列 | 列 | Optional, converts to a Word table
![图](charts/xxx.png) Forbidden — charts are inserted into Word by the script
***文字*** Forbidden — will display as garbled asterisks
# 总标题 Forbidden — Word already has a cover title

TOP5 / per-keyword commentary (mandatory): Each entry = data in parentheses + strategic sentence(competitive assessment, whether to invest at this stage, match type, relationship with the listing). Repeating in the style of "keyword: keyword, search volume..." is forbidden.

Counter-example：- **sofa cover**：sofa cover，搜索量 58321，竞价 $1.04
Positive example：- **sofa cover**（S级，搜索量 58321，竞价 $1.04，集中度 0.22）：核心品类词，集中度低于类目中位；新品期精准小预算试投，与三座规格 listing 匹配再加码。

Final output (only kept in the processing result directory)

  • {ASIN}_关键词分层分析_{DATE}.xlsx + _关键词调研分析报告_{DATE}.docx
  • {ASIN}_竞品弱点分析_{DATE}.xlsx + _竞品弱点分析报告_{DATE}.docx
  • {ASIN}_竞品缺口分析_{DATE}.xlsx + _竞品广告缺口分析报告_{DATE}.docx
  • {ASIN}_PD主攻词单_{DATE}.xlsx + _PD主攻词单报告_{DATE}.docx

Step 9: Update history (must be done after every run, append one line)

python "{scripts.update_history}" --asin {ASIN} --output-dir "{output_dir}" --date {DATE} --run-path "{run_path}"

ASIN历史记录.xlsx → Sheet "Run log"：Append one line per run, no overwriting, no merging dates.

Column Description
Run time YYYY-MM-DD HH:MM
Data date YYYYMMDD(folder date)
Snapshot path {ASIN}/{DATE}/{HHmm}, distinguishes multiple runs on the same day

The old summary table can be migrated in one go using --migrate-only :

python "{scripts.update_history}" --migrate-only --output-dir "{output_dir}"

Step 10: Conditionally trigger Skill 2 (1~7 day window comparison)

When check_history shows that this ASIN has ≥2 runs → execute Skill 2.

python "{scripts.check_history}" --asin {ASIN} --output-dir "{output_dir}" --curr-date {DATE}

Automatically select comparison baseline:Prefer the most recent run within the 1~7 day window; if there are multiple runs on the same day, compare with the previous run on the same day.

Skill 2 two-round process(same as Skill 1):

# 1) 对比 + stats
python "{scripts.compare_versions}" --auto --output-root "{output_dir}" --output-dir "{result_dir}" --asin {ASIN} --curr-date {DATE} --skip-word

# → 暂停点 ③：解读变化，与用户确认投放策略

# 2) Agent 写 insights_tracker.md → 重建 Word
python "{scripts.compare_versions}" --auto ... --insights-file "{result_dir}/insights_tracker.md"

Output:{ASIN}_词库更新报告_{DATE}.docx(including data table + AI strategy section)

Step 11: Report

Report the output path, SS/SSS main keyword summary, and whether parameter adjustment is recommended; for the first run, explain that the next run for the same ASIN will automatically compare.

Error handling

Error Handling
Python error Refer to table-schema.md to check the table structure, then ask the user whether to re-export
Sif not logged in Method B: ask the user to log in via the browser and continue; or switch to Method A
Download file not found Confirm download_dir or switch to Method A
Category/stage clearly incorrect Advisor mode: pause and guide correction of parameters

Script list (scripts/）

Script Purpose
resolve_workspace.py Parse configuration and absolute paths of all scripts
ingest_raw.py Create directories + connect user files (any path/folder)
check_history.py / update_history.py Historical ASIN query and update
process_table1/2/3.py Three-table processing
cross_analysis.py Three-table intersection → PD main keyword list
run_context.py / report_utils.py Internal module, not called directly
batch_regenerate_word.py Development/batch run: rebuild Word; add --full-pipeline to run Skill1+2 in one click
create_mock_sif_exports.py Mock data for development testing only

Reference document index

File Purpose
first-time-setup.md First-time use: output_dir / download_dir guidance (required reading for Agent)
path-setup.md Workspace, configuration, path resolution
manual-export-guide.md Method A user operation guide
browser-export-sop.md Method B URL/button SOP
table-schema.md Three table structures (error prevention)
amazon-expert-guide.md Advisor role and parameter guidance
sop-tables.md Details of grading/intersection rules