our-claude-skills/custom-skills/25-seo-kpi-framework/code/CLAUDE.md

# CLAUDE.md

## Overview

SEO KPI and performance framework for unified metrics aggregation across all SEO dimensions. Establishes baselines, sets targets (30/60/90-day), generates executive summaries with health scores, provides tactical breakdowns, estimates ROI using Ahrefs traffic cost, and supports period-over-period comparison (MoM, QoQ).

## Quick Start

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

# Aggregate KPIs
python scripts/kpi_aggregator.py --url https://example.com --json

# Generate performance report
python scripts/performance_reporter.py --url https://example.com --period monthly --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `kpi_aggregator.py` | Aggregate KPIs across all SEO dimensions | Unified KPI dashboard, health score, baselines |
| `performance_reporter.py` | Generate period-over-period performance reports | Trend analysis, executive summary, tactical breakdown |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## KPI Aggregator

```bash
# Full KPI aggregation
python scripts/kpi_aggregator.py --url https://example.com --json

# Set baselines
python scripts/kpi_aggregator.py --url https://example.com --set-baseline --json

# Compare against baseline
python scripts/kpi_aggregator.py --url https://example.com --baseline baseline.json --json

# With ROI estimation
python scripts/kpi_aggregator.py --url https://example.com --roi --json
```

**Capabilities**:
- Unified KPI taxonomy across 7 dimensions:
  - Traffic KPIs (organic sessions, organic traffic value, traffic trend)
  - Ranking KPIs (visibility score, avg position, top10 keywords count)
  - Engagement KPIs (bounce rate, pages/session, avg session duration)
  - Technical KPIs (crawl errors, page speed score, mobile usability)
  - Content KPIs (indexed pages, content freshness score, thin content ratio)
  - Link KPIs (domain rating, referring domains, link velocity)
  - Local KPIs (GBP visibility, review score, citation accuracy)
- Multi-source data aggregation from Ahrefs and other skill outputs
- Baseline establishment and target setting (30/60/90 day)
- Overall health score (0-100) with weighted dimensions
- ROI estimation using Ahrefs organic traffic cost

## Performance Reporter

```bash
# Monthly report
python scripts/performance_reporter.py --url https://example.com --period monthly --json

# Quarterly report
python scripts/performance_reporter.py --url https://example.com --period quarterly --json

# Custom date range
python scripts/performance_reporter.py --url https://example.com --from 2025-01-01 --to 2025-03-31 --json

# Executive summary only
python scripts/performance_reporter.py --url https://example.com --period monthly --executive --json
```

**Capabilities**:
- Executive summary generation (health score, trend arrows, key wins/concerns)
- Period-over-period comparison (MoM, QoQ, YoY)
- Trend direction indicators (up improving, down declining, stable)
- Top wins and concerns identification
- Tactical breakdown with actionable next steps
- Target vs actual comparison with progress %
- Traffic value change (ROI proxy)

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `site-explorer-metrics` | Current organic metrics |
| `site-explorer-metrics-history` | Historical metrics trends |
| `site-explorer-metrics-by-country` | Country-level breakdown |
| `site-explorer-domain-rating-history` | DR trend over time |
| `site-explorer-total-search-volume-history` | Total keyword volume trend |

## Output Format

```json
{
  "url": "https://example.com",
  "health_score": 72,
  "health_trend": "improving",
  "kpis": {
    "traffic": {"organic_traffic": 15000, "traffic_value_usd": 45000, "trend": "up"},
    "rankings": {"visibility_score": 68, "avg_position": 18.5, "top10_count": 48},
    "links": {"domain_rating": 45, "referring_domains": 850, "velocity": "+15/month"},
    "technical": {"health_score": 85, "crawl_errors": 12},
    "content": {"indexed_pages": 320, "freshness_score": 70},
    "engagement": {"bounce_rate": 45, "pages_per_session": 2.8},
    "local": {"gbp_visibility": 80, "review_score": 4.5}
  },
  "targets": {
    "30_day": {},
    "60_day": {},
    "90_day": {}
  },
  "executive_summary": {
    "top_wins": [],
    "top_concerns": [],
    "recommendations": []
  },
  "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 | Audited website URL |
| Category | Select | SEO KPI & Performance |
| Priority | Select | Based on health score trend |
| Found Date | Date | Report date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: KPI-YYYYMMDD-NNN |

### Language Guidelines

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