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>
2026-05-14 03:15:32 +09:00
parent 1ca84f67ed
commit e527fb4b0f
71 changed files with 2647 additions and 258 deletions
--- a/custom-skills/26-seo-international/desktop/SKILL.md
+++ b/custom-skills/26-seo-international/desktop/SKILL.md
@@ -19,24 +19,68 @@ Audit international SEO implementation: hreflang tags, URL structure patterns, c
 4. **Redirect Logic Audit** - IP-based, Accept-Language redirects, forced redirect detection
 5. **Korean Expansion** - Priority markets (ja, zh, en), CJK URL issues, regional search engines

-## MCP Tool Usage
+## Data Source Selection

-### SEO Data
-```
-our-seo-agent CLI: Primary country metrics source (future); use --input for pre-fetched JSON
-WebSearch / WebFetch: Supplementary international data
+International SEO spans **hreflang validation** (crawl-derived), **content parity** (crawl-derived), and **per-country traffic** (modelled). Pick one backend per data class.
+
+| Backend | Best for | Notes |
+|---|---|---|
+| **OurSEO** (CLI + MCP) | **Default** — hreflang validation, content parity, redirect logic, fix engine | CLI: `our collect crawl`, `our audit tech`, `our fix hreflang`. MCP: `mcp__ourseo__crawl_website`, `mcp__ourseo__audit_page`. Only backend that owns the hreflang FIX path. |
+| **Ahrefs MCP** (`mcp__ahrefs__*`) | Per-country traffic distribution; hreflang issues from Ahrefs site audit | `web-analytics-countries`, `site-explorer-metrics-by-country`, `site-audit-issues`. |
+| **Semrush MCP** (`mcp__semrush__*`) | Per-database organic visibility (compare `kr`, `jp`, `us`, etc.) | `organic_research` with different `database` params; `siteaudit_research` for site-audit issues. |
+| **OurSEO CLI — Naver / per-region SERP** | Korean expansion + regional search engine SERP checks | `our research naver serp`, `our research keywords compare --engines naver`. |
+| **WebSearch / WebFetch** | Test geo/Accept-Language redirect behaviour, verify ccTLD handling | Required for redirect-logic audit — can't be done via SEO MCPs. |
+| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Per-country SERP fallback when `our` CLI isn't running | `serp_organic_live_advanced` with `location_code` per country. |
+
+### How to pick
+
+1. **User named a backend explicitly** → use it.
+2. **User preference memory** — read `feedback_seo_tool_preferences.md`; honor the task-type default.
+3. **Task is hreflang validation / parity / fix** → use **OurSEO** (CLI primary, MCP for Desktop). No alternative owns the fix engine.
+4. **Task is per-country traffic distribution** → Ahrefs `web-analytics-countries` or Semrush `organic_research` across multiple `database` values.
+5. **Task is redirect-logic audit** (IP-based / Accept-Language) → WebFetch with explicit headers.
+6. **Default**: **OurSEO crawl + hreflang audit** for the validation work; Semrush MCP for cross-market visibility.
+7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`.
+
+### Backend call patterns
+
+**OurSEO CLI (default — hreflang validation + fix):**
+```bash
+our collect crawl https://<site> --max-pages 200
+our audit tech https://<site>
+our fix hreflang --site https://<site>
 ```

-### Notion for Report Storage
+**OurSEO MCP (Claude Desktop):**
 ```
-mcp__notion__notion-create-pages: Save audit report to SEO Audit Log database
+mcp__ourseo__crawl_website(url="<site>", max_pages=200)
+mcp__ourseo__audit_page(url="<url>", audit_type="tech")
 ```

-### WebSearch for Best Practices
+**Ahrefs MCP (per-country traffic):**
 ```
-WebSearch: Research hreflang implementation guides and regional search engine requirements
+mcp__ahrefs__web-analytics-countries(domain="<site>")
+mcp__ahrefs__site-explorer-metrics-by-country(target="<site>")
+mcp__ahrefs__site-audit-issues(project_id="<id>")
 ```

+**Semrush MCP (cross-market visibility):**
+```
+mcp__semrush__organic_research(query="<site>", database="kr")
+mcp__semrush__organic_research(query="<site>", database="jp")
+mcp__semrush__siteaudit_research(query="<site>", database="us")
+```
+
+**Redirect-logic audit (manual):**
+```
+WebFetch: https://<site>/ with Accept-Language: ko-KR
+WebFetch: https://<site>/ with Accept-Language: ja-JP
+WebFetch: https://<site>/ with Accept-Language: en-US
+# Compare redirect chains; flag forced geo/language redirects.
+```
+
+Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like.
+
 ## Workflow

 ### 1. Hreflang Validation
--- a/custom-skills/26-seo-international/desktop/skill.yaml
+++ b/custom-skills/26-seo-international/desktop/skill.yaml
@@ -1,8 +1,16 @@
 name: seo-international
 description: |
  International SEO audit and hreflang validation. Triggers: hreflang, international SEO, multi-language, multi-region, content parity, x-default, ccTLD.
+
+# Allowed tools list every backend the skill can pull international-SEO data from.
+# Per-task selection happens in SKILL.md > Data Source Selection — NOT here.
 allowed-tools:
-  - mcp__ahrefs__*
+  - mcp__ourseo__*                # default — crawl + hreflang validation + parity check
+  - mcp__ahrefs__*                # site-audit-* for hreflang issues, web-analytics-countries-*, site-explorer-metrics-by-country
+  - mcp__claude_ai_Ahrefs__*      # Ahrefs (Claude.ai namespace)
+  - mcp__semrush__*               # siteaudit_research, organic_research by database
+  - mcp__dfs-mcp__*               # DataForSEO MCP fallback for per-country SERP
+  - Bash                          # `our` CLI — crawl, audit, hreflang fix
  - mcp__notion__*
  - WebSearch
  - WebFetch
--- a/custom-skills/26-seo-international/desktop/tools/ourseo.md
+++ b/custom-skills/26-seo-international/desktop/tools/ourseo.md
@@ -0,0 +1,42 @@
+# OurSEO Agent (CLI + MCP)
+
+**Default** for hreflang validation, content parity, redirect logic, and the fix engine. Only backend that owns the hreflang **fix** path end-to-end.
+
+## CLI commands (Claude Code)
+
+```bash
+# Crawl all language versions
+our collect crawl https://<site> --max-pages 500
+
+# Technical audit including hreflang
+our audit tech https://<site>
+
+# Hreflang fix (writes back to CMS if --deploy and CMS adapter configured)
+our fix hreflang --site https://<site>
+
+# Per-region SERP / Naver expansion checks
+our research naver serp "<keyword>"
+our research keywords compare "<keyword>" --engines naver
+```
+
+## MCP tools (Claude Desktop)
+
+```
+mcp__ourseo__crawl_website(url="<site>", max_pages=500)
+mcp__ourseo__audit_page(url="<url>", audit_type="tech")
+```
+
+## Strengths for this skill
+
+- **Hreflang validation:** bidirectional links, self-reference, x-default, language/region code validation.
+- **Hreflang fix:** auto-corrects tags via Ghost/WordPress/Strapi adapters.
+- **Content parity audit:** page counts, key-page availability, freshness comparison across language versions.
+- **Naver / regional engine coverage** — Semrush/Ahrefs only cover Google.
+
+## Not for this skill when
+
+- **Per-country traffic distribution KPI** — Ahrefs `web-analytics-countries` is cleaner.
+- **Per-database organic visibility comparison** — Semrush per-`database` calls.
+- **Redirect-logic audit with custom Accept-Language headers** — WebFetch directly.
+
+See also: `docs/user-manual.md` for the full `our fix` command surface.
--- a/custom-skills/26-seo-international/desktop/tools/semrush.md
+++ b/custom-skills/26-seo-international/desktop/tools/semrush.md
@@ -0,0 +1,36 @@
+# Semrush MCP
+
+Use for **per-database organic visibility** across markets — Semrush's database-per-market model is well-suited to international SEO comparison.
+
+Call pattern: discovery → `get_report_schema` → `execute_report`.
+
+## Per-market comparison pattern
+
+```
+# Pull organic positions per database (one call per target market)
+mcp__semrush__organic_research(query="<domain>", database="us")
+mcp__semrush__organic_research(query="<domain>", database="kr")
+mcp__semrush__organic_research(query="<domain>", database="jp")
+mcp__semrush__organic_research(query="<domain>", database="cn")
+mcp__semrush__organic_research(query="<domain>", database="de")
+
+# Cross-market visibility deltas surface content-parity gaps from a ranking perspective
+```
+
+## Key reports
+
+- `organic_research` — keywords/positions per `database`
+- `overview_research` — domain traffic per market
+- `siteaudit_research` — site-wide audit (catches hreflang issues with limitations)
+- `keyword_research` — per-market keyword expansion
+
+## Strengths for this skill
+
+- Quickest "where am I ranking in market X vs market Y" comparison.
+- Easy cross-database competitor pulls.
+
+## Not for this skill when
+
+- **Hreflang validation / parity audit / fix** — OurSEO is the default; only it owns the fix engine.
+- **Forced-redirect / Accept-Language audit** — WebFetch with explicit headers.
+- **Naver / regional engines** — Semrush is Google-only.