--- name: seo-kpi-framework description: | 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="", database="us") mcp__semrush__organic_research(query="", database="us") mcp__semrush__tracking_research(query="", database="us") ``` **Ahrefs MCP (backlinks + traffic-value alternate):** ``` mcp__ahrefs__site-explorer-metrics(target="") mcp__ahrefs__site-explorer-domain-rating(target="") mcp__ahrefs__site-explorer-domain-rating-history(target="", history="weekly") mcp__ahrefs__site-explorer-backlinks-stats(target="") ``` **OurSEO (technical + indexation + first-party):** ```bash our audit tech https:// our analyze mysql-batch --session our research google index --domain our research search-console queries --site sc-domain: --days 28 our research ga4 traffic --property-id our audit local https:// --gbp-profile ``` **OurSEO MCP (Claude Desktop alternate):** ``` mcp__ourseo__check_index(domain="") mcp__ourseo__audit_page(url="", audit_type="tech") ``` ### Reporting rule Every KPI report's **Overview** section MUST include a "Sources" subsection listing the data source per metric. Example: ```markdown ### 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 ```markdown ## 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