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
@@ -1,15 +1,54 @@
|
||||
# Ahrefs
|
||||
# Ahrefs MCP
|
||||
|
||||
> TODO: Document tool usage for this skill
|
||||
Use Ahrefs when the user explicitly asks for Ahrefs data, when DR/UR weighting matters, or when the task needs `gsc-keywords` (Ahrefs is the only SEO MCP that exposes a Google Search Console integration directly).
|
||||
|
||||
## Available Commands
|
||||
Namespace: `mcp__ahrefs__*` (Claude Desktop) / `mcp__claude_ai_Ahrefs__*` (Claude.ai). Same backend.
|
||||
|
||||
- [ ] List commands
|
||||
## Keyword endpoints
|
||||
|
||||
## Configuration
|
||||
- `keywords-explorer-overview` — volume, CPC, KD, parent topic
|
||||
- `keywords-explorer-matching-terms` — phrase-match expansion
|
||||
- `keywords-explorer-related-terms` — related ideas
|
||||
- `keywords-explorer-search-suggestions` — autocomplete-style suggestions
|
||||
- `keywords-explorer-volume-by-country` — country breakdown for one keyword
|
||||
- `keywords-explorer-volume-history` — historical search volume
|
||||
|
||||
- [ ] Add configuration details
|
||||
## GSC integration (Ahrefs-only)
|
||||
|
||||
- `gsc-keywords` — keywords the user's verified site actually ranks for (impressions, clicks, CTR, position)
|
||||
- `gsc-keyword-history` — historical performance of a query
|
||||
|
||||
GSC endpoints require the Ahrefs project to be connected to the GSC property. Confirm with the user that the project exists in their Ahrefs workspace before relying on these.
|
||||
|
||||
## Common parameters
|
||||
|
||||
- `country` — `us`, `kr`, `jp`, etc. (lowercase ISO-2)
|
||||
- `keyword` — the seed term
|
||||
- `limit` — usually 30–100
|
||||
|
||||
## Examples
|
||||
|
||||
- [ ] Add usage examples
|
||||
**Quick overview:**
|
||||
```
|
||||
mcp__ahrefs__keywords-explorer-overview(keyword="enterprise CRM", country="us")
|
||||
```
|
||||
|
||||
**Related terms in Korean:**
|
||||
```
|
||||
mcp__ahrefs__keywords-explorer-related-terms(keyword="신라호텔", country="kr", limit=50)
|
||||
```
|
||||
|
||||
**GSC first-party queries:**
|
||||
```
|
||||
mcp__ahrefs__gsc-keywords(project_id="<ahrefs project id>", limit=100)
|
||||
```
|
||||
|
||||
## When NOT to use Ahrefs for this skill
|
||||
|
||||
- Default keyword volume / matching terms — Semrush is the project default; only switch on explicit request.
|
||||
- Bulk Korean expansion — `our keywords ideas --location 2410` is usually cheaper.
|
||||
- Entity / Knowledge Graph seeding — `mcp__ourseo__search_knowledge_graph`.
|
||||
|
||||
## Reference
|
||||
|
||||
Always check `mcp__ahrefs__doc` once per session before first call — it documents current parameter shapes and may have changed.
|
||||
|
||||
58
custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md
Normal file
58
custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Google Search Console (GSC)
|
||||
|
||||
GSC is the only **first-party** data source on this list — what the user's verified site actually rendered impressions / clicks for in Google. Estimates from Semrush, Ahrefs, and DataForSEO are modelled; GSC is observed.
|
||||
|
||||
Two entry points to GSC for this skill:
|
||||
|
||||
1. **`our research search-console` CLI** — OurSEO Agent's GSC integration (recommended; cached).
|
||||
2. **Ahrefs `gsc-keywords`** — only if the site is connected as an Ahrefs project AND the user is already in Ahrefs context.
|
||||
|
||||
## CLI commands (`our research search-console`)
|
||||
|
||||
See `our research search-console --help` for the current command surface. Typical patterns:
|
||||
|
||||
```bash
|
||||
# Queries the site actually ranks for, last 28 days
|
||||
our research search-console queries --site sc-domain:example.com --days 28
|
||||
|
||||
# Top pages by impressions
|
||||
our research search-console pages --site sc-domain:example.com --days 28
|
||||
|
||||
# Query/page combinations
|
||||
our research search-console combined --site sc-domain:example.com --days 28
|
||||
```
|
||||
|
||||
The `sc-domain:` prefix is required for Domain-verified properties. URL-prefix properties use the plain URL (`https://example.com/`). See gotcha note: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`.
|
||||
|
||||
## Ahrefs GSC tools
|
||||
|
||||
When the user is already working in Ahrefs:
|
||||
|
||||
```
|
||||
mcp__ahrefs__gsc-keywords(project_id="<ahrefs project id>", limit=100)
|
||||
mcp__ahrefs__gsc-keyword-history(project_id="...", keyword="...")
|
||||
mcp__ahrefs__gsc-pages(project_id="...")
|
||||
mcp__ahrefs__gsc-performance-history(project_id="...")
|
||||
mcp__ahrefs__gsc-ctr-by-position(project_id="...")
|
||||
```
|
||||
|
||||
Requires the Ahrefs project to be connected to the GSC property. Confirm with the user before assuming the link exists.
|
||||
|
||||
## When to bring GSC into keyword work
|
||||
|
||||
- **Validation step**: after generating a keyword list from Semrush / Ahrefs / DataForSEO, intersect with GSC queries to see which are already driving impressions.
|
||||
- **Pruning**: drop keywords from the list that have zero GSC impressions over the last 90 days for a mature site (signals the site doesn't compete on them despite the model's volume estimate).
|
||||
- **Cannibalization detection**: GSC `query × page` lets you find queries where multiple URLs share impressions.
|
||||
- **Anonymous-query analysis**: `mcp__ahrefs__gsc-anonymous-queries` surfaces queries Google hides from the standard report — sometimes reveals brand variants.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Purpose |
|
||||
|---|---|
|
||||
| `SEO_AGENT_GSC_SERVICE_ACCOUNT` | Path to the GSC service-account JSON for the OurSEO CLI |
|
||||
| `GSC_CACHE_TTL` | GSC cache TTL in seconds (default 3600) |
|
||||
|
||||
## When NOT to use GSC for this skill
|
||||
|
||||
- Discovery of keywords the site does **not** yet rank for — GSC by definition only shows queries that already triggered impressions. Use Semrush / Ahrefs / DataForSEO for net-new discovery.
|
||||
- Competitive keyword pulls — GSC is single-site.
|
||||
@@ -0,0 +1,74 @@
|
||||
# OurSEO Agent (CLI + MCP)
|
||||
|
||||
The OurSEO Agent (`~/Project/our-seo-agent`) covers two distinct paths for this skill:
|
||||
|
||||
1. **CLI** — `our keywords *` (Claude Code, via Bash). DataForSEO under the hood. Cheapest per call, batch-friendly, Korean-aware.
|
||||
2. **MCP** — `mcp__ourseo__*` (Claude Desktop). Lighter surface: crawl, audit, Knowledge Graph entity expansion.
|
||||
|
||||
Pick the path that matches your current Claude environment.
|
||||
|
||||
## CLI commands (Claude Code, primary for Korean market)
|
||||
|
||||
```bash
|
||||
# Volume + difficulty + intent
|
||||
our keywords volume "<keyword>" --location 2410 --language ko
|
||||
our keywords difficulty "<kw1>" "<kw2>" --location 2410
|
||||
our keywords intent "<kw1>" "<kw2>" "<kw3>"
|
||||
|
||||
# Expansion
|
||||
our keywords ideas "<seed>" --location 2410 --limit 50
|
||||
our keywords for-site <competitor.com> --location 2410 --limit 100
|
||||
|
||||
# Naver (Korean engines)
|
||||
our research naver keywords volume "<keyword>"
|
||||
our research naver keywords ideas "<keyword>" --limit 30
|
||||
|
||||
# Cross-engine compare (where supported)
|
||||
our research keywords compare "<keyword>" --engines naver
|
||||
```
|
||||
|
||||
| Location code | Market |
|
||||
|---|---|
|
||||
| `2410` | Korea |
|
||||
| `2840` | United States |
|
||||
| `2392` | Japan |
|
||||
|
||||
| Language code | Language |
|
||||
|---|---|
|
||||
| `ko` | Korean |
|
||||
| `en` | English |
|
||||
| `ja` | Japanese |
|
||||
|
||||
Cache (avoid duplicate calls): `our research cache list --engine <name>` / `our research cache clear --older-than 30d`.
|
||||
|
||||
## MCP tools (Claude Desktop)
|
||||
|
||||
| Tool | Purpose for keyword work |
|
||||
|---|---|
|
||||
| `mcp__ourseo__search_knowledge_graph` | Resolve a brand / entity to Knowledge Graph IDs — useful as a *seeding* step for keyword expansion around the entity. |
|
||||
| `mcp__ourseo__crawl_website` | Crawl the target site and pull on-page keyword inventory (title/h1/meta) — ground truth for what the site already targets. |
|
||||
| `mcp__ourseo__audit_page` | Single-page SEO audit; not a keyword tool per se, but useful for validating that high-value keywords are actually present on the page. |
|
||||
| `mcp__ourseo__check_serp` | Check SERP position for a keyword/domain pair — bridge to position tracking. |
|
||||
| `mcp__ourseo__find_similar_pages` | Semantic similarity over a prior crawl — supports topic clustering. |
|
||||
|
||||
The OurSEO MCP does **not** expose DataForSEO keyword volume directly. For volume + KD + ideas in Claude Desktop, use Semrush MCP (`mcp__semrush__*`) or DataForSEO MCP (`mcp__dfs-mcp__*`).
|
||||
|
||||
## Configuration
|
||||
|
||||
The CLI reads from `~/Project/our-seo-agent/config/config.yaml` and these env vars:
|
||||
|
||||
| Variable | Purpose |
|
||||
|---|---|
|
||||
| `DATAFORSEO_USERNAME` / `DATAFORSEO_PASSWORD` | DataForSEO auth |
|
||||
| `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` | Naver Open API + Search Ad |
|
||||
| `GOOGLE_KG_API_KEY` | Knowledge Graph Search API |
|
||||
|
||||
See the project `CLAUDE.md` for full env-var reference. Credentials live in 1Password — fetch with `op://Development/<item>/credential`.
|
||||
|
||||
## When to choose OurSEO over Semrush / Ahrefs
|
||||
|
||||
- Korean-market batch work (Naver + Google together).
|
||||
- Crawl-derived keyword inventory (what the site itself targets, not estimates).
|
||||
- Knowledge Graph entity seeding.
|
||||
- Cost-sensitive bulk volume lookups.
|
||||
- Cross-engine comparison (Naver + DataForSEO via `our research keywords compare`).
|
||||
@@ -0,0 +1,57 @@
|
||||
# Semrush MCP
|
||||
|
||||
Default keyword-research backend per SKILL.md > Data Source Selection.
|
||||
|
||||
## Call pattern
|
||||
|
||||
The Semrush MCP follows a three-step discovery → schema → execute pattern (see Semrush MCP server instructions):
|
||||
|
||||
1. **Discovery** — pick the right toolkit for the task:
|
||||
- `mcp__semrush__keyword_research` — keyword overview, related, volume, intent, KD
|
||||
- `mcp__semrush__organic_research` — domain/URL organic keywords + competitors
|
||||
- `mcp__semrush__overview_research` — domain/URL overview (traffic, ranking dist.)
|
||||
- `mcp__semrush__url_research` — single-URL deep dive
|
||||
2. **`mcp__semrush__get_report_schema(report_id=...)`** — fetch the param spec for the chosen report.
|
||||
3. **`mcp__semrush__execute_report(report_id=..., params={...})`** — run it.
|
||||
|
||||
Default `database="us"` when the user does not specify a market. Use `display_limit=30-50` for exploratory queries.
|
||||
|
||||
## Available reports (keyword-research toolkit)
|
||||
|
||||
- Keyword overview (volume, CPC, competition, KD, trend)
|
||||
- Related keywords
|
||||
- Matching phrases (broad / phrase / exact match)
|
||||
- Keyword difficulty (single + bulk)
|
||||
- Search intent
|
||||
- Keyword historical volume
|
||||
|
||||
## Configuration
|
||||
|
||||
| Parameter | Value |
|
||||
|---|---|
|
||||
| Default database | `us` |
|
||||
| Korean market database | `kr` |
|
||||
| Japan market database | `jp` |
|
||||
| Auth | Semrush API key on the MCP server side (no local config) |
|
||||
|
||||
## Examples
|
||||
|
||||
**English keyword volume:**
|
||||
```
|
||||
mcp__semrush__keyword_research(query="enterprise CRM software", database="us")
|
||||
→ pick report_id from response
|
||||
mcp__semrush__get_report_schema(report_id="phrase_this")
|
||||
mcp__semrush__execute_report(report_id="phrase_this", params={"phrase": "enterprise CRM software", "database": "us"})
|
||||
```
|
||||
|
||||
**Korean expansion:**
|
||||
```
|
||||
mcp__semrush__keyword_research(query="신라호텔", database="kr")
|
||||
mcp__semrush__execute_report(report_id="phrase_related", params={"phrase": "신라호텔", "database": "kr", "display_limit": 50})
|
||||
```
|
||||
|
||||
## When NOT to use Semrush
|
||||
|
||||
- Task needs **GSC first-party query data** — use Ahrefs `gsc-keywords` or `our research search-console` instead.
|
||||
- Task needs **Knowledge Graph entity expansion** — use `mcp__ourseo__search_knowledge_graph`.
|
||||
- Task needs **bulk cheap calls at Korean scale** — `our keywords *` CLI (DataForSEO) is usually cheaper.
|
||||
Reference in New Issue
Block a user