feat(seo-skills): multi-backend Data Source Selection (#7)
Replaces single-vendor (Ahrefs-only) tool defaults with a per-task backend menu across all 14 SEO skills. Each skill now lists every capable MCP in allowed-tools and documents how to pick between Semrush, Ahrefs, OurSEO Agent (CLI + MCP), DataForSEO, and GSC in its SKILL.md Data Source Selection section. Tool stubs (~40 new files) populated per skill with capability deltas, call patterns, and explicit "not for this skill when" callouts so the menu is self-correcting. Skills affected: 19-keyword-strategy, 20-serp-analysis, 21-position-tracking, 22-link-building, 23-content-strategy, 24-ecommerce, 25-kpi-framework, 26-international, 27-ai-visibility, 28-knowledge-graph, 31-competitor-intel, 32-crawl-budget, 33-migration-planner, 34-reporting-dashboard. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -21,19 +21,80 @@ Aggregate SEO KPIs across all dimensions into a unified dashboard. Establish bas
|
||||
5. **Performance Reporting** - Period-over-period comparison with executive summary
|
||||
6. **Tactical Breakdown** - Actionable next steps per dimension
|
||||
|
||||
## MCP Tool Usage
|
||||
## Data Source Selection
|
||||
|
||||
### SEO Data
|
||||
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):**
|
||||
```
|
||||
our-seo-agent CLI: Primary metrics source (future); use --input for pre-fetched JSON
|
||||
WebSearch / WebFetch: Supplementary metrics data
|
||||
mcp__semrush__overview_research(query="<domain>", database="us")
|
||||
mcp__semrush__organic_research(query="<domain>", database="us")
|
||||
mcp__semrush__tracking_research(query="<keyword>", database="us")
|
||||
```
|
||||
|
||||
### Notion for Report Storage
|
||||
**Ahrefs MCP (backlinks + traffic-value alternate):**
|
||||
```
|
||||
mcp__notion__*: Save reports to SEO Audit Log database
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user