Andrew Yim
6ac547e78f
Some checks failed
Verify Skills / verify-skills (push) Has been cancelled
Adopt: directory keeps its NN- ordering prefix; skill `name:` is the clean form without it (dir 16-seo-schema-validator → name: seo-schema-validator). Nicer to invoke, matches the original desktop/SKILL.md names, still globally unique. - 71 root SKILL.md: name: NN-foo → name: foo (flat skills + reference-curator suite). Plugins (mac-optimizer/multi-agent-guide/dintel-bootstrap) already clean; 95 already clean. - scripts/migrate_skill_root.py: derive name = dirname minus NN- prefix (skill_name()). - CLAUDE.md + SKILL-MIGRATION-GUIDE.md: document the dir-prefix / clean-name convention. verify_skills.py: 0 name collisions across all renamed skills. (The ~/.claude/skills symlinks were re-pointed to the clean names separately — filesystem only.) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
167 lines
7.7 KiB
Markdown
167 lines
7.7 KiB
Markdown
---
|
|
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="<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):**
|
|
```bash
|
|
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:
|
|
|
|
```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
|