our-claude-skills/custom-skills/31-seo-competitor-intel/code/CLAUDE.md

# CLAUDE.md

## Overview

Competitor intelligence and benchmarking tool for comprehensive SEO competitive analysis. Auto-discovers competitors via Ahrefs, builds competitor profile cards (DR, traffic, keywords, backlinks, content volume), creates head-to-head comparison matrices, tracks traffic trends, analyzes keyword overlap, compares content freshness/volume, and scores competitive threats. Supports Korean market competitor analysis including Naver Blog/Cafe presence.

## Quick Start

```bash
pip install -r scripts/requirements.txt

# Competitor profiling
python scripts/competitor_profiler.py --target https://example.com --json

# Competitive monitoring
python scripts/competitive_monitor.py --target https://example.com --period 30 --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `competitor_profiler.py` | Build competitor profiles and comparison matrix | Competitor cards, head-to-head matrix, threat scores |
| `competitive_monitor.py` | Track competitive changes over time | Traffic trends, keyword movement, content velocity |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Competitor Profiler

```bash
# Auto-discover and profile competitors
python scripts/competitor_profiler.py --target https://example.com --json

# Specify competitors manually
python scripts/competitor_profiler.py --target https://example.com --competitor https://comp1.com --competitor https://comp2.com --json

# Limit auto-discovery count
python scripts/competitor_profiler.py --target https://example.com --max-competitors 10 --json

# Include Korean market analysis
python scripts/competitor_profiler.py --target https://example.com --korean-market --json
```

**Capabilities**:
- Competitor auto-discovery via Ahrefs organic-competitors
- Competitor profile cards:
  - Domain Rating (DR)
  - Organic traffic estimate
  - Total organic keywords
  - Referring domains count
  - Top pages count
  - Content volume estimate
- Head-to-head comparison matrix across all SEO dimensions
- Keyword overlap analysis (shared, unique to target, unique to competitor, gap)
- Content volume and freshness comparison
- Competitive threat scoring (0-100) based on growth trajectory, keyword overlap, DR gap
- Korean market: Naver Blog/Cafe presence detection for competitors

## Competitive Monitor

```bash
# 30-day competitive monitoring
python scripts/competitive_monitor.py --target https://example.com --period 30 --json

# With specific competitors
python scripts/competitive_monitor.py --target https://example.com --competitor https://comp1.com --period 60 --json

# Traffic trend comparison
python scripts/competitive_monitor.py --target https://example.com --scope traffic --period 90 --json
```

**Capabilities**:
- Traffic trend comparison (6-12 month history)
- DR trend comparison over time
- New/lost keyword tracking per competitor
- Referring domain growth comparison
- Content publication velocity comparison
- Top page changes (new top pages, declining pages)
- Alert generation for significant competitive movements
- Market share estimation based on organic traffic

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `site-explorer-metrics` | Current organic metrics |
| `site-explorer-metrics-history` | Historical metrics trends |
| `site-explorer-organic-competitors` | Discover organic competitors |
| `site-explorer-organic-keywords` | Keyword rankings per domain |
| `site-explorer-top-pages` | Top performing pages |
| `site-explorer-pages-by-traffic` | Pages ranked by traffic |
| `site-explorer-domain-rating` | Domain Rating |
| `site-explorer-domain-rating-history` | DR trend |
| `site-explorer-referring-domains` | Referring domain list |
| `site-explorer-backlinks-stats` | Backlink overview |
| `site-explorer-pages-history` | Page index history |

## Output Format

```json
{
  "target": "example.com",
  "competitors": [
    {
      "domain": "competitor1.com",
      "profile": {
        "domain_rating": 55,
        "organic_traffic": 25000,
        "organic_keywords": 3500,
        "referring_domains": 1200,
        "top_pages": 150
      },
      "threat_score": 78,
      "keyword_overlap": {
        "shared": 450,
        "unique_competitor": 800,
        "unique_target": 600,
        "gap": 350
      }
    }
  ],
  "comparison_matrix": {},
  "market_position": "challenger",
  "timestamp": "2025-01-01T00:00:00"
}
```

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Target website URL |
| Category | Select | Competitor Intelligence |
| Priority | Select | Based on threat level |
| Found Date | Date | Report date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: COMP-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Domain Rating, Organic Traffic, Threat Score)
- URLs and code remain unchanged