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:
Andrew Yim
@@ -19,35 +19,73 @@ Monitor keyword ranking positions, detect significant changes, calculate visibil
|
||||
4. **Brand/Non-brand Segmentation** - Automatically classify keywords by brand relevance and search intent type
|
||||
5. **Competitor Comparison** - Compare keyword overlap, position gaps, and visibility scores against competitors
|
||||
|
||||
## MCP Tool Usage
|
||||
## Data Source Selection
|
||||
|
||||
### SEO Data (DataForSEO)
|
||||
This skill can pull rank data from multiple backends. **Pick one per task** — don't fan out by default (cost + rate limits).
|
||||
|
||||
**Primary — our-seo-agent CLI:**
|
||||
| Backend | Best for | Notes |
|
||||
|---|---|---|
|
||||
| **Ahrefs MCP** (`mcp__ahrefs__*`) | Default when an Ahrefs Rank Tracker project exists for the domain | `rank-tracker-overview`, `rank-tracker-serp-overview`, `rank-tracker-competitors-*`. Best historical view; data is what Ahrefs already polled. |
|
||||
| **Semrush MCP** (`mcp__semrush__*`) | Default when no Ahrefs project; English/major market position scans | `tracking_research`, `organic_research`. `database="us"` default; `"kr"` for Korean. |
|
||||
| **OurSEO CLI** (`our serp *`) | DataForSEO under the hood — full ranked-keywords pulls with volume, Korean-aware via `--location 2410` | Claude Code only (Bash). Commands: `our serp ranked-keywords`, `our serp domain-overview`, `our keywords volume`. |
|
||||
| **OurSEO MCP** (`mcp__ourseo__check_serp`) | One-off rank spot-check for a single keyword/domain pair | Cheap; no historical view — pair with prior runs in MySQL / SQLite if tracking over time. |
|
||||
| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Fallback when `our` CLI isn't running; historical rank overview | `dataforseo_labs_google_historical_rank_overview`, `dataforseo_labs_google_ranked_keywords`. |
|
||||
| **GSC** (via `our research search-console` or Ahrefs `gsc-*`) | **First-party position data** — what Google actually rendered for the verified site | Only first-party source — use to validate or replace estimated positions. |
|
||||
|
||||
### 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. **Site is verified in GSC** AND task is single-site tracking → prefer **GSC** for ground truth, supplement with Semrush/Ahrefs for competitor delta.
|
||||
4. **Ahrefs project exists for the domain** → prefer Ahrefs `rank-tracker-*`.
|
||||
5. **Default**: Semrush MCP for new tracking jobs; **`our serp ranked-keywords`** for Korean batch.
|
||||
6. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`.
|
||||
|
||||
### Backend call patterns
|
||||
|
||||
**Ahrefs MCP (when project exists):**
|
||||
```
|
||||
mcp__ahrefs__rank-tracker-overview(project_id="<id>")
|
||||
mcp__ahrefs__rank-tracker-serp-overview(project_id="<id>")
|
||||
mcp__ahrefs__rank-tracker-competitors-overview(project_id="<id>")
|
||||
mcp__ahrefs__rank-tracker-competitors-stats(project_id="<id>")
|
||||
```
|
||||
|
||||
**Semrush MCP (no Ahrefs project):**
|
||||
```
|
||||
mcp__semrush__tracking_research(query="<keyword>", database="us")
|
||||
mcp__semrush__get_report_schema(report_id="...")
|
||||
mcp__semrush__execute_report(report_id="...", params={...})
|
||||
```
|
||||
|
||||
**OurSEO CLI (Korean batch):**
|
||||
```bash
|
||||
our serp ranked-keywords <domain> --location 2410 --limit 100
|
||||
our serp ranked-keywords <domain> --location 2410 --limit 100 --format json
|
||||
our serp domain-overview <domain> --location 2410 --format json
|
||||
our keywords volume "<kw1>" "<kw2>" --location 2410 --language ko
|
||||
our serp domain-overview <domain> --location 2410
|
||||
our serp competitors <domain> --location 2410
|
||||
```
|
||||
|
||||
**Interactive fallback — DataForSEO MCP:**
|
||||
**OurSEO MCP (spot-check):**
|
||||
```
|
||||
mcp__dfs-mcp__dataforseo_labs_google_ranked_keywords
|
||||
mcp__dfs-mcp__dataforseo_labs_google_domain_rank_overview
|
||||
mcp__dfs-mcp__dataforseo_labs_google_historical_rank_overview
|
||||
mcp__dfs-mcp__dataforseo_labs_google_keyword_overview
|
||||
mcp__ourseo__check_serp(keyword="<keyword>", domain="<target.com>", country="kr")
|
||||
```
|
||||
|
||||
### Common Parameters
|
||||
- **location_code**: 2410 (Korea), 2840 (US), 2392 (Japan)
|
||||
- **language_code**: ko, en, ja
|
||||
**GSC (first-party validation):**
|
||||
```bash
|
||||
our research search-console queries --site sc-domain:<domain> --days 28
|
||||
```
|
||||
|
||||
### Notion for Report Storage
|
||||
```
|
||||
mcp__notion__notion-create-pages: Save tracking reports to SEO Audit Log
|
||||
mcp__notion__notion-update-page: Update existing tracking entries
|
||||
```
|
||||
### Common parameters
|
||||
|
||||
| Concept | Semrush | Ahrefs | DataForSEO / `our` CLI |
|
||||
|---|---|---|---|
|
||||
| Korean market | `database="kr"` | `country="kr"` | `--location 2410` |
|
||||
| US market | `database="us"` | `country="us"` | `--location 2840` |
|
||||
| Japan | `database="jp"` | `country="jp"` | `--location 2392` |
|
||||
| Language | (database-bound) | (country-bound) | `--language ko`/`en`/`ja` |
|
||||
|
||||
Always record the chosen data source in the report **Overview** so future tracking runs can compare like-for-like.
|
||||
|
||||
## Workflow
|
||||
|
||||
|
||||
@@ -1,8 +1,16 @@
|
||||
name: seo-position-tracking
|
||||
description: |
|
||||
Keyword position tracking and ranking monitoring. Triggers: rank tracking, position monitoring, keyword rankings, visibility score, ranking report.
|
||||
|
||||
# Allowed tools list every backend the skill can pull rank data from.
|
||||
# Per-task selection happens in SKILL.md > Data Source Selection — NOT here.
|
||||
allowed-tools:
|
||||
- mcp__ahrefs__*
|
||||
- mcp__ahrefs__* # default — Ahrefs rank-tracker-* is the strongest in this category
|
||||
- mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace)
|
||||
- mcp__semrush__* # tracking_research, organic_research
|
||||
- mcp__ourseo__* # check_serp for spot-checks
|
||||
- mcp__dfs-mcp__* # DataForSEO MCP (historical rank, ranked_keywords)
|
||||
- Bash # `our serp *` CLI (Claude Code only)
|
||||
- mcp__notion__*
|
||||
- WebSearch
|
||||
- WebFetch
|
||||
|
||||
@@ -1,15 +1,27 @@
|
||||
# Ahrefs
|
||||
# Ahrefs MCP
|
||||
|
||||
> TODO: Document tool usage for this skill
|
||||
**Default** when an Ahrefs Rank Tracker project exists for the domain — Ahrefs' rank tracker is the strongest in this category. Namespace: `mcp__ahrefs__*` / `mcp__claude_ai_Ahrefs__*`.
|
||||
|
||||
## Available Commands
|
||||
## Key endpoints
|
||||
|
||||
- [ ] List commands
|
||||
- `rank-tracker-overview` — current position distribution, visibility
|
||||
- `rank-tracker-serp-overview` — SERP for each tracked keyword
|
||||
- `rank-tracker-competitors-overview` — competitor positions for the same keywords
|
||||
- `rank-tracker-competitors-pages` — top competitor pages
|
||||
- `rank-tracker-competitors-stats` — aggregate competitor visibility
|
||||
- `gsc-keywords` — first-party rank data when GSC is connected to the Ahrefs project
|
||||
|
||||
## Configuration
|
||||
## Example
|
||||
|
||||
- [ ] Add configuration details
|
||||
```
|
||||
mcp__ahrefs__rank-tracker-overview(project_id="<id>")
|
||||
mcp__ahrefs__rank-tracker-competitors-stats(project_id="<id>")
|
||||
```
|
||||
|
||||
## Examples
|
||||
Project must already exist in Ahrefs — list via `management-projects`.
|
||||
|
||||
- [ ] Add usage examples
|
||||
## Not for this skill when
|
||||
|
||||
- **No Ahrefs project for the domain** — Semrush `tracking_research` is the simplest alternative.
|
||||
- **First-party rank truth without an Ahrefs project** — use GSC via `our research search-console queries`.
|
||||
- **One-off spot-check for a single keyword** — `mcp__ourseo__check_serp` is cheaper.
|
||||
|
||||
40
custom-skills/21-seo-position-tracking/desktop/tools/gsc.md
Normal file
40
custom-skills/21-seo-position-tracking/desktop/tools/gsc.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Google Search Console
|
||||
|
||||
**First-party position data** — what Google actually rendered for the verified site. Estimates from Semrush/Ahrefs/DataForSEO are modelled; GSC is observed.
|
||||
|
||||
Two entry points:
|
||||
|
||||
1. **`our research search-console` CLI** — primary, cached, scriptable.
|
||||
2. **Ahrefs `gsc-*`** — only when an Ahrefs project is connected to the GSC property.
|
||||
|
||||
## CLI commands
|
||||
|
||||
```bash
|
||||
our research search-console queries --site sc-domain:<domain> --days 28
|
||||
our research search-console pages --site sc-domain:<domain> --days 28
|
||||
our research search-console combined --site sc-domain:<domain> --days 28
|
||||
```
|
||||
|
||||
`sc-domain:` prefix for Domain-verified properties. URL-prefix properties use the plain URL.
|
||||
|
||||
## Ahrefs GSC tools
|
||||
|
||||
```
|
||||
mcp__ahrefs__gsc-keywords(project_id="<id>", limit=100)
|
||||
mcp__ahrefs__gsc-keyword-history(project_id="<id>", keyword="<kw>")
|
||||
mcp__ahrefs__gsc-positions-history(project_id="<id>")
|
||||
mcp__ahrefs__gsc-performance-by-position(project_id="<id>")
|
||||
```
|
||||
|
||||
## Strengths
|
||||
|
||||
- **Ground truth** — only first-party position source.
|
||||
- Includes impressions and CTR per query — useful for visibility weighting beyond raw position.
|
||||
- Anonymous-query data via `mcp__ahrefs__gsc-anonymous-queries`.
|
||||
|
||||
## Not for this skill when
|
||||
|
||||
- **Net-new keyword discovery** — GSC only shows queries the site already ranked for. Pair with Semrush/Ahrefs for discovery.
|
||||
- **Competitor positions** — GSC is single-site.
|
||||
|
||||
Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`.
|
||||
@@ -0,0 +1,37 @@
|
||||
# OurSEO Agent (CLI + MCP)
|
||||
|
||||
Two paths:
|
||||
|
||||
1. **CLI** (Claude Code) — `our serp *` and `our keywords *` (DataForSEO under the hood).
|
||||
2. **MCP** (Claude Desktop) — `mcp__ourseo__check_serp` for single-keyword spot-check.
|
||||
|
||||
## CLI commands
|
||||
|
||||
```bash
|
||||
# Ranked keywords for a domain (modelled)
|
||||
our serp ranked-keywords <domain> --location 2410 --limit 100 --format json
|
||||
our serp domain-overview <domain> --location 2410 --format json
|
||||
our serp competitors <domain> --location 2410
|
||||
|
||||
# Volume / KD pulls to weight visibility scores
|
||||
our keywords volume "<kw1>" "<kw2>" --location 2410 --language ko
|
||||
```
|
||||
|
||||
Location codes: `2410` Korea, `2840` US, `2392` Japan.
|
||||
|
||||
## MCP tool (spot-check)
|
||||
|
||||
```
|
||||
mcp__ourseo__check_serp(keyword="<keyword>", domain="<target>", country="kr")
|
||||
```
|
||||
|
||||
## Strengths
|
||||
|
||||
- Cheapest per call for Korean batch rank pulls (`--location 2410`).
|
||||
- No project setup required — just call.
|
||||
- MCP `check_serp` is the cheapest live position verification path.
|
||||
|
||||
## Not for this skill when
|
||||
|
||||
- **Historical trend / period-over-period continuity** — needs an Ahrefs / Semrush project that polls regularly. OurSEO is point-in-time only; pair with MySQL workspace to keep history.
|
||||
- **First-party position truth** — GSC.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Semrush MCP
|
||||
|
||||
Default when no Ahrefs Rank Tracker project exists for the domain. Strong for English / major-market position scans.
|
||||
|
||||
Call pattern: discovery → `get_report_schema` → `execute_report`.
|
||||
|
||||
## Key reports
|
||||
|
||||
- `tracking_research` — position tracking projects
|
||||
- `organic_research` — ranked keywords for a domain
|
||||
- `overview_research` — visibility distribution
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
mcp__semrush__tracking_research(query="<keyword>", database="us")
|
||||
mcp__semrush__get_report_schema(report_id="<id>")
|
||||
mcp__semrush__execute_report(report_id="<id>", params={...})
|
||||
```
|
||||
|
||||
Korean market: `database="kr"`.
|
||||
|
||||
## Not for this skill when
|
||||
|
||||
- **Ahrefs project already exists for the domain** — use Ahrefs rank-tracker for historical continuity.
|
||||
- **First-party ranking truth** — GSC (`our research search-console`).
|
||||
- **Bulk Korean rank pulls** — `our serp ranked-keywords --location 2410` is cheaper.
|
||||
Reference in New Issue
Block a user