keyword-research

Keyword Research and Analysis Skill

Quick Reference

Step	Sorftime API	Purpose	Data Volume
1	product_traffic_terms	Product traffic keywords	50-200
2	competitor_product_keywords	Competitor placement keywords	100-500
3	category_keywords	Category core keywords	100-500
4	keyword_related_words	Long-tail keyword expansion	1000-2000
5	LLM Agent	8-dimension intelligent classification	Full volume

One-click execution:

# 在 Claude Code 环境中运行（自动触发 LLM 分类）
python .claude/skills/keyword-research/scripts/workflow.py B07PWTJ4H1 US --claude-code-env

Other options:

# 跳过分类，仅采集数据（后续可手动LLM分类）
python .claude/skills/keyword-research/scripts/workflow.py B07PWTJ4H1 US --skip-classification

# 禁用LLM分类，使用规则分类
python .claude/skills/keyword-research/scripts/workflow.py B07PWTJ4H1 US --disable-llm-classification

Trigger Conditions

This analysis process is started when the user makes a request in the following ways:

• Command: /keyword-research {ASIN} {站点}
• Example: /keyword-research B07PWTJ4H1 US
• Natural language: "Analyze this product's keyword library", "Research the keywords for B07PWTJ4H1"

---

Role Setting

You are an "Amazon PPC Advertising Expert" and "Keyword Strategy Analyst" with 10 years of experience. You are proficient in the Amazon A9 algorithm and keyword placement strategies, and can identify high-value words and words that need to be excluded from massive amounts of keywords.

---

Data Collection Strategy: Plan A (ASIN-based in-depth analysis)

输入: ASIN + 站点 + (可选) 产品信息
  ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 基础数据采集                                         │
├─────────────────────────────────────────────────────────────┤
│ 1. product_traffic_terms      → 产品流量词 (50-200个)       │
│ 2. competitor_product_keywords → 竞品布局词 (100-500个)     │
│ 3. category_keywords           → 类目核心词 (100-500个)      │
└─────────────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2: 长尾词扩展                                          │
├─────────────────────────────────────────────────────────────┤
│ 从基础词中选择 Top 30 核心词                                 │
│ → 对每个调用 keyword_related_words (50-100个延伸词)         │
│ → 预计获取 1000-2000 个长尾词                               │
└─────────────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 3: 数据清洗                                            │
├─────────────────────────────────────────────────────────────┤
│ 1. 去重（归一化：小写、去除特殊字符）                        │
│ 2. 过滤无效词（过短、非英文、乱码）                          │
│ 3. 合并搜索量/CPC 等指标                                    │
└─────────────────────────────────────────────────────────────┘
  ↓
最终词库: 2000+ 关键词

---

Keyword Classification: 8-Dimension Intelligent Classification Model

Classification Dimensions

Dimension	Identifier	Identification Rule	Application Strategy
Negative/Sensitive Words	NEGATIVE	Words irrelevant to the product or inconsistent with the description	Add directly as negative keywords
Brand Words	BRAND	Competitor brand names	Competitor tactics or negation
Material Words	MATERIAL	Words related to product materials	Exact phrase match
Scenario Words	SCENARIO	Usage scenario/location words	Split ad groups by scenario
Attribute Modifier Words	ATTRIBUTE	Product attribute/feature words	Long-tail exact match
Function Words	FUNCTION	Words related to product functions	Broad match for traffic expansion
Core Product Words	CORE	Core product names	Big-word placement to occupy slots
Others	OTHER	Unclassified, misspellings, other languages	Supplementary keyword embedding

Classification Identification Examples (Using Coat Rack as an Example)

产品信息: Coat Rack Wall Mount, Wood, 5 Hooks, Entryway

否定词: freestanding, over door, floor, tree, shoe
品牌词: umbra, simplehuman, mDesign, household essentials
材质词: wood, wooden, metal, aluminum, bamboo
场景词: entryway, bathroom, mudroom, garage, bedroom
属性词: wall mount, heavy duty, rustic, vintage, expandable, 5 hook
功能词: hanging, storage, organizer, display
核心词: coat rack, hook, hanger, hat rack, towel rack
其他: coatrac (拼写错误), perchero (西语)

---

Execution Process

Phase One: Data Collection

Step 1.1: Obtain product traffic keywords

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"product_traffic_terms","arguments":{"amzSite":"US","asin":"ASIN"}}}'

Returned data: Keyword list, including metrics such as search volume and CPC

Step 1.2: Obtain competitor placement keywords

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"competitor_product_keywords","arguments":{"amzSite":"US","asin":"ASIN"}}}'

Returned data: Competitors' ranking positions under each keyword

Step 1.3: Obtain category core keywords

# 首先获取产品详情以获取 NodeID
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN"}}}'

# 然后获取类目关键词
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"category_keywords","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'

Step 1.4: Long-tail keyword expansion

Select the Top 30 core words from the base words, and for each one call:

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":N,"method":"tools/call","params":{"name":"keyword_related_words","arguments":{"amzSite":"US","searchKeyword":"KEYWORD"}}}'

---

Phase Two: LLM Intelligent Classification

Classification Prompt Template

你是一位亚马逊关键词分类专家。请根据以下产品信息，将关键词列表按 8 个维度分类。

【产品信息】
产品名称: {product_name}
材质: {material}
核心属性: {features}
使用场景: {use_cases}
否定特征: {negative_features}

【分类维度】
1. NEGATIVE: 不相关的词，需直接否定
2. BRAND: 竞品品牌名称
3. MATERIAL: 材质相关词 (wood, metal, aluminum...)
4. SCENARIO: 使用场景词 (entryway, bathroom...)
5. ATTRIBUTE: 属性修饰词 (wall mount, heavy duty...)
6. FUNCTION: 功能词 (hanging, storage...)
7. CORE: 核心产品词 (coat rack, hook...)
8. OTHER: 其他（拼写错误、其他语言等）

【待分类关键词】
{keywords_json}

【输出格式】
请以 JSON 格式输出：
{
  "NEGATIVE": ["word1", "word2", ...],
  "BRAND": [...],
  ...
}

Batch Processing Strategy

• Batch size: 150 keywords per batch
• Parallel processing: multiple batches can be processed concurrently
• Result merging: count each category, aggregate keywords

---

Phase 3: Report generation

Output file structure

keyword-reports/
└── {ASIN}_{Site}_{YYYYMMDD}/
    ├── report.md                    # Markdown 分析报告
    ├── keywords.csv                 # 完整关键词词库（分类后）
    ├── negative_words.txt           # 否定词清单
    ├── brand_words.txt              # 品牌词清单
    ├── categorized_summary.json     # 分类统计
    └── dashboard.html               # HTML 可视化仪表板

keywords.csv format

keyword,category,search_volume,cpc,competition,application,relevance_score
coat rack,CORE,54000,1.85,high,广泛匹配,1.00
wooden coat rack,MATERIAL,12000,1.25,medium,精准匹配,0.95
freestanding coat rack,NEGATIVE,4500,0.85,low,直接否定,0.00
...

---

Product information support (optional)

To improve classification accuracy, users can provide product information:

Input methods

Method 1: command-line parameter

python workflow.py B07PWTJ4H1 US --product-info product.json

Method 2: interactive collection

请输入产品核心属性（用逗号分隔）:
> Wall Mount, 5 Hooks, 16.5 inches, Heavy Duty

Product information JSON format

{
  "product_name": "Coat Rack Wall Mount",
  "material": "Wood",
  "features": ["Wall Mount", "5 Hooks", "16.5 inches", "Heavy Duty"],
  "use_cases": ["Entryway", "Bathroom", "Mudroom", "Garage"],
  "negative_features": ["Freestanding", "Over Door", "Floor"]
}

---

Sorftime API reference

Keyword-related endpoints

Endpoint	Call cost	Parameters	Returns
product_traffic_terms	1	asin, site	Product traffic keywords
competitor_product_keywords	1	asin, site	Competitor placement keywords
category_keywords	1	nodeId, site	Category core keywords
keyword_related_words	1	searchKeyword, site	Extended long-tail keywords
keyword_detail	1	keyword, site	Keyword details
product_detail	1	asin, site	Product details

Call format

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":N,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{"amzSite":"US","KEY":"VALUE"}}}'

---

Supported marketplaces

Amazon: US, GB, DE, FR, IN, CA, JP, ES, IT, MX, AE, AU, BR, SA

---

Notes

1. API Key configuration: automatically from .mcp.json read
2. Data deduplication: normalization (lowercase, remove special characters)
3. LLM classification: batch processing, 150 keywords per batch
4. Output encoding: UTF-8, supports Chinese and special characters
5. Report naming: {ASIN}_{Site}_{YYYYMMDD} format

---

Troubleshooting

Issue 1: API returns "No corresponding product found"

Cause: ASIN does not exist in the Sorftime database Solution:

1. Use product_search to verify the ASIN
2. Check whether the marketplace is correct

Issue 2: Inaccurate classification results

Cause: missing product information context or rule-based classification was used Solution:

1. Provide a product information JSON file
2. Run in the Claude Code environment to use LLM classification
3. Manually perform LLM classification and save to categorized_result.json

Issue 3: Insufficient number of extended long-tail keywords

Cause: inaccurate core keyword selection or API rate limiting Solution:

1. Adjust the core keyword selection strategy, increase the search volume weight
2. Reduce the --long-tail-limit count to avoid API rate limiting
3. Use --skip-long-tail to skip long-tail expansion

Issue 4: Classification shows "Classification failed or no results provided" or rule-based classification was used

Cause: running in a command-line environment, LLM classification was not triggered Solution:

1. Use the --claude-code-env parameter to force-enable LLM classification mode:

   python workflow.py B07PWTJ4H1 US --claude-code-env
   

2. The system will output a classification prompt; copy the prompt and send it to Claude to perform classification
3. Save the classification results as categorized_result.json
4. Re-running workflow.py will automatically load the classification results and regenerate the report

Issue 5: How to perform LLM classification manually

Scenario: data was collected but classification is inaccurate Solution:

1. View the output directory's classification_prompt.txt
2. Send the prompt to Claude for classification
3. Save the classification result as categorized_result.json
4. Run the report regeneration script

---

Reference Documentation

• Sorftime API Documentation
• Classification Rules Description

---

Manual LLM Classification Process

If the rule-based classification results are inaccurate, you can manually perform LLM classification:

Step 1: View the classification prompt

cat keyword-reports/{ASIN}_{Site}_{YYYYMMDD}/classification_prompt.txt

Step 2: Send the prompt to Claude

Copy the entire prompt content and send it to Claude for classification

Step 3: Save the classification result

Save the JSON returned by Claude to:

keyword-reports/{ASIN}_{Site}_{YYYYMMDD}/categorized_result.json

Step 4: Regenerate the report

regenerate_reports.py Supports multiple usage methods:

Method 1: Run from within the report directory (auto-detect)

cd keyword-reports/{ASIN}_{Site}_{YYYYMMDD}/
python ../../.claude/skills/keyword-research/scripts/regenerate_reports.py

Method 2: Specify ASIN and site

python .claude/skills/keyword-research/scripts/regenerate_reports.py --asin B0FG6QG8C8 --site US

Method 3: Specify the full output directory

python .claude/skills/keyword-research/scripts/regenerate_reports.py --dir "keyword-reports\B0FG6QG8C8_US_20260314"

Method 4: List all available report directories

python .claude/skills/keyword-research/scripts/regenerate_reports.py --list

---

Version Update Log

v1.3 (2026-03-14)

• ✅ Optimized regenerate_reports.py: Removed hardcoded ASIN
• ✅ Supports multiple usage methods:
  • Run from within the report directory (auto-detect)
  • Use --asis and --site parameters to specify
  • Use --dir parameter to specify the full directory
  • Use --list to list all available reports
• ✅ Improved error messages: More user-friendly error messages and help documentation

v1.2 (2026-03-14)

• ✅ Fixed the LLM classification trigger issue
• ✅ Added --claude-code-env parameter to force-enable LLM classification
• ✅ Improved environment detection logic
• ✅ Automatically trigger LLM classification in the Claude Code environment
• ✅ Automatically use the LLM results to regenerate the report after classification is complete

v1.1 (2026-03-14)

• ✅ Added Claude Code environment detection
• ✅ Added --skip-classification option
• ✅ Improved rule-based classification: expanded IP brand word recognition
• ✅ Improved rule-based classification: added theme attribute words
• ✅ Updated troubleshooting documentation

v1.0 (2026-03-13)

• Initial version
• Supports Sorftime API data collection
• Supports 8-dimensional intelligent classification
• Generate Markdown/CSV/HTML reports

---

This skill version: v1.3 | Last updated: 2026-03-14