ourdigital/our-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(seo-skills): multi-backend Data Source Selection (#7)

Browse Source 
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
2026-05-14 03:15:32 +09:00
committed by GitHub
parent 1ca84f67ed
commit e527fb4b0f
71 changed files with 2647 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
custom-skills/20-seo-serp-analysis/desktop/SKILL.md
View File

@@ -19,11 +19,37 @@ Analyze search engine result page composition for Google and Naver. Detect SERP
4. **Search Intent Validation** - Infer intent (informational, navigational, commercial, transactional, local) from SERP composition
5. **Naver SERP Composition** - Detect sections (blog, cafe, knowledge iN, Smart Store, brand zone, books, shortform, influencer), map section priority, analyze brand zone presence
## MCP Tool Usage
## Data Source Selection
### SEO Data (DataForSEO)
This skill can pull SERP 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 |
|---|---|---|
| **Semrush MCP** (`mcp__semrush__*`) | Default Google SERP overview, organic competitor positions, SERP-feature presence | `overview_research` / `organic_research` → `get_report_schema` → `execute_report`. `database="us"` default; `"kr"` for Korean. |
| **Ahrefs MCP** (`mcp__ahrefs__*`) | When user wants Ahrefs SERP overview or already has an Ahrefs project | `serp-overview` exposes top organic, SERP features, paid layout per keyword. |
| **OurSEO MCP** (`mcp__ourseo__check_serp`) | Live position spot-check for a single keyword/domain pair | Cheap; good for rank-only confirmations without full SERP pull. |
| **OurSEO CLI** (`our serp *`) | DataForSEO under the hood — full SERP JSON with all features, Korean-aware via `--location 2410` | Claude Code only (Bash). Commands: `our serp live`, `our serp competitors`, `our serp ranked-keywords`, `our serp domain-overview`. |
| **OurSEO CLI — Naver** (`our research naver serp`) | Naver SERP composition (blog, cafe, knowledge iN, Smart Store, brand zone, shortform, influencer) | Naver-only; required for Korean-market analysis since Semrush/Ahrefs don't cover Naver SERP. |
| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Fallback when `our` CLI isn't running | `serp_organic_live_advanced`, `dataforseo_labs_google_serp_competitors`. |
### 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 needs a capability only one backend has** (Naver SERP → `our research naver serp`; full SERP JSON → DataForSEO / OurSEO CLI) → use that backend.
4. **Default**: Semrush MCP for Google SERP overview; **`our research naver serp`** for Naver.
5. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`.
### Backend call patterns
**Semrush MCP (default Google):**
```
mcp__semrush__overview_research(query="<keyword>", database="us")
mcp__semrush__get_report_schema(report_id="...")
mcp__semrush__execute_report(report_id="...", params={...})
```
**OurSEO CLI — DataForSEO (full Google SERP JSON):**
```bash
our serp live "<keyword>" --location 2410 --language ko
our serp competitors <domain> --location 2410
@@ -31,30 +57,33 @@ our serp ranked-keywords <domain> --location 2410 --limit 50
our serp domain-overview <domain> --location 2410
```
**Interactive fallback — DataForSEO MCP:**
```
mcp__dfs-mcp__serp_organic_live_advanced
mcp__dfs-mcp__dataforseo_labs_google_serp_competitors
mcp__dfs-mcp__dataforseo_labs_google_ranked_keywords
mcp__dfs-mcp__dataforseo_labs_google_domain_rank_overview
**OurSEO CLI — Naver SERP (Korean market):**
```bash
our research naver serp "<keyword>"
our research naver serp "<keyword>" --domain <target.com>
```
### Common Parameters
- **location_code**: 2410 (Korea), 2840 (US), 2392 (Japan)
- **language_code**: ko, en, ja
### Notion for Report Storage
**OurSEO MCP (single-keyword spot-check):**
```
mcp__notion__notion-create-pages: Save analysis report to SEO Audit Log database
mcp__notion__notion-update-page: Update existing report entries
mcp__ourseo__check_serp(keyword="<keyword>", domain="<target.com>", country="kr")
```
### Web Tools for Naver Analysis
**Ahrefs MCP:**
```
WebSearch: Discover Naver search trends
WebFetch: Fetch Naver SERP HTML for section analysis
mcp__ahrefs__serp-overview(keyword="<keyword>", country="us")
```
### 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 analyses can compare like-for-like.
## Workflow
### 1. Google SERP Analysis

14
custom-skills/20-seo-serp-analysis/desktop/skill.yaml
View File

@@ -1,14 +1,16 @@
# Skill metadata (extracted from SKILL.md frontmatter)
name: seo-serp-analysis
description: |
SERP analysis for Google and Naver. Triggers: SERP analysis, search results, featured snippet, SERP features, Naver SERP.
# Optional fields
# Allowed tools list every backend the skill can pull SERP data from.
# Per-task selection happens in SKILL.md > Data Source Selection — NOT here.
allowed-tools:
- mcp__ahrefs__*
- mcp__semrush__* # default for Google SERP overview
- mcp__ahrefs__* # Ahrefs serp-overview
- mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace)
- mcp__ourseo__* # OurSEO check_serp, audit_page
- mcp__dfs-mcp__* # DataForSEO MCP fallback
- Bash # `our serp *` + `our research naver serp` (Claude Code only)
- mcp__notion__*
- WebSearch
- WebFetch
# triggers: [] # TODO: Extract from description

25
custom-skills/20-seo-serp-analysis/desktop/tools/ahrefs.md
View File

@@ -1,15 +1,24 @@
# Ahrefs
# Ahrefs MCP
> TODO: Document tool usage for this skill
Use when the user explicitly wants Ahrefs' SERP view, or already has an Ahrefs project for the domain. Namespace: `mcp__ahrefs__*` (Desktop) / `mcp__claude_ai_Ahrefs__*` (Claude.ai) — same backend.
## Available Commands
## Key endpoints
- [ ] List commands
- `serp-overview` — top organic, SERP features, paid layout for a keyword
- `rank-tracker-serp-overview` — SERP layout for keywords in a tracked project
- `keywords-explorer-overview` — pairs with SERP for SERP-feature signals (Featured Snippet, PAA)
## Configuration
## Example
- [ ] Add configuration details
```
mcp__ahrefs__serp-overview(keyword="<keyword>", country="us")
mcp__ahrefs__serp-overview(keyword="<keyword>", country="kr")
```
## Examples
## Not for this skill when
- [ ] Add usage examples
- **Naver SERP** — Ahrefs doesn't cover Naver. Use `our research naver serp`.
- **Single-keyword position spot-check** — `mcp__ourseo__check_serp` is cheaper.
- **Full SERP JSON with all features for export** — DataForSEO via `our serp live`.
Reference: call `mcp__ahrefs__doc` once per session before first use.

39
custom-skills/20-seo-serp-analysis/desktop/tools/ourseo.md Normal file
View File

@@ -0,0 +1,39 @@
# OurSEO Agent (CLI + MCP)
Two paths for SERP work:
1. **CLI** (Claude Code, Bash) — `our serp *` (DataForSEO Google) + `our research naver serp` (Naver-only).
2. **MCP** (Claude Desktop) — `mcp__ourseo__check_serp` for single-keyword spot-check.
## CLI commands
```bash
# Google SERP via DataForSEO
our serp live "<keyword>" --location 2410 --language ko
our serp competitors <domain> --location 2410
our serp ranked-keywords <domain> --location 2410 --limit 50
our serp domain-overview <domain> --location 2410
# Naver SERP (Korean engines — Naver-only path)
our research naver serp "<keyword>"
our research naver serp "<keyword>" --domain <target.com>
```
Location codes: `2410` Korea, `2840` US, `2392` Japan.
## MCP tool
```
mcp__ourseo__check_serp(keyword="<keyword>", domain="<target>", country="kr")
```
## Strengths
- **Only** path that covers Naver SERP (blog, cafe, knowledge iN, Smart Store, brand zone, shortform, influencer).
- Cheapest per call for batch Korean-market SERP work.
- Full live SERP JSON with all features for export.
## Not for this skill when
- **Modelled SERP overview** (volume + CPC trend per keyword) — Semrush is cleanest for that.
- **Brand Radar / AI search SERP** — Ahrefs Brand Radar is the only option.

28
custom-skills/20-seo-serp-analysis/desktop/tools/semrush.md Normal file
View File

@@ -0,0 +1,28 @@
# Semrush MCP
Default backend for Google SERP overview, organic competitor positions, SERP-feature presence.
Call pattern: discovery → `get_report_schema` → `execute_report`.
## Key reports (SERP toolkit)
- Domain overview (organic positions, traffic, distribution)
- Position changes (new/lost/improved/declined)
- Organic competitors per keyword
- SERP-feature presence per keyword
## Example
```
mcp__semrush__overview_research(query="<keyword>", database="us")
mcp__semrush__get_report_schema(report_id="<id from above>")
mcp__semrush__execute_report(report_id="<id>", params={"phrase": "<keyword>", "database": "us"})
```
Korean market: `database="kr"`. Default `database="us"` per Semrush MCP instructions.
## Not for this skill when
- **Naver SERP** — Semrush is Google-only. Use `our research naver serp`.
- **Raw SERP JSON for parsing all features** (PAA list, video carousel items, image pack) — DataForSEO via `our serp live` exposes richer JSON.
- **Backlink graph for ranking pages** — Ahrefs `site-explorer-*` is stronger.