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

name, description

name	description
seo-kpi-framework	SEO KPI and performance framework for unified metrics, health scores, ROI, and period-over-period reporting. Triggers: SEO KPI, performance report, health score, SEO metrics, ROI, baseline, targets, SEO 성과 지표, KPI 대시보드, SEO 성과 보고서.

SEO KPI & Performance Framework

Purpose

Aggregate SEO KPIs across all dimensions into a unified dashboard. Establish baselines, set targets (30/60/90-day), generate executive summaries with health scores, provide tactical breakdowns, estimate ROI using our-seo-agent traffic cost data, and support period-over-period comparison (MoM, QoQ, YoY).

Core Capabilities

1. KPI Aggregation - Unified metrics across 7 dimensions (traffic, rankings, links, technical, content, engagement, local)
2. Health Scoring - Weighted 0-100 score with trend direction
3. Baseline & Targets - Establish baselines and set 30/60/90 day growth targets
4. ROI Estimation - Traffic value from organic cost data
5. Performance Reporting - Period-over-period comparison with executive summary
6. Tactical Breakdown - Actionable next steps per dimension

Data Source Selection

KPI framework is an aggregator — it pulls one metric per dimension from the best backend for that metric, then composites them. Pick per metric, not per skill invocation. Don't pull every metric from every backend.

Per-metric backend defaults

KPI dimension	Default backend	Alternates	Notes
Organic traffic + traffic value	Semrush overview_research	Ahrefs site-explorer-metrics	Modelled estimates — pick one per audit and document it.
Visibility / ranking distribution	Semrush tracking_research (when project exists), else Ahrefs rank-tracker-*	OurSEO check_serp for spot positions	First-party alternative: GSC position data.
Backlinks / DR	Ahrefs site-explorer-domain-rating + -backlinks-stats	Semrush backlink_research	Ahrefs has the strongest backlink graph.
Technical health	OurSEO our audit tech + our analyze mysql-batch	Ahrefs site-audit-issues, Semrush siteaudit_research	OurSEO is the deepest because it owns the crawl + fix engine.
Indexed pages	OurSEO our research google index / mcp__ourseo__check_index	GSC index coverage report	First-party best.
Content freshness	OurSEO crawl_website (extracts last-modified)	Ahrefs site-explorer-pages-history
First-party clicks / impressions / CTR	GSC via our research search-console	Ahrefs gsc-* if Ahrefs project connected	Required for accurate KPI — Google's own data, not modelled.
GA4 / on-site engagement	OurSEO CLI: our research ga4 *	(none equivalent in Semrush/Ahrefs at the property level)	Sessions, bounce, conversion.
Local visibility (GBP)	OurSEO our collect gbp * + our audit local	(Semrush local listings only in US/EU)	First-party Google Business Profile data.

How to pick

1. User named a backend for a specific metric → use it for that metric.
2. User preference memory — read feedback_seo_tool_preferences.md; honor per-task defaults.
3. Apply per-metric defaults from the table above. Default to first-party (GSC, GA4, GBP) whenever it's available — every modelled estimate weakens the composite.
4. Be consistent across reporting periods. If the prior baseline used Semrush traffic value, use Semrush traffic value this run too — switching mid-stream breaks the trend.
5. Document every metric's source in the report Overview.

Backend call patterns

Semrush MCP (default traffic + visibility):

mcp__semrush__overview_research(query="<domain>", database="us")
mcp__semrush__organic_research(query="<domain>", database="us")
mcp__semrush__tracking_research(query="<keyword>", database="us")

Ahrefs MCP (backlinks + traffic-value alternate):

mcp__ahrefs__site-explorer-metrics(target="<domain>")
mcp__ahrefs__site-explorer-domain-rating(target="<domain>")
mcp__ahrefs__site-explorer-domain-rating-history(target="<domain>", history="weekly")
mcp__ahrefs__site-explorer-backlinks-stats(target="<domain>")

OurSEO (technical + indexation + first-party):

our audit tech https://<domain>
our analyze mysql-batch --session <id>
our research google index --domain <domain>
our research search-console queries --site sc-domain:<domain> --days 28
our research ga4 traffic --property-id <id>
our audit local https://<domain> --gbp-profile <client>

OurSEO MCP (Claude Desktop alternate):

mcp__ourseo__check_index(domain="<domain>")
mcp__ourseo__audit_page(url="<url>", audit_type="tech")

Reporting rule

Every KPI report's Overview section MUST include a "Sources" subsection listing the data source per metric. Example:

### Sources
- Organic traffic: Semrush overview_research (database=us)
- Backlinks / DR: Ahrefs site-explorer-domain-rating
- Indexed pages: OurSEO check_index
- Clicks / Impressions: GSC (28d)
- GBP visibility: OurSEO collect gbp (profile=client)

This is non-negotiable — period-over-period KPI comparisons are meaningless without per-metric source attribution.

Workflow

1. KPI Aggregation

1. Fetch site-explorer-metrics for current organic data
2. Extract traffic, ranking, link, technical, content metrics
3. Calculate dimension scores with weights (traffic 25%, rankings 20%, technical 20%, content 15%, links 15%, local 5%)
4. Compute overall health score (0-100)
5. Set 30/60/90 day targets (5%/10%/20% improvement)
6. Estimate ROI from traffic cost data (use our-seo-agent CLI or pre-fetched JSON)

2. Performance Reporting

1. Determine date range from period (monthly/quarterly/yearly/custom)
2. Fetch metrics-history for current and previous period
3. Calculate period-over-period changes
4. Identify wins (>5% improvement) and concerns (>5% decline)
5. Generate executive summary with trend arrows
6. Create tactical breakdown with actionable next steps
7. Compare against targets if provided

Output Format

## SEO KPI Dashboard: [domain]

### Health Score: [score]/100 ([trend])

### KPI Summary
| Dimension | Score | Key Metric | Trend |
|-----------|-------|------------|-------|
| Traffic | [score] | [organic_traffic] | [arrow] |
| Rankings | [score] | [visibility] | [arrow] |
| Links | [score] | [DR] | [arrow] |
| Technical | [score] | [health] | [arrow] |
| Content | [score] | [indexed_pages] | [arrow] |

### Executive Summary
- Top Wins: [list]
- Top Concerns: [list]
- Recommendations: [list]

### Targets (30/60/90 day)
[Target table with progress bars]

Key Metrics

Dimension	Metrics	Source
Traffic	Organic traffic, traffic value (USD)	site-explorer-metrics
Rankings	Visibility score, top10 keywords	site-explorer-metrics
Links	Domain rating, referring domains	domain-rating, metrics
Technical	Pages crawled, technical health	site-explorer-metrics
Content	Indexed pages, freshness score	site-explorer-metrics
Local	GBP visibility, review score	External data

Limitations

• Local KPIs require external GBP data (not available via our-seo-agent)
• Engagement KPIs (bounce rate, session duration) require Google Analytics
• Technical health is estimated heuristically from available data
• ROI is estimated from organic traffic cost data, not actual revenue

Notion Output (Required)

All reports MUST be saved to OurDigital SEO Audit Log:

• Database ID: 2c8581e5-8a1e-8035-880b-e38cefc2f3ef
• Properties: Issue (title), Site (url), Category, Priority, Found Date, Audit ID
• Language: Korean with English technical terms
• Audit ID Format: KPI-YYYYMMDD-NNN