| name | ecommerce.price-history-analyzer |
| version | 1.1.0 |
| description | Analyze historical pricing, price wars, volatility, and Buy Box stability. Triggers: Keepa chart, price history, price trend, historical pricing. Use for long-term history, not current alerts; use price-monitor for recent changes.
|
| allowed-tools | ["Bash","Read","Write"] |
IMPORTANT — Working Directory: All scripts in this skill MUST be executed with the working directory set to the absolute path of the directory containing this SKILL.md file (the skill root directory). Always cd into this directory before running any command. Do NOT use relative paths or shell shortcuts like ~ in paths, as they may not be resolved by the execution environment.
Price History Analyzer v1.1.0
Is there a price war? Are prices stable?
Analyze price wars, volatility, and Buy Box stability using Keepa historical data.
Core Questions
— Is there a price war?
— Are prices stable?
— Can I win the Buy Box?
Clarify or Infer Before Querying
- If ASIN is missing, ask for the ASIN or use product search to find candidate ASINs.
- Clarify marketplace and desired history window when relevant.
- Do not use only a product keyword for historical price analysis unless an ASIN can be resolved.
When to Use
- Evaluating market pricing stability before entry
- Assessing price war risk
- Understanding Buy Box competition
- Analyzing historical pricing trends
Differs From / Not Applicable
- Use price-monitor for recent/current price alerts and competitor changes.
- Use competitor-analyzer for broader competitor metrics.
- Use this skill for historical price trend, volatility, price wars, and Buy Box stability.
Data Source
| Source | Endpoint | Data |
|---|
| Keepa | /api/v1/tools/research/keepa/productSeries | Buy Box history, BSR, ratings, monthly sold |
| NexScope Proxy | /api/v1/tools/research/amazon/search | Current product list |
Keepa Data Fields
| Field | Description |
|---|
buyboxPrice | Historical Buy Box prices with timestamps |
bsrSub | BSR ranking history by category |
ratingCount | Review count history |
monthlySold | Monthly sales history |
Key Metrics
| Metric | Description | Thresholds |
|---|
| Price War Score | Overall price war intensity (0-100) | < 25 LOW, 25-50 MODERATE, 50-75 HIGH, > 75 SEVERE |
| PVI (Price Volatility Index) | Standard deviation / mean × 100 | < 5% LOW, 5-10% MEDIUM, 10-20% HIGH, > 20% EXTREME |
| Buy Box Stability | Changes per day | < 0.5 VERY_STABLE, 0.5-1 STABLE, 1-2 MODERATE, 2-5 UNSTABLE, > 5 CHAOTIC |
| Price Trend | Direction over time | RISING, STABLE, DECLINING, CRASHED |
Price War Score Factors
| Factor | Weight | Description |
|---|
| Volatility | 35% | PVI contribution (max 35 points) |
| Trend | 25% | Declining trend adds points |
| Price Drops | 25% | Frequency of significant drops |
| Buy Box Instability | 15% | Changes per day factor |
Price War Levels
| Level | Score | Signal | Action |
|---|
| 🟢 LOW | 0-25 | Healthy pricing | Safe to enter |
| 🟡 MODERATE | 25-50 | Some competition | Monitor weekly |
| 🟠 HIGH | 50-75 | Active price war | Caution required |
| 🔴 SEVERE | 75-100 | Intense price war | Avoid market |
⚠️ MANDATORY: Charts & Display Rules
- Generate charts by default for full analytical reports — use
--chart with an output directory unless the user asks for a quick text-only result or chart data is unavailable.
- Send generated charts to the user — when charts are created, share all chart PNGs immediately.
- All chart styling is driven by
ecommerce_chart_helpers.py which reads from chart_style.json (derived from references/display-rules.md). Do NOT hardcode colors in scripts.
Usage
python3 scripts/price_history_analyzer.py '{"keyword": "face wash"}'
python3 scripts/price_history_analyzer.py '{"asin": "B07RL88DD2"}'
python3 scripts/price_history_analyzer.py '{"keyword": "yoga mat", "market": "UK"}'
python3 scripts/price_history_analyzer.py '{"keyword": "face wash"}' --chart /tmp/output
Parameters
| Parameter | Type | Default | Description |
|---|
keyword | string | - | Search keyword |
asin | string | - | Specific ASIN to analyze |
market | string | | Marketplace (US/UK/DE/FR/CA/JP) |
Output Structure
{
"keyword": "face wash",
"market": "US",
"analysis_date2026-04-09",
"products_analyzed": 5,
"price_analysis": {
"data_points": 265,
"period_days": 90,
"current_price": 7.49,
"min_price": 5.36,
"max_price": 7.49,
"avg_price": 6.82,
"std_dev": 0.42,
"pvi": 6.1,
"volatility_levelLOW",
"price_changes_count": 15,
"price_drops": 3,
"price_increases": 5,
"trend_pct": 2.1,
"trend_directionSTABLE"
},
"buybox_analysis": {
"stabilityMODERATE",
"stability_score": 50,
"total_changes": 54,
"changes_per_day": 1.8,
"outages": 2,
"outage_pct": 3.7
},
"price_war_score": {
"score": 9,
"levelLOW",
: "🟢",
: {
"volatility": 9,
"trend": 0,
"price_drops": 0,
"buybox_instability": 0
}
},
"insights": {
"summary🟢 Healthy pricing. Score 9, volatility 6.1%. Safe market.",
"assessments": [...],
"recommendations": [...]
}
}
Charts Generated
| Chart | Description | File |
|---|
| Price History | Line chart with trend | 1_price_history.png |
| Price War Score | Gauge visualization | 2_price_war_score.png |
| Volatility & Buy Box | Side-by-side summary | 3_volatility_buybox.png |
Insights Generated
| Insight | Trigger |
|---|
| Healthy Pricing | Score < 25 |
| Moderate Competition | Score 25-50 |
| Active Price War | Score 50-75 |
| Severe Price War | Score > 75 |
| High Volatility | PVI > 15% |
| Low Volatility | PVI < 5% |
| Downward Trend | Declining direction |
| Upward Trend | Rising direction |
| Buy Box Chaotic | Stability = CHAOTIC |
| Buy Box Stable | Stability = VERY_STABLE |
Recommendations
| Situation | Recommendation |
|---|
| Score < 25 | Normal competitive strategy viable |
| Score 25-50 | Monitor prices weekly, build margin buffer |
| Score > 50 | Avoid price competition, differentiate on value |
| Declining trend | Factor declining prices into margin calculations |
| Organic > 90% | Competitor relies on organic — vulnerable to PPC attack |
| Organic < 50% | Competitor heavily PPC-dependent — may have weak organic |
Workflow Integration
📊 Validation Phase
├── demand-validator → Validate demand is real
├── price-history-analyzer → Check for price wars ← YOU ARE HERE
└── product-validator → Validate product data
Limitations
- Keepa data availability varies by ASIN
- Historical data typically 90 days
- API calls consume Keepa tokens
- Category cleaner applied (may reduce sample size)
Environment Variables
| Variable | Required | Description |
|---|
NEXSCOPE_PROXY_BASE | Yes | NexScope proxy base URL |
NEXSCOPE_API_KEY | Yes | NexScope proxy API key |
References
references/display-rules.md — Chart styling guidelines
