our-claude-skills/custom-skills/34-seo-reporting-dashboard/code/CLAUDE.md

CLAUDE.md

Overview

SEO reporting dashboard and executive report generator. Aggregates outputs from all SEO skills (11-33) into stakeholder-ready reports with interactive HTML dashboards, trend analysis, and Korean-language executive summaries. This is the PRESENTATION LAYER that sits on top of skill 25 (KPI Framework) and all other skill outputs, providing a unified view of SEO performance across all audit dimensions.

Quick Start

pip install -r scripts/requirements.txt

# Aggregate outputs from all SEO skills
python scripts/report_aggregator.py --domain https://example.com --json

# Generate HTML dashboard
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html

# Generate Korean executive report
python scripts/executive_report.py --report aggregated_report.json --audience c-level --output report.md

Scripts

Script	Purpose	Key Output
report_aggregator.py	Collect and normalize outputs from all SEO skills	Unified aggregated report, cross-skill health score, priority issues
dashboard_generator.py	Generate interactive HTML dashboard with Chart.js	Self-contained HTML file with charts and responsive layout
executive_report.py	Korean-language executive summary generation	Markdown report tailored to audience level
base_client.py	Shared utilities	RateLimiter, ConfigManager, BaseAsyncClient

Report Aggregator

# Aggregate all skill outputs for a domain
python scripts/report_aggregator.py --domain https://example.com --json

# Specify output directory to scan
python scripts/report_aggregator.py --domain https://example.com --output-dir ./audit_outputs --json

# Filter by date range
python scripts/report_aggregator.py --domain https://example.com --from 2025-01-01 --to 2025-03-31 --json

# Save to file
python scripts/report_aggregator.py --domain https://example.com --json --output report.json

Capabilities:

• Scan for recent audit outputs from skills 11-33 (JSON files or Notion entries)
• Normalize data formats across skills into unified structure
• Merge findings by domain/date
• Compute cross-skill health scores with weighted dimensions
• Identify top-priority issues across all audits
• Timeline of audit history
• Support for both local file scanning and Notion database queries

Dashboard Generator

# Generate HTML dashboard from aggregated report
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html

# Custom title
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html --title "OurDigital SEO Dashboard"

Capabilities:

• Generate self-contained HTML dashboard (uses Chart.js from CDN)
• Health score gauge chart
• Traffic trend line chart
• Keyword ranking distribution bar chart
• Technical issues breakdown pie chart
• Competitor comparison radar chart
• Mobile-responsive layout with CSS grid
• Export as single .html file (no external dependencies)

Executive Report

# C-level executive summary (Korean)
python scripts/executive_report.py --report aggregated_report.json --audience c-level --output report.md

# Marketing team report
python scripts/executive_report.py --report aggregated_report.json --audience marketing --output report.md

# Technical team report
python scripts/executive_report.py --report aggregated_report.json --audience technical --output report.md

# Output to Notion instead of file
python scripts/executive_report.py --report aggregated_report.json --audience c-level --format notion

Capabilities:

• Korean-language executive summary generation
• Key wins and concerns identification
• Period-over-period comparison narrative
• Priority action items ranked by impact
• Stakeholder-appropriate language (non-technical for C-level)
• Support for C-level, marketing team, and technical team audiences
• Markdown output format

Ahrefs MCP Tools Used

Tool	Purpose
site-explorer-metrics	Fresh current organic metrics snapshot
site-explorer-metrics-history	Historical metrics for trend visualization

Output Format

{
  "domain": "example.com",
  "report_date": "2025-01-15",
  "overall_health": 72,
  "health_trend": "improving",
  "skills_included": [
    {"skill_id": 11, "skill_name": "comprehensive-audit", "audit_date": "2025-01-14"},
    {"skill_id": 25, "skill_name": "kpi-framework", "audit_date": "2025-01-15"}
  ],
  "category_scores": {
    "technical": 85,
    "on_page": 70,
    "performance": 60,
    "content": 75,
    "links": 68,
    "local": 65,
    "keywords": 72,
    "competitor": 58
  },
  "top_issues": [
    {"severity": "critical", "category": "performance", "description": "CLS exceeds threshold on mobile"},
    {"severity": "high", "category": "technical", "description": "12 pages with noindex tag incorrectly set"}
  ],
  "top_wins": [
    {"category": "links", "description": "Domain Rating increased by 3 points"},
    {"category": "keywords", "description": "15 new keywords entered top 10"}
  ],
  "timeline": [
    {"date": "2025-01-15", "skill": "kpi-framework", "health_score": 72},
    {"date": "2025-01-14", "skill": "comprehensive-audit", "health_score": 70}
  ],
  "audit_id": "DASH-20250115-001",
  "timestamp": "2025-01-15T14:30: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 Dashboard
Priority	Select	Based on overall health trend
Found Date	Date	Report date (YYYY-MM-DD)
Audit ID	Rich Text	Format: DASH-YYYYMMDD-NNN

Language Guidelines

• Report content in Korean (한국어)
• Keep technical English terms as-is (e.g., Health Score, Domain Rating, Core Web Vitals, Chart.js)
• URLs and code remain unchanged