From e527fb4b0ff711425cd2473ce6c4d8e8ac0a7668 Mon Sep 17 00:00:00 2001 From: Andrew Yim <6537554+ourdigital@users.noreply.github.com> Date: Thu, 14 May 2026 03:15:32 +0900 Subject: [PATCH] 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) --- .../19-seo-keyword-strategy/desktop/SKILL.md | 108 ++++++++++++------ .../desktop/skill.yaml | 11 +- .../desktop/tools/ahrefs.md | 53 +++++++-- .../desktop/tools/gsc.md | 58 ++++++++++ .../desktop/tools/ourseo.md | 74 ++++++++++++ .../desktop/tools/semrush.md | 57 +++++++++ .../20-seo-serp-analysis/desktop/SKILL.md | 67 ++++++++--- .../20-seo-serp-analysis/desktop/skill.yaml | 14 ++- .../desktop/tools/ahrefs.md | 25 ++-- .../desktop/tools/ourseo.md | 39 +++++++ .../desktop/tools/semrush.md | 28 +++++ .../21-seo-position-tracking/desktop/SKILL.md | 74 +++++++++--- .../desktop/skill.yaml | 10 +- .../desktop/tools/ahrefs.md | 28 +++-- .../desktop/tools/gsc.md | 40 +++++++ .../desktop/tools/ourseo.md | 37 ++++++ .../desktop/tools/semrush.md | 27 +++++ .../22-seo-link-building/desktop/SKILL.md | 52 +++++++-- .../22-seo-link-building/desktop/skill.yaml | 8 +- .../desktop/tools/ourseo.md | 35 ++++++ .../desktop/tools/semrush.md | 30 +++++ .../23-seo-content-strategy/desktop/SKILL.md | 67 +++++++++-- .../desktop/skill.yaml | 10 +- .../desktop/tools/ahrefs.md | 33 ++++-- .../desktop/tools/gsc.md | 42 +++++++ .../desktop/tools/ourseo.md | 39 +++++++ .../desktop/tools/semrush.md | 34 ++++++ .../24-seo-ecommerce/desktop/SKILL.md | 70 ++++++++++-- .../24-seo-ecommerce/desktop/skill.yaml | 10 +- .../24-seo-ecommerce/desktop/tools/ahrefs.md | 31 +++-- .../24-seo-ecommerce/desktop/tools/ourseo.md | 44 +++++++ .../24-seo-ecommerce/desktop/tools/semrush.md | 34 ++++++ .../25-seo-kpi-framework/desktop/SKILL.md | 73 +++++++++++- .../25-seo-kpi-framework/desktop/skill.yaml | 10 +- .../desktop/tools/ahrefs.md | 38 ++++-- .../25-seo-kpi-framework/desktop/tools/gsc.md | 56 +++++++++ .../desktop/tools/ourseo.md | 38 ++++++ .../desktop/tools/semrush.md | 40 +++++++ .../26-seo-international/desktop/SKILL.md | 62 ++++++++-- .../26-seo-international/desktop/skill.yaml | 10 +- .../desktop/tools/ourseo.md | 42 +++++++ .../desktop/tools/semrush.md | 36 ++++++ .../27-seo-ai-visibility/desktop/SKILL.md | 61 +++++++++- .../27-seo-ai-visibility/desktop/skill.yaml | 10 +- .../desktop/tools/ourseo.md | 38 ++++++ .../desktop/tools/semrush.md | 21 ++++ .../28-seo-knowledge-graph/desktop/SKILL.md | 60 ++++++++-- .../28-seo-knowledge-graph/desktop/skill.yaml | 11 +- .../desktop/tools/ourseo.md | 53 +++++++++ .../desktop/tools/semrush.md | 29 +++++ .../31-seo-competitor-intel/desktop/SKILL.md | 64 +++++++++-- .../desktop/skill.yaml | 12 +- .../desktop/tools/ourseo.md | 40 +++++++ .../desktop/tools/semrush.md | 35 ++++++ .../32-seo-crawl-budget/desktop/SKILL.md | 74 +++++++++++- .../32-seo-crawl-budget/desktop/skill.yaml | 10 +- .../desktop/tools/ahrefs.md | 36 ++++-- .../32-seo-crawl-budget/desktop/tools/gsc.md | 45 ++++++++ .../desktop/tools/ourseo.md | 53 +++++++++ .../desktop/tools/semrush.md | 30 +++++ .../33-seo-migration-planner/desktop/SKILL.md | 78 +++++++++++-- .../desktop/skill.yaml | 14 ++- .../desktop/tools/gsc.md | 54 +++++++++ .../desktop/tools/ourseo.md | 54 +++++++++ .../desktop/tools/semrush.md | 39 +++++++ .../desktop/SKILL.md | 79 +++++++++++-- .../desktop/skill.yaml | 14 ++- .../desktop/tools/ahrefs.md | 57 ++++++--- .../desktop/tools/gsc.md | 49 ++++++++ .../desktop/tools/ourseo.md | 48 ++++++++ .../desktop/tools/semrush.md | 43 +++++++ 71 files changed, 2647 insertions(+), 258 deletions(-) create mode 100644 custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md create mode 100644 custom-skills/19-seo-keyword-strategy/desktop/tools/ourseo.md create mode 100644 custom-skills/19-seo-keyword-strategy/desktop/tools/semrush.md create mode 100644 custom-skills/20-seo-serp-analysis/desktop/tools/ourseo.md create mode 100644 custom-skills/20-seo-serp-analysis/desktop/tools/semrush.md create mode 100644 custom-skills/21-seo-position-tracking/desktop/tools/gsc.md create mode 100644 custom-skills/21-seo-position-tracking/desktop/tools/ourseo.md create mode 100644 custom-skills/21-seo-position-tracking/desktop/tools/semrush.md create mode 100644 custom-skills/22-seo-link-building/desktop/tools/ourseo.md create mode 100644 custom-skills/22-seo-link-building/desktop/tools/semrush.md create mode 100644 custom-skills/23-seo-content-strategy/desktop/tools/gsc.md create mode 100644 custom-skills/23-seo-content-strategy/desktop/tools/ourseo.md create mode 100644 custom-skills/23-seo-content-strategy/desktop/tools/semrush.md create mode 100644 custom-skills/24-seo-ecommerce/desktop/tools/ourseo.md create mode 100644 custom-skills/24-seo-ecommerce/desktop/tools/semrush.md create mode 100644 custom-skills/25-seo-kpi-framework/desktop/tools/gsc.md create mode 100644 custom-skills/25-seo-kpi-framework/desktop/tools/ourseo.md create mode 100644 custom-skills/25-seo-kpi-framework/desktop/tools/semrush.md create mode 100644 custom-skills/26-seo-international/desktop/tools/ourseo.md create mode 100644 custom-skills/26-seo-international/desktop/tools/semrush.md create mode 100644 custom-skills/27-seo-ai-visibility/desktop/tools/ourseo.md create mode 100644 custom-skills/27-seo-ai-visibility/desktop/tools/semrush.md create mode 100644 custom-skills/28-seo-knowledge-graph/desktop/tools/ourseo.md create mode 100644 custom-skills/28-seo-knowledge-graph/desktop/tools/semrush.md create mode 100644 custom-skills/31-seo-competitor-intel/desktop/tools/ourseo.md create mode 100644 custom-skills/31-seo-competitor-intel/desktop/tools/semrush.md create mode 100644 custom-skills/32-seo-crawl-budget/desktop/tools/gsc.md create mode 100644 custom-skills/32-seo-crawl-budget/desktop/tools/ourseo.md create mode 100644 custom-skills/32-seo-crawl-budget/desktop/tools/semrush.md create mode 100644 custom-skills/33-seo-migration-planner/desktop/tools/gsc.md create mode 100644 custom-skills/33-seo-migration-planner/desktop/tools/ourseo.md create mode 100644 custom-skills/33-seo-migration-planner/desktop/tools/semrush.md create mode 100644 custom-skills/34-seo-reporting-dashboard/desktop/tools/gsc.md create mode 100644 custom-skills/34-seo-reporting-dashboard/desktop/tools/ourseo.md create mode 100644 custom-skills/34-seo-reporting-dashboard/desktop/tools/semrush.md diff --git a/custom-skills/19-seo-keyword-strategy/desktop/SKILL.md b/custom-skills/19-seo-keyword-strategy/desktop/SKILL.md index 6c2f03b..c665ca3 100644 --- a/custom-skills/19-seo-keyword-strategy/desktop/SKILL.md +++ b/custom-skills/19-seo-keyword-strategy/desktop/SKILL.md @@ -21,11 +21,41 @@ Expand seed keywords, classify search intent, cluster topics, and identify compe 4. **Topic Clustering** - Group keywords into semantic clusters 5. **Gap Analysis** - Find competitor keywords missing from target site -## MCP Tool Usage +## Data Source Selection -### SEO Data (DataForSEO) +This skill can pull keyword data from multiple backends. **Pick one per task** — don't fan out to every backend by default (cost + rate limits). -**Primary — our-seo-agent CLI:** +| Backend | Best for | Notes | +|---|---|---| +| **Semrush MCP** (`mcp__semrush__*`) | Default for keyword volume, related/matching terms, organic competitor pulls | Call pattern: `keyword_research` → `get_report_schema` → `execute_report`. `database="us"` default; `"kr"` for Korean market. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Ahrefs DR/UR weighting; first-party `gsc-keywords` (only Ahrefs integrates GSC inside its MCP) | `keywords-explorer-overview`, `-matching-terms`, `-related-terms`, `-search-suggestions`, `-volume-by-country`, `gsc-keywords`. | +| **OurSEO Agent CLI** (`our keywords *`) | DataForSEO under the hood — cheapest per call, batch-friendly, Korean-aware via `--location 2410` | Claude Code only (needs Bash). Wrap calls: `our keywords volume`, `ideas`, `for-site`, `intent`, `difficulty`. | +| **OurSEO Agent MCP** (`mcp__ourseo__*`) | Claude Desktop equivalent for crawl-derived keywords + Knowledge Graph entity expansion | `search_knowledge_graph` for entity seeding; `crawl_website` to extract on-page keyword inventory from the target site itself. | +| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Direct fallback when `our` CLI isn't available | Same data as `our keywords *`. | +| **GSC** (via `our research search-console` or Ahrefs `gsc-*`) | First-party queries the site actually ranks for — ground truth, not estimates | Use to validate/prune Semrush or Ahrefs lists with real impressions/CTR. | + +### How to pick + +Apply these in order; stop at the first match: + +1. **User named a backend explicitly** in the prompt → use it. +2. **User preference memory** — read `feedback_seo_tool_preferences.md`; honor the task-type default there. +3. **Task needs a capability only one backend has** (e.g., `gsc-keywords` first-party data, or `mcp__ourseo__search_knowledge_graph` entity expansion) → use that backend. +4. **Default by market**: + - English-market or unspecified → **Semrush MCP** with `database="us"`. + - Korean market → **OurSEO CLI** `our keywords --location 2410 --language ko` (Claude Code), or **Semrush MCP** with `database="kr"` (Claude Desktop). +5. **Still ambiguous on a non-trivial task** → ask once via `AskUserQuestion` listing the top 2–3 candidates. + +### Backend call patterns + +**Semrush MCP (default):** +``` +mcp__semrush__keyword_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="...") +mcp__semrush__execute_report(report_id="...", params={...}) +``` + +**OurSEO CLI (Korean default, Claude Code):** ```bash our keywords volume "" --location 2410 --language ko our keywords ideas "" --location 2410 --limit 50 @@ -34,48 +64,50 @@ our keywords intent "" "" "" our keywords difficulty "" "" ``` -**Interactive fallback — DataForSEO MCP:** +**Ahrefs MCP (when user requests, or for GSC first-party):** ``` -mcp__dfs-mcp__dataforseo_labs_google_keyword_overview -mcp__dfs-mcp__dataforseo_labs_google_keyword_ideas -mcp__dfs-mcp__dataforseo_labs_google_keyword_suggestions -mcp__dfs-mcp__dataforseo_labs_search_intent -mcp__dfs-mcp__dataforseo_labs_bulk_keyword_difficulty -mcp__dfs-mcp__kw_data_google_ads_search_volume -mcp__dfs-mcp__dataforseo_labs_google_keywords_for_site +mcp__ahrefs__keywords-explorer-overview(keyword="", country="us") +mcp__ahrefs__keywords-explorer-matching-terms(keyword="", country="us") +mcp__ahrefs__keywords-explorer-volume-by-country(keyword="") +mcp__ahrefs__gsc-keywords(...) ``` -### Common Parameters -- **location_code**: 2410 (Korea), 2840 (US), 2392 (Japan) -- **language_code**: ko, en, ja +**OurSEO Agent MCP (Claude Desktop, KG/entity expansion):** +``` +mcp__ourseo__search_knowledge_graph(query="") +mcp__ourseo__crawl_website(url="", max_pages=50) +``` -### Web Search for Naver Discovery -``` -WebSearch: Naver autocomplete and trend discovery -``` +### Common parameters across backends + +| 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` | ## Workflow ### 1. Seed Keyword Expansion -1. Input seed keyword (Korean or English) -2. Fetch search volume via `our keywords volume "" --location 2410 --language ko` -3. Expand with `our keywords ideas "" --location 2410 --limit 50` -4. Get autocomplete suggestions via MCP: `mcp__dfs-mcp__dataforseo_labs_google_keyword_suggestions` -5. Apply Korean suffix expansion if Korean market -6. Deduplicate and merge results +1. Determine backend via **Data Source Selection** above. +2. Fetch search volume for the seed. +3. Expand via the chosen backend's "related" / "ideas" / "matching-terms" endpoint. +4. Apply Korean suffix expansion if Korean market (regardless of backend). +5. Deduplicate and merge. ### 2. Intent Classification & Clustering -1. Classify each keyword by search intent -2. Group keywords into topic clusters -3. Identify pillar topics and supporting terms -4. Calculate cluster-level metrics (total volume, avg KD) +1. Classify each keyword by search intent (informational / navigational / commercial / transactional). +2. Group keywords into topic clusters. +3. Identify pillar topics and supporting terms. +4. Calculate cluster-level metrics (total volume, avg KD). ### 3. Gap Analysis -1. Pull organic keywords for target: `our keywords for-site --location 2410 --limit 100` -2. Pull organic keywords for competitors: `our keywords for-site --location 2410 --limit 100` -3. Identify keywords present in competitors but missing from target -4. Score opportunities by volume/difficulty ratio -5. Prioritize by intent alignment with business goals +1. Pull organic keywords for target via chosen backend. +2. Pull organic keywords for competitors (parallel). +3. Identify keywords present in competitors but missing from target. +4. Score opportunities by volume/difficulty ratio. +5. Prioritize by intent alignment with business goals. ## Output Format @@ -83,26 +115,30 @@ WebSearch: Naver autocomplete and trend discovery ## Keyword Strategy Report: [seed keyword] ### Overview +- Data source: [Semrush | Ahrefs | OurSEO CLI | OurSEO MCP | GSC] +- Market: [database/location code] - Total keywords discovered: [count] - Topic clusters: [count] - Total search volume: [sum] ### Top Clusters | Cluster | Keywords | Total Volume | Avg KD | -|---------|----------|-------------|--------| +|---|---|---|---| | ... | ... | ... | ... | ### Top Opportunities | Keyword | Volume | KD | Intent | Cluster | -|---------|--------|-----|--------|---------| +|---|---|---|---|---| | ... | ... | ... | ... | ... | ### Keyword Gaps (vs competitors) | Keyword | Volume | Competitor Position | Opportunity Score | -|---------|--------|-------------------|-------------------| +|---|---|---|---| | ... | ... | ... | ... | ``` +Always record the chosen data source in the **Overview** so future audits can compare apples to apples. + ## Notion Output (Required) All audit reports MUST be saved to OurDigital SEO Audit Log: diff --git a/custom-skills/19-seo-keyword-strategy/desktop/skill.yaml b/custom-skills/19-seo-keyword-strategy/desktop/skill.yaml index 0bf39f0..4010e6a 100644 --- a/custom-skills/19-seo-keyword-strategy/desktop/skill.yaml +++ b/custom-skills/19-seo-keyword-strategy/desktop/skill.yaml @@ -2,8 +2,17 @@ name: seo-keyword-strategy description: | Keyword strategy and research for SEO campaigns. Triggers: keyword research, keyword analysis, keyword gap, search volume, keyword clustering, intent classification. +# Allowed tools list every backend the skill can pull keyword data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + # SEO data backends + - mcp__semrush__* # default for keyword/SERP/organic + - mcp__ahrefs__* # Ahrefs (Claude Desktop namespace) + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) — same backend + - mcp__ourseo__* # OurSEO Agent MCP (KG, crawl-derived keywords) + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our keywords *` CLI (Claude Code only) + # Output / supplementary - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/19-seo-keyword-strategy/desktop/tools/ahrefs.md b/custom-skills/19-seo-keyword-strategy/desktop/tools/ahrefs.md index 5d918e0..8654bdb 100644 --- a/custom-skills/19-seo-keyword-strategy/desktop/tools/ahrefs.md +++ b/custom-skills/19-seo-keyword-strategy/desktop/tools/ahrefs.md @@ -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="", 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. diff --git a/custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md b/custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md new file mode 100644 index 0000000..9bcb49c --- /dev/null +++ b/custom-skills/19-seo-keyword-strategy/desktop/tools/gsc.md @@ -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="", 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. diff --git a/custom-skills/19-seo-keyword-strategy/desktop/tools/ourseo.md b/custom-skills/19-seo-keyword-strategy/desktop/tools/ourseo.md new file mode 100644 index 0000000..f8a99d1 --- /dev/null +++ b/custom-skills/19-seo-keyword-strategy/desktop/tools/ourseo.md @@ -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 "" --location 2410 --language ko +our keywords difficulty "" "" --location 2410 +our keywords intent "" "" "" + +# Expansion +our keywords ideas "" --location 2410 --limit 50 +our keywords for-site --location 2410 --limit 100 + +# Naver (Korean engines) +our research naver keywords volume "" +our research naver keywords ideas "" --limit 30 + +# Cross-engine compare (where supported) +our research keywords compare "" --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 ` / `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//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`). diff --git a/custom-skills/19-seo-keyword-strategy/desktop/tools/semrush.md b/custom-skills/19-seo-keyword-strategy/desktop/tools/semrush.md new file mode 100644 index 0000000..21bdcff --- /dev/null +++ b/custom-skills/19-seo-keyword-strategy/desktop/tools/semrush.md @@ -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. diff --git a/custom-skills/20-seo-serp-analysis/desktop/SKILL.md b/custom-skills/20-seo-serp-analysis/desktop/SKILL.md index e18e885..78f2c62 100644 --- a/custom-skills/20-seo-serp-analysis/desktop/SKILL.md +++ b/custom-skills/20-seo-serp-analysis/desktop/SKILL.md @@ -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="", 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 "" --location 2410 --language ko our serp competitors --location 2410 @@ -31,30 +57,33 @@ our serp ranked-keywords --location 2410 --limit 50 our serp domain-overview --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 "" +our research naver serp "" --domain ``` -### 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="", domain="", 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="", 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 diff --git a/custom-skills/20-seo-serp-analysis/desktop/skill.yaml b/custom-skills/20-seo-serp-analysis/desktop/skill.yaml index db1f6b7..99500b4 100644 --- a/custom-skills/20-seo-serp-analysis/desktop/skill.yaml +++ b/custom-skills/20-seo-serp-analysis/desktop/skill.yaml @@ -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 diff --git a/custom-skills/20-seo-serp-analysis/desktop/tools/ahrefs.md b/custom-skills/20-seo-serp-analysis/desktop/tools/ahrefs.md index 5d918e0..d067f30 100644 --- a/custom-skills/20-seo-serp-analysis/desktop/tools/ahrefs.md +++ b/custom-skills/20-seo-serp-analysis/desktop/tools/ahrefs.md @@ -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="", country="us") +mcp__ahrefs__serp-overview(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. diff --git a/custom-skills/20-seo-serp-analysis/desktop/tools/ourseo.md b/custom-skills/20-seo-serp-analysis/desktop/tools/ourseo.md new file mode 100644 index 0000000..1b29ec5 --- /dev/null +++ b/custom-skills/20-seo-serp-analysis/desktop/tools/ourseo.md @@ -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 "" --location 2410 --language ko +our serp competitors --location 2410 +our serp ranked-keywords --location 2410 --limit 50 +our serp domain-overview --location 2410 + +# Naver SERP (Korean engines — Naver-only path) +our research naver serp "" +our research naver serp "" --domain +``` + +Location codes: `2410` Korea, `2840` US, `2392` Japan. + +## MCP tool + +``` +mcp__ourseo__check_serp(keyword="", domain="", 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. diff --git a/custom-skills/20-seo-serp-analysis/desktop/tools/semrush.md b/custom-skills/20-seo-serp-analysis/desktop/tools/semrush.md new file mode 100644 index 0000000..e305cac --- /dev/null +++ b/custom-skills/20-seo-serp-analysis/desktop/tools/semrush.md @@ -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="", database="us") +mcp__semrush__get_report_schema(report_id="") +mcp__semrush__execute_report(report_id="", params={"phrase": "", "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. diff --git a/custom-skills/21-seo-position-tracking/desktop/SKILL.md b/custom-skills/21-seo-position-tracking/desktop/SKILL.md index fb57a43..f3e0ee9 100644 --- a/custom-skills/21-seo-position-tracking/desktop/SKILL.md +++ b/custom-skills/21-seo-position-tracking/desktop/SKILL.md @@ -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="") +mcp__ahrefs__rank-tracker-serp-overview(project_id="") +mcp__ahrefs__rank-tracker-competitors-overview(project_id="") +mcp__ahrefs__rank-tracker-competitors-stats(project_id="") +``` + +**Semrush MCP (no Ahrefs project):** +``` +mcp__semrush__tracking_research(query="", 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 --location 2410 --limit 100 +our serp ranked-keywords --location 2410 --limit 100 --format json +our serp domain-overview --location 2410 --format json our keywords volume "" "" --location 2410 --language ko -our serp domain-overview --location 2410 our serp competitors --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="", domain="", 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: --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 diff --git a/custom-skills/21-seo-position-tracking/desktop/skill.yaml b/custom-skills/21-seo-position-tracking/desktop/skill.yaml index 37cd9a2..a8aa699 100644 --- a/custom-skills/21-seo-position-tracking/desktop/skill.yaml +++ b/custom-skills/21-seo-position-tracking/desktop/skill.yaml @@ -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 diff --git a/custom-skills/21-seo-position-tracking/desktop/tools/ahrefs.md b/custom-skills/21-seo-position-tracking/desktop/tools/ahrefs.md index 5d918e0..e93c5ba 100644 --- a/custom-skills/21-seo-position-tracking/desktop/tools/ahrefs.md +++ b/custom-skills/21-seo-position-tracking/desktop/tools/ahrefs.md @@ -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="") +mcp__ahrefs__rank-tracker-competitors-stats(project_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. diff --git a/custom-skills/21-seo-position-tracking/desktop/tools/gsc.md b/custom-skills/21-seo-position-tracking/desktop/tools/gsc.md new file mode 100644 index 0000000..2aa222a --- /dev/null +++ b/custom-skills/21-seo-position-tracking/desktop/tools/gsc.md @@ -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: --days 28 +our research search-console pages --site sc-domain: --days 28 +our research search-console combined --site sc-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="", limit=100) +mcp__ahrefs__gsc-keyword-history(project_id="", keyword="") +mcp__ahrefs__gsc-positions-history(project_id="") +mcp__ahrefs__gsc-performance-by-position(project_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`. diff --git a/custom-skills/21-seo-position-tracking/desktop/tools/ourseo.md b/custom-skills/21-seo-position-tracking/desktop/tools/ourseo.md new file mode 100644 index 0000000..30bc545 --- /dev/null +++ b/custom-skills/21-seo-position-tracking/desktop/tools/ourseo.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 --location 2410 --limit 100 --format json +our serp domain-overview --location 2410 --format json +our serp competitors --location 2410 + +# Volume / KD pulls to weight visibility scores +our keywords volume "" "" --location 2410 --language ko +``` + +Location codes: `2410` Korea, `2840` US, `2392` Japan. + +## MCP tool (spot-check) + +``` +mcp__ourseo__check_serp(keyword="", domain="", 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. diff --git a/custom-skills/21-seo-position-tracking/desktop/tools/semrush.md b/custom-skills/21-seo-position-tracking/desktop/tools/semrush.md new file mode 100644 index 0000000..ff6d0ba --- /dev/null +++ b/custom-skills/21-seo-position-tracking/desktop/tools/semrush.md @@ -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="", database="us") +mcp__semrush__get_report_schema(report_id="") +mcp__semrush__execute_report(report_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. diff --git a/custom-skills/22-seo-link-building/desktop/SKILL.md b/custom-skills/22-seo-link-building/desktop/SKILL.md index def4cbe..da6cbd7 100644 --- a/custom-skills/22-seo-link-building/desktop/SKILL.md +++ b/custom-skills/22-seo-link-building/desktop/SKILL.md @@ -20,20 +20,58 @@ Analyze backlink profiles, detect toxic links, find competitor link gaps, track 5. **Broken Backlink Recovery** - Find and reclaim broken high-DR backlinks 6. **Korean Platform Mapping** - Naver Blog, Cafe, Tistory, Brunch, Korean news -## MCP Tool Usage +## Data Source Selection -### SEO Data +This skill can pull backlink data from multiple backends. **Pick one per task** — don't fan out by default (cost + rate limits). Backlink graphs are the most cost-sensitive of all SEO data. + +| Backend | Best for | Notes | +|---|---|---| +| **Ahrefs MCP** (`mcp__ahrefs__*`) | **Default** — Ahrefs' backlink graph remains the strongest in the industry. All `site-explorer-*` endpoints. | Primary capability: `site-explorer-domain-rating`, `-backlinks-stats`, `-referring-domains`, `-anchors`, `-broken-backlinks`, `-refdomains-history`. | +| **Semrush MCP** (`mcp__semrush__*`) | Alternative when user is already in Semrush context or wants a second opinion | `backlink_research` covers similar ground; Authority Score replaces DR. Coverage is competitive but not identical to Ahrefs. | +| **OurSEO** | **Not a backlink source.** No backlink graph in the OurSEO stack. | If asked, use OurSEO MCP / CLI only as a supplement for on-page link inventory (`crawl_website` extracts internal/outbound links from the target site itself). | +| **WebSearch / WebFetch** | Manual spot-check of a specific referring URL | Useful for verifying anchor / context of a high-value referring page. | + +### 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 comparison across vendors** (e.g., "verify Ahrefs claims with Semrush") → run both, document the source per metric. +4. **Default**: **Ahrefs MCP** — backlink work is the one SEO task where Ahrefs is the default, not Semrush. +5. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**Ahrefs MCP (default):** ``` -our-seo-agent CLI: Primary backlink data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary backlink data +mcp__ahrefs__site-explorer-domain-rating(target="") +mcp__ahrefs__site-explorer-backlinks-stats(target="") +mcp__ahrefs__site-explorer-referring-domains(target="", limit=100) +mcp__ahrefs__site-explorer-anchors(target="") +mcp__ahrefs__site-explorer-broken-backlinks(target="", limit=100) +mcp__ahrefs__site-explorer-refdomains-history(target="", history="weekly") +mcp__ahrefs__site-explorer-all-backlinks(target="", limit=500) +mcp__ahrefs__site-explorer-linked-anchors-external(target="") ``` -### Notion for Report Storage +**Semrush MCP (alternative):** ``` -mcp__notion__notion-create-pages: Save audit report to SEO Audit Log -mcp__notion__notion-update-page: Update existing audit entries +mcp__semrush__backlink_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="...") +mcp__semrush__execute_report(report_id="...", params={...}) ``` +**OurSEO (on-page link inventory, supplement only):** +``` +mcp__ourseo__crawl_website(url="", max_pages=100) +# Extract internal/outbound link inventory from crawl output — NOT a backlink graph. +``` + +### Korean platform mapping + +Backlinks from Korean platforms (Naver Blog, Cafe, Tistory, Brunch, Korean news) are often underrepresented in both Ahrefs and Semrush. After pulling from the chosen backend, supplement with `WebSearch` for major Korean directories and brand-name queries on Naver to spot-check coverage gaps. + +Always record the chosen data source in the report **Overview** so future audits can compare like-for-like. + ## Workflow ### 1. Backlink Profile Audit diff --git a/custom-skills/22-seo-link-building/desktop/skill.yaml b/custom-skills/22-seo-link-building/desktop/skill.yaml index fd238a4..e15645c 100644 --- a/custom-skills/22-seo-link-building/desktop/skill.yaml +++ b/custom-skills/22-seo-link-building/desktop/skill.yaml @@ -1,8 +1,14 @@ name: seo-link-building description: | Link building diagnosis and backlink analysis. Triggers: backlink audit, link building, referring domains, toxic links, link gap, broken backlinks. + +# Allowed tools list every backend the skill can pull backlink data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__ahrefs__* # default — backlink graph is Ahrefs' strongest moat + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__semrush__* # backlink_research (alternative) + - mcp__ourseo__* # gap: OurSEO has no backlink graph — Web/MCP only as supplement - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/22-seo-link-building/desktop/tools/ourseo.md b/custom-skills/22-seo-link-building/desktop/tools/ourseo.md new file mode 100644 index 0000000..7170bfe --- /dev/null +++ b/custom-skills/22-seo-link-building/desktop/tools/ourseo.md @@ -0,0 +1,35 @@ +# OurSEO Agent (CLI + MCP) + +**OurSEO is not a backlink-graph backend.** The OurSEO stack does not crawl the public web for inbound links; it only inventories outbound and internal links from the target site itself. + +Use OurSEO here only as a **supplement** to Ahrefs or Semrush — never as the primary backlink source. + +## What OurSEO can do for link work + +```bash +# Crawl the target site for outbound and internal link inventory +our collect crawl https:// --max-pages 200 + +# Schema-side sameAs validation (links from JSON-LD) +our audit sameas https:// --brand "" +``` + +MCP equivalent (Claude Desktop): + +``` +mcp__ourseo__crawl_website(url="", max_pages=200) +``` + +Output includes per-page `links` dict with internal/external entries — useful for: +- Auditing **internal** linking to high-value pages. +- Validating that **sameAs** schema links resolve (not dead). +- Counting outbound link velocity for content templates. + +## Not for this skill when + +- **Anything inbound** — referring domains, anchor distribution, broken backlinks, DR, link velocity. Use Ahrefs (default) or Semrush. +- **Toxic link detection** — needs an authoritative backlink graph; OurSEO has none. + +## Korean platform mapping + +Pair Ahrefs/Semrush output with `WebSearch` for Korean platforms that both vendors underrepresent: Naver Blog, Cafe, Tistory, Brunch, Korean news. diff --git a/custom-skills/22-seo-link-building/desktop/tools/semrush.md b/custom-skills/22-seo-link-building/desktop/tools/semrush.md new file mode 100644 index 0000000..d689a67 --- /dev/null +++ b/custom-skills/22-seo-link-building/desktop/tools/semrush.md @@ -0,0 +1,30 @@ +# Semrush MCP + +Alternative backlink backend. Use when the user is already in Semrush context, wants a second opinion, or doesn't have an Ahrefs subscription. Ahrefs remains the default for backlink work in this skill. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key reports + +- `backlink_research` — referring domains, backlink count, anchor distribution +- Authority Score (Semrush's equivalent of Ahrefs DR) +- Toxic Score for risk flagging + +## Example + +``` +mcp__semrush__backlink_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="") +mcp__semrush__execute_report(report_id="", params={...}) +``` + +## When to use over Ahrefs + +- User explicitly prefers Semrush data. +- Cross-vendor verification ("does Semrush agree with Ahrefs on this referring domain?"). +- Authority Score weighting instead of DR. + +## Not for this skill when + +- **Default backlink work** — Ahrefs has the stronger backlink graph; use it unless the user named Semrush. +- **Korean platform refdomains** — both Semrush and Ahrefs underrepresent Naver Blog/Cafe/Tistory; supplement with WebSearch. diff --git a/custom-skills/23-seo-content-strategy/desktop/SKILL.md b/custom-skills/23-seo-content-strategy/desktop/SKILL.md index b540a5f..326cb14 100644 --- a/custom-skills/23-seo-content-strategy/desktop/SKILL.md +++ b/custom-skills/23-seo-content-strategy/desktop/SKILL.md @@ -18,25 +18,74 @@ Audit existing content performance, identify topic gaps vs competitors, map topi 4. **Editorial Calendar** - Prioritized content creation schedule 5. **Korean Content Patterns** - Naver Blog style, 후기, 추천 format analysis -## MCP Tool Usage +## Data Source Selection -### SEO Data +This skill can pull content + keyword + traffic data from multiple backends. **Pick one backend per data type per task** — content strategy spans multiple data classes, so you'll often combine 2 backends (e.g., one for keyword discovery + one for on-page inventory). + +| Backend | Best for | Notes | +|---|---|---| +| **Semrush MCP** (`mcp__semrush__*`) | **Default** for organic content discovery, keyword expansion, top pages by traffic | `organic_research`, `keyword_research`, `overview_research` → `get_report_schema` → `execute_report`. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Top-pages-by-traffic for competitor sites, content-decay candidates, Korean platform refdomains | `site-explorer-top-pages`, `site-explorer-pages-history`, `keywords-explorer-*`, `gsc-pages` (first-party). | +| **OurSEO MCP** (`mcp__ourseo__*`) | **On-page content inventory** — what the target site itself publishes | `crawl_website` for content URLs + titles + H1s; `find_similar_pages` for topic clustering. Pair with a keyword backend for performance data. | +| **OurSEO CLI** (`our keywords *`, `our serp *`) | DataForSEO under the hood for Korean batch keyword + competitor pulls | Claude Code only (Bash). Best for `--location 2410` Korean content gap work. | +| **GSC** (via `our research search-console` or Ahrefs `gsc-*`) | **Cannibalization detection** — query × page where multiple URLs split impressions; first-party content performance | Only first-party source — required for accurate decay detection on the target site. | +| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Fallback when `our` CLI isn't running | Same data as `our keywords *` / `our serp *`. | + +### 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 content decay / cannibalization on the target site** → use **GSC** (first-party impression data is required). +4. **Task is on-page content inventory** → use **OurSEO crawl_website**. +5. **Default for keyword + competitor pulls**: Semrush MCP (English markets); OurSEO CLI (`--location 2410`) for Korean markets. +6. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**Semrush MCP (default keyword/content discovery):** ``` -our-seo-agent CLI: Primary content/traffic data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary content data +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__keyword_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="...") +mcp__semrush__execute_report(report_id="...", params={...}) ``` -### WebSearch for Content Research +**Ahrefs MCP (top pages by traffic, decay candidates):** ``` -WebSearch: Research content topics and competitor strategies -WebFetch: Analyze competitor page content and structure +mcp__ahrefs__site-explorer-top-pages(target="", country="us", limit=100) +mcp__ahrefs__site-explorer-pages-history(target="", history="monthly") +mcp__ahrefs__keywords-explorer-overview(keyword="", country="us") ``` -### Notion for Report Storage +**OurSEO MCP (on-page content inventory):** ``` -notion-create-pages: Save audit reports to SEO Audit Log +mcp__ourseo__crawl_website(url="", max_pages=200) +mcp__ourseo__find_similar_pages(crawl_path="", query="") ``` +**OurSEO CLI (Korean batch):** +```bash +our keywords ideas "" --location 2410 --limit 50 +our keywords for-site --location 2410 --limit 100 +our serp ranked-keywords --location 2410 --limit 100 +``` + +**GSC (cannibalization + decay):** +```bash +our research search-console combined --site sc-domain: --days 90 +# Group by query; flag queries where multiple pages share impressions. +``` + +### 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` | + +Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like. + ## Workflow ### 1. Content Audit diff --git a/custom-skills/23-seo-content-strategy/desktop/skill.yaml b/custom-skills/23-seo-content-strategy/desktop/skill.yaml index 4ec2631..d5334d0 100644 --- a/custom-skills/23-seo-content-strategy/desktop/skill.yaml +++ b/custom-skills/23-seo-content-strategy/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-content-strategy description: | Content strategy and planning for SEO. Triggers: content audit, content strategy, content gap, topic clusters, content brief, editorial calendar, content decay. + +# Allowed tools list every backend the skill can pull content/keyword data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__semrush__* # default for organic content + keyword discovery + - mcp__ahrefs__* # site-explorer-top-pages, keywords-explorer + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__ourseo__* # crawl_website for on-page content inventory + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our keywords *`, `our serp *` CLI (Claude Code only) - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/23-seo-content-strategy/desktop/tools/ahrefs.md b/custom-skills/23-seo-content-strategy/desktop/tools/ahrefs.md index 5d918e0..54e5915 100644 --- a/custom-skills/23-seo-content-strategy/desktop/tools/ahrefs.md +++ b/custom-skills/23-seo-content-strategy/desktop/tools/ahrefs.md @@ -1,15 +1,32 @@ -# Ahrefs +# Ahrefs MCP -> TODO: Document tool usage for this skill +Use for **top-pages-by-traffic** views on competitor sites, **content decay** candidates on the target, and Korean platform refdomains. Namespace: `mcp__ahrefs__*` / `mcp__claude_ai_Ahrefs__*`. -## Available Commands +## Key endpoints -- [ ] List commands +- `site-explorer-top-pages` — pages ranked by traffic for any domain (target or competitor) +- `site-explorer-pages-history` — trend in indexed pages over time (decay signal) +- `site-explorer-pages-by-traffic` — sorted by current traffic +- `site-explorer-pages-by-internal-links` — informs internal-linking opportunities +- `keywords-explorer-overview` / `-related-terms` / `-matching-terms` — topic expansion +- `gsc-pages` — first-party top pages when GSC is connected to the project -## Configuration +## Example -- [ ] Add configuration details +``` +mcp__ahrefs__site-explorer-top-pages(target="", country="us", limit=100) +mcp__ahrefs__site-explorer-pages-history(target="", history="monthly") +mcp__ahrefs__keywords-explorer-related-terms(keyword="", country="us", limit=50) +``` -## Examples +## Strengths for this skill -- [ ] Add usage examples +- Best ranked-by-traffic view of competitor content inventory. +- Historical pages-history surfaces decaying content quickly. +- Pairs well with OurSEO crawl (which gives the on-page side). + +## Not for this skill when + +- **On-page content inventory of the target** — OurSEO `crawl_website` is the ground-truth source. +- **Cannibalization detection** on the target — GSC first-party data is required. +- **Korean Naver content** — Ahrefs underrepresents Naver Blog/Cafe; use `our research naver *` and WebSearch. diff --git a/custom-skills/23-seo-content-strategy/desktop/tools/gsc.md b/custom-skills/23-seo-content-strategy/desktop/tools/gsc.md new file mode 100644 index 0000000..8e94e3c --- /dev/null +++ b/custom-skills/23-seo-content-strategy/desktop/tools/gsc.md @@ -0,0 +1,42 @@ +# Google Search Console + +**Required** for two content-strategy tasks that no other backend can do honestly: + +1. **Cannibalization detection** — query × page combos where multiple URLs share impressions. +2. **Decay detection** — period-over-period impression decline on the target's existing pages. + +## CLI commands + +```bash +# Top queries — what the site already ranks for +our research search-console queries --site sc-domain: --days 28 + +# Top pages by clicks/impressions +our research search-console pages --site sc-domain: --days 28 + +# Combined query × page — REQUIRED for cannibalization +our research search-console combined --site sc-domain: --days 90 +``` + +`sc-domain:` prefix for Domain-verified properties; URL-prefix properties use the plain URL. + +## Decay workflow + +1. Pull `pages` for the last 90 days. +2. Pull `pages` for the same 90-day window from 90 days prior (or use cached prior runs). +3. Diff impression / click counts per URL. +4. Flag URLs with >30% impression decline as decay candidates. +5. Cross-reference with `our collect crawl` output to check freshness signals (last-modified, content age). + +## Cannibalization workflow + +1. Pull `combined` over 90 days. +2. Group by query; count distinct URLs per query. +3. Flag queries where 2+ URLs each have >100 impressions — the site is competing with itself. + +## Not for this skill when + +- **Net-new content discovery** — GSC only knows what already ranks. Use Semrush/Ahrefs for gap discovery. +- **Competitor performance** — single-site only. + +Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`. diff --git a/custom-skills/23-seo-content-strategy/desktop/tools/ourseo.md b/custom-skills/23-seo-content-strategy/desktop/tools/ourseo.md new file mode 100644 index 0000000..17a737c --- /dev/null +++ b/custom-skills/23-seo-content-strategy/desktop/tools/ourseo.md @@ -0,0 +1,39 @@ +# OurSEO Agent (CLI + MCP) + +The **on-page** half of content strategy work — what the target site itself publishes, in what shape, with what schema. Pair with a keyword backend (Semrush/Ahrefs) for performance data. + +## CLI commands (Claude Code) + +```bash +# Crawl the target for content inventory (titles, H1s, meta, last-modified) +our collect crawl https:// --max-pages 500 + +# Korean batch keyword research for content gaps +our keywords ideas "" --location 2410 --limit 50 +our keywords for-site --location 2410 --limit 100 +our serp ranked-keywords --location 2410 --limit 100 + +# Naver-specific content discovery +our research naver keywords ideas "" --limit 30 +our research naver serp "" +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__crawl_website(url="", max_pages=200) +mcp__ourseo__find_similar_pages(crawl_path="", query="") +mcp__ourseo__search_knowledge_graph(query="") +``` + +## Strengths for this skill + +- **`crawl_website` is the ground-truth on-page content inventory.** No vendor estimates — just what the site publishes. +- **`find_similar_pages`** does semantic clustering on a prior crawl (Vertex AI embeddings) — useful for topic-cluster building and cannibalization candidates. +- Korean Naver content discovery via `our research naver *` covers a market Semrush/Ahrefs don't reach. + +## Not for this skill when + +- **Search volume / KD per keyword** — Semrush MCP is the cleanest source. +- **Top pages by traffic on competitor sites** — Ahrefs `site-explorer-top-pages`. +- **First-party content performance** — GSC `pages` / `combined` reports. diff --git a/custom-skills/23-seo-content-strategy/desktop/tools/semrush.md b/custom-skills/23-seo-content-strategy/desktop/tools/semrush.md new file mode 100644 index 0000000..7250fda --- /dev/null +++ b/custom-skills/23-seo-content-strategy/desktop/tools/semrush.md @@ -0,0 +1,34 @@ +# Semrush MCP + +**Default** for organic content discovery and keyword expansion in content strategy work. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key reports + +- `organic_research` — organic keywords + top pages for a domain +- `keyword_research` — expansion, volume, KD, intent +- `overview_research` — domain-level traffic/visibility + +## Example + +``` +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__keyword_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="") +mcp__semrush__execute_report(report_id="", params={...}) +``` + +Korean market: `database="kr"`. + +## Strengths for this skill + +- Best overall keyword + organic competitor view. +- Cleanest discovery → schema → execute pattern for batch content brief generation. +- Pairs with OurSEO crawl (on-page) and GSC (first-party performance). + +## Not for this skill when + +- **On-page inventory of target site** — OurSEO `crawl_website`. +- **Cannibalization detection** — GSC first-party `combined` report. +- **Korean Naver content** — `our research naver *` covers Naver-specific patterns Semrush doesn't. diff --git a/custom-skills/24-seo-ecommerce/desktop/SKILL.md b/custom-skills/24-seo-ecommerce/desktop/SKILL.md index a4e6c8d..620b7ad 100644 --- a/custom-skills/24-seo-ecommerce/desktop/SKILL.md +++ b/custom-skills/24-seo-ecommerce/desktop/SKILL.md @@ -21,25 +21,75 @@ Audit e-commerce sites for product page optimization, structured data validation 4. **Duplicate Content Detection** - Parameter variants, product variants, pagination issues 5. **Korean Marketplace Presence** - Naver Smart Store, Coupang, Gmarket, 11번가 -## MCP Tool Usage +## Data Source Selection -### SEO Data -``` -our-seo-agent CLI: Primary product page data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary product page data +This skill spans multiple data classes (crawl + schema + keyword + marketplace presence). **Pick one backend per data class** — typically you'll combine: one for crawl/schema, one for keyword/competitor. + +| Backend | Best for | Notes | +|---|---|---| +| **OurSEO** (CLI + MCP) | **Default** for product-page crawl, product schema validation, category taxonomy, canonical/duplicate detection | CLI: `our collect crawl`, `our audit tech`, `our build kg-schema`. MCP: `mcp__ourseo__crawl_website`, `mcp__ourseo__audit_page`. Owns the crawl/audit/schema-fix surface end-to-end. | +| **Semrush MCP** (`mcp__semrush__*`) | E-commerce keyword discovery, organic competitor research, third-party site audit | `keyword_research`, `organic_research`, `siteaudit_research` → `get_report_schema` → `execute_report`. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Product/category backlinks; third-party site audit | `site-explorer-top-pages` (which product/category pages earn links), `site-audit-issues`, `site-audit-page-explorer`. | +| **OurSEO CLI — DataForSEO** (`our keywords *`, `our serp *`) | Korean-market keyword + SERP batch for product/category terms | Claude Code only. `--location 2410` for Korean. | +| **WebSearch / WebFetch** | Korean marketplace presence check (Naver Smart Store, Coupang, Gmarket, 11번가) | Korean marketplaces aren't covered by Semrush/Ahrefs at the listing level — verify presence with direct queries. | +| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Fallback when `our` CLI isn't running | Same data as `our keywords *` / `our serp *`. | + +### 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 product schema / on-page audit / duplicate detection** → use **OurSEO** (it owns the schema + canonical + fix engine). +4. **Task is e-commerce keyword discovery** → Semrush MCP (English) or OurSEO CLI (`--location 2410` Korean). +5. **Task is Korean marketplace presence** → WebSearch/WebFetch (no MCP backend covers this). +6. **Default for general e-commerce audits**: **OurSEO** (crawl + schema + fix) **paired with** Semrush MCP (keyword + competitor signal). +7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**OurSEO CLI (product-page crawl + schema audit, default):** +```bash +our collect crawl https://.com --max-pages 100 +our audit tech https://.com +our analyze mysql-batch --session --export missing-schema --format excel +our build kg-schema --type Product --name "" --url ``` -### WebSearch for Marketplace Checks +**OurSEO MCP (Claude Desktop equivalent):** ``` -WebSearch: Search for brand presence on Korean marketplaces -WebFetch: Fetch and analyze marketplace listing pages +mcp__ourseo__crawl_website(url="", max_pages=100) +mcp__ourseo__audit_page(url="", audit_type="schema") ``` -### Notion for Report Storage +**Semrush MCP (e-commerce keyword + competitor):** ``` -mcp__notion__notion-create-pages: Save audit report to SEO Audit Log database +mcp__semrush__keyword_research(query="", database="us") +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__siteaudit_research(query="", database="us") ``` +**Ahrefs MCP (top pages + site audit):** +``` +mcp__ahrefs__site-explorer-top-pages(target="", country="us", limit=100) +mcp__ahrefs__site-audit-issues(project_id="") +mcp__ahrefs__site-audit-page-explorer(project_id="") +``` + +**OurSEO CLI — Korean batch:** +```bash +our keywords ideas "" --location 2410 --limit 50 +our serp ranked-keywords --location 2410 --limit 100 +``` + +**Korean marketplace presence (WebSearch):** +``` +WebSearch: smartstore.naver.com "" +WebSearch: coupang.com "" +WebSearch: gmarket.co.kr "" +WebSearch: 11st.co.kr "" +``` + +Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like. + ## Workflow ### 1. Product Page Audit diff --git a/custom-skills/24-seo-ecommerce/desktop/skill.yaml b/custom-skills/24-seo-ecommerce/desktop/skill.yaml index 3b29eeb..0447fe7 100644 --- a/custom-skills/24-seo-ecommerce/desktop/skill.yaml +++ b/custom-skills/24-seo-ecommerce/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-ecommerce description: | E-commerce SEO audit and optimization. Triggers: product SEO, e-commerce audit, product schema, category SEO, Smart Store, marketplace SEO. + +# Allowed tools list every backend the skill can pull e-commerce data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__ourseo__* # default for crawl + schema audit (audit_page, crawl_website) + - mcp__semrush__* # e-commerce keyword + organic_research + siteaudit_research + - mcp__ahrefs__* # site-explorer-* for product/category backlinks; site-audit-* + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our` CLI: crawl, audit, schema commands - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/24-seo-ecommerce/desktop/tools/ahrefs.md b/custom-skills/24-seo-ecommerce/desktop/tools/ahrefs.md index 5d918e0..d1a6619 100644 --- a/custom-skills/24-seo-ecommerce/desktop/tools/ahrefs.md +++ b/custom-skills/24-seo-ecommerce/desktop/tools/ahrefs.md @@ -1,15 +1,30 @@ -# Ahrefs +# Ahrefs MCP -> TODO: Document tool usage for this skill +Use for **product/category backlinks** and third-party **site audit** views on e-commerce sites. Namespace: `mcp__ahrefs__*` / `mcp__claude_ai_Ahrefs__*`. -## Available Commands +## Key endpoints -- [ ] List commands +- `site-explorer-top-pages` — which product/category pages earn the most links/traffic +- `site-explorer-pages-by-backlinks` — link equity distribution across the catalog +- `site-audit-issues` — schema, canonical, parameter-URL issues from Ahrefs' crawler +- `site-audit-page-explorer` — per-page issue surfacing +- `keywords-explorer-overview` — product-term volume / KD -## Configuration +## Example -- [ ] Add configuration details +``` +mcp__ahrefs__site-explorer-top-pages(target="", country="us", limit=100) +mcp__ahrefs__site-audit-issues(project_id="") +mcp__ahrefs__keywords-explorer-overview(keyword="", country="us") +``` -## Examples +## Strengths for this skill -- [ ] Add usage examples +- Surfaces which **product pages** earn external links — informs which products deserve hero-page promotion. +- Site Audit catches canonical / parameter-URL issues across the catalog without running your own crawler. + +## Not for this skill when + +- **Product schema validation** — OurSEO `audit_page` + `build kg-schema` owns this end-to-end. +- **Korean marketplace presence** (Naver Smart Store, Coupang, Gmarket, 11번가) — Ahrefs doesn't cover these. Use WebSearch. +- **Live catalog crawl of the target** — OurSEO `crawl_website` is more configurable. diff --git a/custom-skills/24-seo-ecommerce/desktop/tools/ourseo.md b/custom-skills/24-seo-ecommerce/desktop/tools/ourseo.md new file mode 100644 index 0000000..8896212 --- /dev/null +++ b/custom-skills/24-seo-ecommerce/desktop/tools/ourseo.md @@ -0,0 +1,44 @@ +# OurSEO Agent (CLI + MCP) + +**Default** for e-commerce crawl, product schema validation, category taxonomy audit, duplicate/canonical detection, and the schema-fix path. Only backend that owns the catalog audit → fix workflow end-to-end. + +## CLI commands (Claude Code) + +```bash +# Crawl the catalog +our collect crawl https:// --max-pages 500 +our collect distributed https:// --workers 8 --max-pages 50000 + +# Technical + schema audit +our audit tech https:// +our analyze mysql-batch --session --export missing-schema --format excel + +# Build / fix Product schema +our build kg-schema --type Product --name "" --url --auto-sameas +our fix entity-schema --site https:// --type Product --entity-name "" --cms --deploy + +# Korean batch keyword work +our keywords ideas "" --location 2410 --limit 50 +our serp ranked-keywords --location 2410 --limit 100 +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__crawl_website(url="", max_pages=500) +mcp__ourseo__audit_page(url="", audit_type="schema") +mcp__ourseo__audit_page(url="", audit_type="tech") +``` + +## Strengths for this skill + +- **Schema validation + deploy** — Product, Offer, AggregateRating, Review, BreadcrumbList. Validates AND can fix via CMS adapters. +- **Canonical + duplicate detection** — built into the crawl + audit stage. +- **Korean market batch** — `--location 2410` covers Korean e-commerce keyword work cheaply. +- **Distributed crawler** scales to multi-tenant catalog audits. + +## Not for this skill when + +- **Competitor organic research** — Semrush `organic_research` is cleaner. +- **Product/category backlink analysis** — Ahrefs `site-explorer-top-pages` + backlinks. +- **Korean marketplace presence detection** — WebSearch (Naver Smart Store, Coupang, Gmarket, 11번가). diff --git a/custom-skills/24-seo-ecommerce/desktop/tools/semrush.md b/custom-skills/24-seo-ecommerce/desktop/tools/semrush.md new file mode 100644 index 0000000..4e61f9b --- /dev/null +++ b/custom-skills/24-seo-ecommerce/desktop/tools/semrush.md @@ -0,0 +1,34 @@ +# Semrush MCP + +Use for **e-commerce keyword discovery**, **organic competitor research**, and **third-party site audit** of stores. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key reports + +- `keyword_research` — product / category term volume + KD + intent +- `organic_research` — competitor store organic keywords + top pages +- `overview_research` — store-level traffic / visibility +- `siteaudit_research` — store-wide technical SEO audit + +## Example + +``` +mcp__semrush__keyword_research(query="", database="us") +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__siteaudit_research(query="", database="us") +``` + +Korean market: `database="kr"`. + +## Strengths for this skill + +- Cleanest competitor-store organic view (which product terms drive their traffic). +- Site audit catches site-wide technical issues quickly. +- `keyword_research` is the default for product/category term expansion. + +## Not for this skill when + +- **Product schema validation** — OurSEO owns this. +- **Korean marketplace presence** — WebSearch only. +- **Catalog crawl with custom configuration** — OurSEO `crawl_website`. diff --git a/custom-skills/25-seo-kpi-framework/desktop/SKILL.md b/custom-skills/25-seo-kpi-framework/desktop/SKILL.md index 7a5f070..1614659 100644 --- a/custom-skills/25-seo-kpi-framework/desktop/SKILL.md +++ b/custom-skills/25-seo-kpi-framework/desktop/SKILL.md @@ -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="", database="us") +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__tracking_research(query="", 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="") +mcp__ahrefs__site-explorer-domain-rating(target="") +mcp__ahrefs__site-explorer-domain-rating-history(target="", history="weekly") +mcp__ahrefs__site-explorer-backlinks-stats(target="") ``` +**OurSEO (technical + indexation + first-party):** +```bash +our audit tech https:// +our analyze mysql-batch --session +our research google index --domain +our research search-console queries --site sc-domain: --days 28 +our research ga4 traffic --property-id +our audit local https:// --gbp-profile +``` + +**OurSEO MCP (Claude Desktop alternate):** +``` +mcp__ourseo__check_index(domain="") +mcp__ourseo__audit_page(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 diff --git a/custom-skills/25-seo-kpi-framework/desktop/skill.yaml b/custom-skills/25-seo-kpi-framework/desktop/skill.yaml index a85a1e2..e8a19b7 100644 --- a/custom-skills/25-seo-kpi-framework/desktop/skill.yaml +++ b/custom-skills/25-seo-kpi-framework/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-kpi-framework description: | SEO KPI and performance framework. Triggers: SEO KPI, performance report, health score, SEO metrics, ROI, baseline, targets. + +# KPI framework aggregates across ALL backends — every SEO source is fair game. +# Per-METRIC selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__semrush__* # overview_research, organic_research, tracking_research + - mcp__ahrefs__* # site-explorer-metrics, domain-rating, gsc-*, web-analytics-* + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__ourseo__* # audit_page, crawl_website, check_serp, check_index + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our` CLI: full surface (GA4, GSC, GBP, ranking, etc.) - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/25-seo-kpi-framework/desktop/tools/ahrefs.md b/custom-skills/25-seo-kpi-framework/desktop/tools/ahrefs.md index 5d918e0..c2bf257 100644 --- a/custom-skills/25-seo-kpi-framework/desktop/tools/ahrefs.md +++ b/custom-skills/25-seo-kpi-framework/desktop/tools/ahrefs.md @@ -1,15 +1,37 @@ -# Ahrefs +# Ahrefs MCP -> TODO: Document tool usage for this skill +In the KPI framework, Ahrefs owns **backlinks/DR**, contributes alternates for **traffic value** and **visibility**, and provides historical trend series. Namespace: `mcp__ahrefs__*` / `mcp__claude_ai_Ahrefs__*`. -## Available Commands +## KPI dimensions served by Ahrefs -- [ ] List commands +| KPI | Endpoint | +|---|---| +| Domain Rating | `site-explorer-domain-rating` | +| DR history (trend) | `site-explorer-domain-rating-history` | +| Backlink count + dofollow ratio | `site-explorer-backlinks-stats` | +| Referring domains (count + trend) | `site-explorer-refdomains-history` | +| Organic traffic estimate | `site-explorer-metrics` | +| Metrics history (trend) | `site-explorer-metrics-history` | +| Top pages traffic distribution | `site-explorer-top-pages` | +| First-party clicks/impressions (if GSC connected) | `gsc-performance-history`, `gsc-positions-history` | -## Configuration +## Example -- [ ] Add configuration details +``` +mcp__ahrefs__site-explorer-metrics(target="") +mcp__ahrefs__site-explorer-metrics-history(target="", history="weekly") +mcp__ahrefs__site-explorer-domain-rating-history(target="", history="weekly") +``` -## Examples +## Strengths for this skill -- [ ] Add usage examples +- Backlink dimension is unmatched. +- Trend series are pre-computed — useful for period-over-period KPI charts. +- When GSC is connected to the Ahrefs project, first-party CTR / position history is available. + +## Not for this skill when + +- **Technical-health KPI** — OurSEO's audit + crawl is deeper. +- **GA4 / on-site engagement KPI** — `our research ga4 *` only. +- **GBP local KPI** — `our collect gbp *` / `our audit local` only. +- **Indexed pages count** — OurSEO `check_index` / GSC Coverage. diff --git a/custom-skills/25-seo-kpi-framework/desktop/tools/gsc.md b/custom-skills/25-seo-kpi-framework/desktop/tools/gsc.md new file mode 100644 index 0000000..145d895 --- /dev/null +++ b/custom-skills/25-seo-kpi-framework/desktop/tools/gsc.md @@ -0,0 +1,56 @@ +# Google Search Console + +**First-party** clicks / impressions / CTR / position. The only ground-truth source for these KPIs — every modelled estimate from Semrush/Ahrefs/DataForSEO is a proxy. Prefer GSC whenever the site is verified. + +## CLI commands + +```bash +# Top queries (KPI: clicks, impressions, CTR, position per query) +our research search-console queries --site sc-domain: --days 28 + +# Top pages (KPI: clicks, impressions per URL) +our research search-console pages --site sc-domain: --days 28 + +# Query × page combined (KPI: cannibalization, content efficiency) +our research search-console combined --site sc-domain: --days 28 +``` + +`sc-domain:` prefix for Domain-verified properties. + +## KPI dimensions served by GSC + +| KPI | Source | +|---|---| +| Clicks (first-party) | `queries` or `pages` | +| Impressions (first-party) | `queries` or `pages` | +| CTR | computed from clicks / impressions | +| Average position | `queries` | +| Cannibalization signal | `combined` (query × page) | +| Branded vs non-branded split | post-process `queries` output | +| Anonymous queries | Ahrefs `gsc-anonymous-queries` (if Ahrefs project connected) | + +## Ahrefs GSC alternates + +When the site is connected as an Ahrefs project: + +``` +mcp__ahrefs__gsc-performance-history(project_id="") +mcp__ahrefs__gsc-positions-history(project_id="") +mcp__ahrefs__gsc-ctr-by-position(project_id="") +mcp__ahrefs__gsc-anonymous-queries(project_id="") +``` + +## Strengths for this skill + +- Single source of truth for clicks/impressions — non-negotiable in a serious KPI dashboard. +- 28-day, 90-day, and 16-month windows available (GSC default). +- Anonymous queries via Ahrefs surface ~10-30% of impressions Google hides from the standard report. + +## Not for this skill when + +- **Backlinks / DR KPI** — Ahrefs. +- **Traffic value (USD)** — Semrush. +- **GA4 sessions / conversions** — `our research ga4 *`. +- **Competitor KPIs** — GSC is single-site. + +Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`. diff --git a/custom-skills/25-seo-kpi-framework/desktop/tools/ourseo.md b/custom-skills/25-seo-kpi-framework/desktop/tools/ourseo.md new file mode 100644 index 0000000..c20accf --- /dev/null +++ b/custom-skills/25-seo-kpi-framework/desktop/tools/ourseo.md @@ -0,0 +1,38 @@ +# OurSEO Agent (CLI + MCP) + +In the KPI framework, OurSEO owns **technical health**, **indexed pages**, **GA4**, **GBP local**, and **first-party crawl-derived** KPIs. It is also the gateway to GSC via `our research search-console`. + +## KPI dimensions served by OurSEO + +| KPI | Command | +|---|---| +| Technical health score | `our audit tech https://` | +| Crawl efficiency / errors | `our analyze mysql-batch --session ` | +| Indexed pages | `our research google index --domain ` / `mcp__ourseo__check_index` | +| First-party clicks/impressions/CTR | `our research search-console queries --site sc-domain: --days 28` | +| GA4 sessions / traffic / channel | `our research ga4 traffic --property-id ` | +| GA4 landing pages | `our research ga4 landing-pages --property-id ` | +| GA4 channel mix | `our research ga4 channels --property-id ` | +| GBP visibility / reviews / posts | `our collect gbp reviews/locations/posts ...`, `our audit local` | +| Content freshness | `our collect crawl https://` (extracts last-modified) | +| Schema coverage | `our analyze mysql-batch --session --export missing-schema` | + +## MCP equivalents (Claude Desktop) + +``` +mcp__ourseo__check_index(domain="") +mcp__ourseo__audit_page(url="", audit_type="tech") +mcp__ourseo__crawl_website(url="", max_pages=100) +``` + +## Strengths for this skill + +- **First-party** GSC + GA4 + GBP all routed through one CLI — easiest way to get ground-truth KPIs. +- **Owns technical health + indexed pages** end-to-end. +- Stores results in MySQL workspace — supports period-over-period KPI comparison without re-pulling. + +## Not for this skill when + +- **Modelled traffic-value** — Semrush `overview_research` is the cleanest source. +- **Backlinks / DR / Authority** — Ahrefs (or Semrush) backlink endpoints. +- **AI visibility KPI** — Ahrefs Brand Radar. diff --git a/custom-skills/25-seo-kpi-framework/desktop/tools/semrush.md b/custom-skills/25-seo-kpi-framework/desktop/tools/semrush.md new file mode 100644 index 0000000..b999a10 --- /dev/null +++ b/custom-skills/25-seo-kpi-framework/desktop/tools/semrush.md @@ -0,0 +1,40 @@ +# Semrush MCP + +In the KPI framework, Semrush is the **default for organic traffic + visibility + competitor KPIs**. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## KPI dimensions served by Semrush + +| KPI | Report | +|---|---| +| Organic traffic (estimate) | `overview_research` | +| Traffic value (USD) | `overview_research` | +| Visibility / ranking distribution | `tracking_research`, `organic_research` | +| Top organic keywords | `organic_research` | +| Authority Score (DR alternative) | `backlink_research` | +| Competitor organic share | `organic_research` | +| Period-over-period traffic delta | `trends_research` | + +## Example + +``` +mcp__semrush__overview_research(query="", database="us") +mcp__semrush__tracking_research(query="", database="us") +mcp__semrush__trends_research(query="", database="us") +``` + +Korean market: `database="kr"`. + +## Strengths for this skill + +- Cleanest combined traffic-value + visibility dashboard per domain. +- `trends_research` exposes period-over-period directly. +- Default backend for the project's SEO KPI map. + +## Not for this skill when + +- **Backlink / DR KPI** — Ahrefs is the default for this dimension. +- **First-party clicks/impressions/CTR** — GSC via `our research search-console`. +- **GA4 KPI** (sessions, conversions, bounce) — `our research ga4 *`. +- **Local KPI (GBP)** — `our collect gbp *` / `our audit local`. diff --git a/custom-skills/26-seo-international/desktop/SKILL.md b/custom-skills/26-seo-international/desktop/SKILL.md index 814c6cd..5fa7866 100644 --- 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:// --max-pages 200 +our audit tech https:// +our fix hreflang --site https:// ``` -### 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="", max_pages=200) +mcp__ourseo__audit_page(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="") +mcp__ahrefs__site-explorer-metrics-by-country(target="") +mcp__ahrefs__site-audit-issues(project_id="") ``` +**Semrush MCP (cross-market visibility):** +``` +mcp__semrush__organic_research(query="", database="kr") +mcp__semrush__organic_research(query="", database="jp") +mcp__semrush__siteaudit_research(query="", database="us") +``` + +**Redirect-logic audit (manual):** +``` +WebFetch: https:/// with Accept-Language: ko-KR +WebFetch: https:/// with Accept-Language: ja-JP +WebFetch: https:/// 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 diff --git a/custom-skills/26-seo-international/desktop/skill.yaml b/custom-skills/26-seo-international/desktop/skill.yaml index 6dd0be0..63d8eea 100644 --- 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 diff --git a/custom-skills/26-seo-international/desktop/tools/ourseo.md b/custom-skills/26-seo-international/desktop/tools/ourseo.md new file mode 100644 index 0000000..279170a --- /dev/null +++ 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:// --max-pages 500 + +# Technical audit including hreflang +our audit tech https:// + +# Hreflang fix (writes back to CMS if --deploy and CMS adapter configured) +our fix hreflang --site https:// + +# Per-region SERP / Naver expansion checks +our research naver serp "" +our research keywords compare "" --engines naver +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__crawl_website(url="", max_pages=500) +mcp__ourseo__audit_page(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. diff --git a/custom-skills/26-seo-international/desktop/tools/semrush.md b/custom-skills/26-seo-international/desktop/tools/semrush.md new file mode 100644 index 0000000..d49512c --- /dev/null +++ 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="", database="us") +mcp__semrush__organic_research(query="", database="kr") +mcp__semrush__organic_research(query="", database="jp") +mcp__semrush__organic_research(query="", database="cn") +mcp__semrush__organic_research(query="", 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. diff --git a/custom-skills/27-seo-ai-visibility/desktop/SKILL.md b/custom-skills/27-seo-ai-visibility/desktop/SKILL.md index c19a142..f72ea61 100644 --- a/custom-skills/27-seo-ai-visibility/desktop/SKILL.md +++ b/custom-skills/27-seo-ai-visibility/desktop/SKILL.md @@ -35,13 +35,62 @@ Monitor and analyze brand visibility in AI-generated search results. This skill 4. **Recommendations**: Generate actionable Korean-language recommendations 5. **Output**: JSON report and Notion database entry -## Data Sources +## Data Source Selection -| Source | Purpose | -|--------|---------| -| `our-seo-agent` CLI | Primary AI visibility data source (future); use `--input` for pre-fetched JSON | -| WebSearch / WebFetch | Supplementary AI search data | -| Notion MCP | Save audit report to database | +**Single-vendor constraint.** AI search visibility / Brand Radar / share-of-voice in AI answers is currently **Ahrefs-only** among connected SEO MCPs. Neither Semrush nor DataForSEO exposes equivalent endpoints today. This is the one SEO skill where the "let the user choose" framing collapses to a one-option menu for the core capability. + +| Backend | Best for | Notes | +|---|---|---| +| **Ahrefs MCP — Brand Radar** (`mcp__ahrefs__brand-radar-*`) | **Default** (and currently the only viable source) for AI mentions, impressions, share of voice, cited domains/pages, AI response history | Tools: `brand-radar-ai-responses`, `brand-radar-cited-domains`, `brand-radar-cited-pages`, `brand-radar-impressions-overview`, `brand-radar-mentions-overview`, `brand-radar-sov-overview`, `brand-radar-sov-history`, plus `*-entities` variants. | +| **Ahrefs MCP — Management** | Configure Brand Radar prompts and reports | `management-brand-radar-prompts`, `management-brand-radar-reports`. | +| **OurSEO brand monitoring** (`mcp__ourseo__monitor_brand` / `our research google brand`) | Web-wide brand mention scanning — **not** AI-search specific, but useful as a supplement to compare with AI citations | Catches brand mentions in standard Google search; complements Brand Radar's AI-specific view. | +| **WebSearch** | Manual spot-check of AI engines (ChatGPT, Gemini, Perplexity) by querying directly | Not automated — useful for one-off "did the brand appear?" checks. | +| **Semrush MCP** | **No equivalent.** Listed in `allowed-tools` only for future compatibility if Semrush adds an AI-visibility product. | Do not attempt to substitute Semrush for Brand Radar today. | + +### How to pick + +1. **User named Ahrefs explicitly** → use Brand Radar. +2. **Task is AI mentions / impressions / share of voice / cited pages** → Brand Radar is the only option; use it. +3. **Task is general brand monitoring across the web (not AI-specific)** → OurSEO `monitor_brand` is sufficient and cheaper. +4. **Task explicitly compares AI vs traditional brand visibility** → run **both** Brand Radar AND OurSEO `monitor_brand`, document the source per data slice. +5. **No alternative needed** for the core AI-visibility capability — skip the AskUserQuestion fallback unless the user expresses preference uncertainty. + +### Backend call patterns + +**Ahrefs Brand Radar (default):** +``` +mcp__ahrefs__brand-radar-impressions-overview(brand="") +mcp__ahrefs__brand-radar-mentions-overview(brand="") +mcp__ahrefs__brand-radar-sov-overview(brand="", competitors=["",""]) +mcp__ahrefs__brand-radar-sov-history(brand="", history="weekly") +mcp__ahrefs__brand-radar-cited-domains(brand="") +mcp__ahrefs__brand-radar-cited-pages(brand="") +mcp__ahrefs__brand-radar-ai-responses(brand="") +mcp__ahrefs__brand-radar-impressions-history(brand="", history="weekly") +mcp__ahrefs__brand-radar-mentions-history(brand="", history="weekly") +``` + +**Configure prompts / reports:** +``` +mcp__ahrefs__management-brand-radar-prompts() +mcp__ahrefs__management-brand-radar-reports() +``` + +**OurSEO brand monitoring (supplement):** +``` +mcp__ourseo__monitor_brand(brand="", exclude_domains=[""]) +``` + +Or CLI: +```bash +our research google brand "" --exclude +``` + +### Tracking note + +Brand Radar requires the brand to be configured in the user's Ahrefs workspace via `management-brand-radar-prompts`. If a query returns empty, first check that the brand is set up — don't conclude "no AI visibility" from an empty Brand Radar response without verifying configuration. + +Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like. ## Notion Output diff --git a/custom-skills/27-seo-ai-visibility/desktop/skill.yaml b/custom-skills/27-seo-ai-visibility/desktop/skill.yaml index a078255..bf4ae45 100644 --- a/custom-skills/27-seo-ai-visibility/desktop/skill.yaml +++ b/custom-skills/27-seo-ai-visibility/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-ai-visibility description: | AI search visibility and brand radar monitoring. Triggers: AI search, AI visibility, brand radar, AI citations, share of voice, AI answers, AI mentions. + +# AI visibility / Brand Radar is currently Ahrefs-only among the SEO MCPs. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. +# Other backends are listed for supplementary brand-monitoring work. allowed-tools: - - mcp__ahrefs__* + - mcp__ahrefs__* # default (and currently the ONLY) source for Brand Radar / AI visibility + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__ourseo__monitor_brand # OurSEO brand monitoring (web mention scan, not AI-search specific) + - mcp__semrush__* # supplementary — Semrush has no Brand Radar equivalent today + - Bash # `our` CLI: `our research google brand`, `our monitor brand` - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/27-seo-ai-visibility/desktop/tools/ourseo.md b/custom-skills/27-seo-ai-visibility/desktop/tools/ourseo.md new file mode 100644 index 0000000..98fbbbc --- /dev/null +++ b/custom-skills/27-seo-ai-visibility/desktop/tools/ourseo.md @@ -0,0 +1,38 @@ +# OurSEO Agent (CLI + MCP) + +OurSEO is **not an AI-visibility backend.** Use it here only as a supplement for general brand-monitoring work that complements Ahrefs Brand Radar. + +## What OurSEO covers + +```bash +# Web-wide brand mention scan via Google Custom Search +our research google brand "" --exclude + +# Korean engines (Naver brand presence) +our research naver serp "" +``` + +MCP equivalent: + +``` +mcp__ourseo__monitor_brand(brand="", exclude_domains=[""]) +``` + +## How OurSEO + Brand Radar pair + +- **Brand Radar** (Ahrefs) → AI search citations, impressions, SOV, cited pages +- **OurSEO monitor_brand** → standard Google search brand mentions across the web + +Together they show: +- "Where are we cited in AI vs the open web?" +- "Are the high-citation pages in AI also the ones earning standard organic links?" +- "Does our share of voice in AI match our share in Google brand SERPs?" + +## Not for this skill when + +- **AI mentions / impressions / SOV / cited domains/pages** — Brand Radar only. +- **AI engine breakdown** — Brand Radar `brand-radar-ai-responses`. + +## Important + +Treat OurSEO output as a **second axis**, not a substitute. Reporting AI visibility using only `monitor_brand` would mislead the user — those are open-web mentions, not AI citations. diff --git a/custom-skills/27-seo-ai-visibility/desktop/tools/semrush.md b/custom-skills/27-seo-ai-visibility/desktop/tools/semrush.md new file mode 100644 index 0000000..9306b27 --- /dev/null +++ b/custom-skills/27-seo-ai-visibility/desktop/tools/semrush.md @@ -0,0 +1,21 @@ +# Semrush MCP + +**Not applicable** for AI search visibility / Brand Radar today. Semrush does not expose an equivalent product as of 2026-05. + +Listed in this skill's `allowed-tools` only for forward compatibility if Semrush ships an AI-visibility product. + +## Do not use Semrush for + +- AI mentions / impressions / share of voice in AI answers +- Cited domains / cited pages in AI responses +- AI engine breakdown (ChatGPT / Gemini / Perplexity / Claude) +- Brand SOV history in AI search + +## Use instead + +- **Ahrefs Brand Radar** (`mcp__ahrefs__brand-radar-*`) — the only viable backend for the core capability today. +- **OurSEO `monitor_brand`** — for general web-mention monitoring (not AI-search specific) as a supplement. + +## If a Semrush AI product ships + +Update this stub and re-evaluate the Data Source Selection in `SKILL.md`. Until then, keep Brand Radar as the default and do not attempt to substitute Semrush. diff --git a/custom-skills/28-seo-knowledge-graph/desktop/SKILL.md b/custom-skills/28-seo-knowledge-graph/desktop/SKILL.md index 9ef2cc5..0980f5f 100644 --- a/custom-skills/28-seo-knowledge-graph/desktop/SKILL.md +++ b/custom-skills/28-seo-knowledge-graph/desktop/SKILL.md @@ -51,14 +51,60 @@ Analyze brand entity presence in Google Knowledge Graph, Knowledge Panels, Peopl 6. Use **WebSearch** for SERP feature detection 7. Save report to **Notion** SEO Audit Log -## Tools Used +## Data Source Selection -| Tool | Purpose | -|------|---------| -| WebSearch | Search for entity/brand to detect Knowledge Panel | -| WebFetch | Fetch Wikipedia, Wikidata, Naver pages, website schemas | -| WebSearch | SERP feature detection for entity keywords | -| Notion | Save audit reports to SEO Audit Log database | +Entity / Knowledge Graph work spans **KG API lookups**, **on-page schema audit**, **third-party presence checks** (Wikipedia, Wikidata, Naver), and **brand SERP analysis**. Different backends own different slices. + +| Backend | Best for | Notes | +|---|---|---| +| **OurSEO** (CLI + MCP) | **Default** for KG lookups, entity audit, schema generation + fix | CLI: `our research kg lookup`, `our research kg resolve`, `our audit entity`, `our audit sameas`, `our build kg-schema`, `our fix entity-schema`. MCP: `mcp__ourseo__search_knowledge_graph`. Only backend with an integrated KG + entity-fix path. | +| **WebSearch / WebFetch** | Knowledge Panel detection, PAA monitoring, Wikipedia / Wikidata / Naver encyclopedia presence | KG Panel detection via direct Google search is heuristic but unavoidable — no MCP exposes Knowledge Panel structure directly. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | SERP-level entity queries — PAA, brand SERP, FAQ schema appearance | `serp-overview`, `gsc-keywords` (first-party brand query data), `site-audit-issues` for missing schema. | +| **Semrush MCP** (`mcp__semrush__*`) | Brand SERP overview, organic positions for entity-related queries | No dedicated KG endpoints — supplementary only. | + +### 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 KG lookup / entity resolution / sameAs validation / schema fix** → use **OurSEO** (CLI primary, MCP for Desktop). No alternative covers this end-to-end. +4. **Task is Wikipedia / Wikidata / Naver encyclopedia presence** → WebSearch + WebFetch (no MCP backend covers third-party encyclopedias). +5. **Task is brand SERP analysis** → Ahrefs `serp-overview` or Semrush `overview_research`, paired with WebSearch for Knowledge Panel detection. +6. **Default**: **OurSEO `our research kg`** + WebSearch for third-party presence. +7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**OurSEO CLI (default — KG lookup + entity audit + fix):** +```bash +our research kg lookup "" --language ko +our research kg resolve "" --domain --language ko +our audit entity https:// --entity "" --language ko +our audit sameas https:// --brand "" +our build kg-schema --type Organization --name "" --url https:// --auto-sameas +our fix entity-schema --site https:// --type Organization --entity-name "" --auto-sameas --cms ghost --deploy +``` + +**OurSEO MCP (Claude Desktop):** +``` +mcp__ourseo__search_knowledge_graph(query="", language="ko") +``` + +**Third-party presence (WebSearch / WebFetch):** +``` +WebSearch: "" site:wikipedia.org +WebFetch: https://www.wikidata.org/wiki/Special:Search?search= +WebSearch: "" site:terms.naver.com # Naver encyclopedia +WebSearch: "" site:kin.naver.com # Naver 지식iN +``` + +**Brand SERP analysis (Ahrefs / Semrush):** +``` +mcp__ahrefs__serp-overview(keyword="", country="us") +mcp__ahrefs__gsc-keywords(project_id="") # First-party brand query data +mcp__semrush__overview_research(query="", database="us") +``` + +Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like. ## Notion Output diff --git a/custom-skills/28-seo-knowledge-graph/desktop/skill.yaml b/custom-skills/28-seo-knowledge-graph/desktop/skill.yaml index ded87ca..b618266 100644 --- a/custom-skills/28-seo-knowledge-graph/desktop/skill.yaml +++ b/custom-skills/28-seo-knowledge-graph/desktop/skill.yaml @@ -1,8 +1,15 @@ name: seo-knowledge-graph description: | Knowledge Graph and entity SEO analysis. Triggers: knowledge panel, entity SEO, knowledge graph, PAA, FAQ schema, Wikipedia, Wikidata, brand entity. + +# Allowed tools list every backend the skill can pull entity / Knowledge Graph data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__ourseo__* # default — search_knowledge_graph + audit_page entity schema + - mcp__semrush__* # supplementary (no direct KG endpoints) + - mcp__ahrefs__* # site-audit-* for schema issues; gsc-* for entity query data + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - Bash # `our research kg *`, `our audit entity`, `our build kg-schema` - mcp__notion__* - - WebSearch + - WebSearch # Wikipedia / Wikidata / Naver presence checks - WebFetch diff --git a/custom-skills/28-seo-knowledge-graph/desktop/tools/ourseo.md b/custom-skills/28-seo-knowledge-graph/desktop/tools/ourseo.md new file mode 100644 index 0000000..36c1f40 --- /dev/null +++ b/custom-skills/28-seo-knowledge-graph/desktop/tools/ourseo.md @@ -0,0 +1,53 @@ +# OurSEO Agent (CLI + MCP) + +**Default** for Knowledge Graph + entity SEO end-to-end. Only backend with an integrated KG lookup → entity audit → schema build → schema fix workflow. + +## CLI commands (Claude Code) + +```bash +# KG lookup (Google KG Search API) +our research kg lookup "" --language ko +our research kg resolve "" --domain --language ko + +# Entity audit (sameAs, entity schemas on the site) +our audit entity https:// --entity "" --language ko +our audit sameas https:// --brand "" + +# Build entity schema as JSON-LD @graph +our build kg-schema --type Organization --name "" --url https:// --auto-sameas + +# Fix entity schema in CMS (Ghost / WordPress / Strapi) +our fix entity-schema --site https:// --type Organization \ + --entity-name "" --auto-sameas --cms ghost --deploy + +# Archive audit to Notion +our output notion kg-audit --input entity-report.json +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__search_knowledge_graph(query="", language="ko") +``` + +## Strengths for this skill + +- **Only end-to-end path**: KG lookup → entity audit → schema build → CMS deploy. +- **sameAs validation** — checks that JSON-LD sameAs links resolve (not 404 / 403). +- **Korean coverage** — Korean entity workflows (Naver encyclopedia, 지식iN) baked in via the CLI. +- **`@graph` JSON-LD output** with auto-sameAs — produces deploy-ready schema. + +## Not for this skill when + +- **Knowledge Panel detection on Google SERP** — WebSearch (no MCP exposes Knowledge Panel structure). +- **Wikipedia / Wikidata presence** — WebSearch / WebFetch. +- **First-party brand-query data** (impressions, CTR for brand searches) — GSC or Ahrefs `gsc-keywords`. + +## Config + +| Env var | Purpose | +|---|---| +| `GOOGLE_KG_API_KEY` | Knowledge Graph Search API key (op://Development/...) | +| `OURSEO_GHOST_API_KEY` / `OURSEO_WP_*` / `OURSEO_STRAPI_API_TOKEN` | CMS adapter auth for `--deploy` | + +Cross-reference: [[reference_1password_api_credentials]] in memory. diff --git a/custom-skills/28-seo-knowledge-graph/desktop/tools/semrush.md b/custom-skills/28-seo-knowledge-graph/desktop/tools/semrush.md new file mode 100644 index 0000000..a6ab3c5 --- /dev/null +++ b/custom-skills/28-seo-knowledge-graph/desktop/tools/semrush.md @@ -0,0 +1,29 @@ +# Semrush MCP + +Semrush has **no dedicated Knowledge Graph / entity endpoints.** Use only as a supplement for **brand SERP overview** and organic positions on entity-related queries. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## What Semrush can do here + +``` +# Brand SERP overview — what shows up for the brand name +mcp__semrush__overview_research(query="", database="us") + +# Organic positions for entity-related queries (FAQ-style queries the entity should answer) +mcp__semrush__organic_research(query="", database="us") +``` + +## Not for this skill when + +- **Knowledge Graph lookup / entity resolution** — OurSEO `search_knowledge_graph` / `our research kg lookup`. +- **Wikipedia / Wikidata / Naver encyclopedia presence** — WebSearch / WebFetch. +- **Entity schema audit + fix** (Organization, Person, LocalBusiness, sameAs) — OurSEO `our audit entity` / `our fix entity-schema`. +- **PAA / FAQ rich result detection** — WebSearch on the brand SERP. + +## When Semrush is useful here + +- Branded vs non-branded query split for the entity (post-process `organic_research` output). +- Competitor entity comparison ("does competitor X also have an organic presence for entity Y?"). + +Always pair with OurSEO + WebSearch for the actual entity work; Semrush is auxiliary here. diff --git a/custom-skills/31-seo-competitor-intel/desktop/SKILL.md b/custom-skills/31-seo-competitor-intel/desktop/SKILL.md index c28da36..35cfc0a 100644 --- a/custom-skills/31-seo-competitor-intel/desktop/SKILL.md +++ b/custom-skills/31-seo-competitor-intel/desktop/SKILL.md @@ -24,24 +24,72 @@ Comprehensive competitor intelligence for SEO: auto-discover competitors, build 7. **Alert Generation** - Flag significant competitive movements 8. **Market Share Estimation** - Organic traffic share within competitive set -## MCP Tool Usage +## Data Source Selection -### SEO Data +Competitor intelligence spans **organic profile** (traffic, keywords), **backlink profile** (DR, refdomains), **content velocity** (top pages, new content), and **Korean platform presence**. Different backends own different slices. + +| Backend | Best for | Notes | +|---|---|---| +| **Semrush MCP** (`mcp__semrush__*`) | **Default** for organic competitor profile, keyword overlap, traffic trends | `organic_research`, `trends_research`, `overview_research` → `get_report_schema` → `execute_report`. Auto-discovery of competitors. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Backlink profile, organic competitor discovery, top-pages-by-traffic, historical DR | `site-explorer-organic-competitors`, `site-explorer-organic-keywords`, `site-explorer-top-pages`, `site-explorer-domain-rating-history`, `site-explorer-backlinks-stats`. Pair with Semrush for cross-check. | +| **OurSEO** (CLI + MCP) | SERP overlap spot-checks, content similarity, crawl-derived content velocity | `mcp__ourseo__check_serp`, `mcp__ourseo__find_similar_pages`, `mcp__ourseo__crawl_website`. CLI: `our serp competitors`, `our serp ranked-keywords`. | +| **OurSEO CLI — Korean** (`our research naver *`) | Naver-engine competitor analysis (Blog/Cafe/Smart Store presence, Naver SERP) | Naver-only; required for Korean market since Semrush/Ahrefs don't cover Naver. | +| **WebSearch** | Korean Blog/Cafe/Tistory/Brunch presence checks | Supplement Korean platform mapping when Semrush/Ahrefs underrepresent these. | +| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Fallback for ranked-keywords / SERP competitors when `our` CLI isn't running | Same data as `our serp *`. | + +### 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 backlink-focused** (DR comparison, link gap) → Ahrefs (backlink-graph moat). +4. **Task is keyword/traffic-focused** → Semrush (organic competitor view is strongest). +5. **Task is Korean-market competitor analysis** → **OurSEO CLI** (`our research naver *` + `our serp * --location 2410`). Korean platforms aren't covered by Semrush/Ahrefs. +6. **Default**: Semrush MCP for organic + Ahrefs for backlinks (paired). Korean override: OurSEO CLI. +7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**Semrush MCP (default organic):** ``` -our-seo-agent CLI: Primary competitive data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary competitor data +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__trends_research(query="", database="us") +mcp__semrush__overview_research(query="", database="us") ``` -### Notion for Report Storage +**Ahrefs MCP (backlink + top pages):** ``` -mcp__notion__notion-create-pages: Save reports to SEO Audit Log +mcp__ahrefs__site-explorer-organic-competitors(target="") +mcp__ahrefs__site-explorer-organic-keywords(target="", country="us", limit=500) +mcp__ahrefs__site-explorer-top-pages(target="", country="us") +mcp__ahrefs__site-explorer-domain-rating-history(target="", history="weekly") +mcp__ahrefs__site-explorer-backlinks-stats(target="") ``` -### WebSearch for Korean Market +**OurSEO (SERP overlap + content similarity):** ``` -WebSearch: Check Naver Blog/Cafe presence for competitors +mcp__ourseo__check_serp(keyword="", domain="", country="kr") +mcp__ourseo__find_similar_pages(crawl_path="", query="") +mcp__ourseo__crawl_website(url="", max_pages=50) ``` +**OurSEO CLI (Korean batch):** +```bash +our serp ranked-keywords --location 2410 --limit 100 +our serp competitors --location 2410 +our research naver serp "" +our research naver keywords ideas "" +``` + +**Korean platform presence (WebSearch):** +``` +WebSearch: blog.naver.com "" +WebSearch: cafe.naver.com "" +WebSearch: tistory.com "" +``` + +Always record the chosen data source(s) in the report **Overview** so future runs can compare like-for-like. + ## Workflow ### Competitor Profiling diff --git a/custom-skills/31-seo-competitor-intel/desktop/skill.yaml b/custom-skills/31-seo-competitor-intel/desktop/skill.yaml index c55c3ff..3cfe2c3 100644 --- a/custom-skills/31-seo-competitor-intel/desktop/skill.yaml +++ b/custom-skills/31-seo-competitor-intel/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-competitor-intel description: | Competitor intelligence and SEO benchmarking. Triggers: competitor analysis, competitive intelligence, competitor comparison, threat assessment, market position, benchmarking. + +# Allowed tools list every backend the skill can pull competitive data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* + - mcp__semrush__* # default — organic_research, trends_research, backlink_research + - mcp__ahrefs__* # site-explorer-* (organic competitors, backlinks) + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__ourseo__* # check_serp, find_similar_pages, crawl_website + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our` CLI — full surface - mcp__notion__* - - WebSearch + - WebSearch # Naver Blog/Cafe presence checks - WebFetch diff --git a/custom-skills/31-seo-competitor-intel/desktop/tools/ourseo.md b/custom-skills/31-seo-competitor-intel/desktop/tools/ourseo.md new file mode 100644 index 0000000..3fcbab3 --- /dev/null +++ b/custom-skills/31-seo-competitor-intel/desktop/tools/ourseo.md @@ -0,0 +1,40 @@ +# OurSEO Agent (CLI + MCP) + +For competitor intel, OurSEO contributes **SERP overlap spot-checks**, **content similarity / topic clustering**, and **Korean-market Naver competitor analysis** that Semrush/Ahrefs don't cover. + +## CLI commands (Claude Code) + +```bash +# SERP overlap and competitor SERP pulls +our serp competitors --location 2410 +our serp ranked-keywords --location 2410 --limit 100 +our serp domain-overview --location 2410 + +# Competitor crawl for content velocity / inventory +our collect crawl https:// --max-pages 100 + +# Korean engine competitor analysis (Naver) +our research naver serp "" +our research naver keywords ideas "" --limit 30 +our research keywords compare "" --engines naver +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__check_serp(keyword="", domain="", country="kr") +mcp__ourseo__find_similar_pages(crawl_path="", query="") +mcp__ourseo__crawl_website(url="", max_pages=50) +``` + +## Strengths for this skill + +- **Naver competitor analysis** — only path that covers Naver Blog/Cafe/Smart Store/Knowledge iN competitor presence. +- **`find_similar_pages`** uses Vertex AI embeddings on prior crawl data — good for topic-cluster overlap detection between target and competitor. +- **SERP spot-checks** are cheap; useful for ad-hoc "do we share top-10 with competitor X for keyword Y" questions. + +## Not for this skill when + +- **Backlink-graph competitor comparison** — Ahrefs. +- **Modelled traffic / Authority Score** for the threat-scoring matrix — Semrush. +- **Historical trend series** (DR over time, traffic over time) — Ahrefs/Semrush history endpoints. diff --git a/custom-skills/31-seo-competitor-intel/desktop/tools/semrush.md b/custom-skills/31-seo-competitor-intel/desktop/tools/semrush.md new file mode 100644 index 0000000..1394394 --- /dev/null +++ b/custom-skills/31-seo-competitor-intel/desktop/tools/semrush.md @@ -0,0 +1,35 @@ +# Semrush MCP + +**Default** for competitor organic profile, keyword overlap, traffic trends, and competitor auto-discovery. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key reports + +- `organic_research` — organic keywords + competitor pulls for any domain +- `trends_research` — period-over-period traffic deltas +- `overview_research` — domain-level traffic/visibility for the comparison matrix +- `backlink_research` — Authority Score and referring-domain counts (paired with Ahrefs for cross-check) + +## Example + +``` +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__trends_research(query="", database="us") +mcp__semrush__overview_research(query="", database="us") +``` + +Korean market: `database="kr"`. + +## Strengths for this skill + +- **Auto-discovery** of organic competitors via `organic_research`. +- Cleanest **keyword overlap** computation across target + competitors. +- `trends_research` directly exposes period-over-period — required for threat scoring. + +## Not for this skill when + +- **Backlink-focused competitor comparison** — Ahrefs `site-explorer-organic-competitors` + `-backlinks-stats` is stronger. +- **Korean Naver competitor presence** — Semrush is Google-only. Use `our research naver *` + WebSearch. +- **SERP overlap spot-check** — `mcp__ourseo__check_serp` is cheaper. diff --git a/custom-skills/32-seo-crawl-budget/desktop/SKILL.md b/custom-skills/32-seo-crawl-budget/desktop/SKILL.md index ba1b903..aebe4a6 100644 --- a/custom-skills/32-seo-crawl-budget/desktop/SKILL.md +++ b/custom-skills/32-seo-crawl-budget/desktop/SKILL.md @@ -85,13 +85,75 @@ Save Korean-language report to SEO Audit Log database. | Found Date | Date | Analysis date (YYYY-MM-DD) | | Audit ID | Rich Text | Format: CRAWL-YYYYMMDD-NNN | -## Data Sources +## Data Source Selection -| Source | Purpose | -|--------|---------| -| `our-seo-agent` CLI | Future primary data source; use `--input` for pre-fetched JSON | -| Notion MCP | Save audit report to database | -| WebSearch | Current bot documentation and best practices | +Crawl-budget analysis is **primarily log-based** — the authoritative signal lives in server access logs that this skill's local Python scripts parse. API backends supplement that with crawled URL inventories, index status, and third-party site-audit views. Pick per data class. + +| Backend | Best for | Notes | +|---|---|---| +| **Server access logs** (via `scripts/log_parser.py` + `crawl_budget_analyzer.py`) | **Primary** — bot identification, request volume, status code distribution, waste detection, orphan pages | Requires actual server logs from the user (Nginx / Apache / CloudFront). No MCP substitute. | +| **OurSEO** (CLI + MCP) | **Default** for crawl-derived URL inventory, index status, redirect chains | CLI: `our collect crawl`, `our research google index`, `our audit tech`. MCP: `mcp__ourseo__crawl_website`, `mcp__ourseo__check_index`. Distributed crawl for large sites: `our collect distributed --workers N`. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Orphan detection, redirect chain analysis via Ahrefs site audit | `site-audit-issues`, `site-audit-page-explorer`, `site-audit-page-content`. Useful when an Ahrefs project already exists for the domain. | +| **Semrush MCP** (`mcp__semrush__*`) | Alternative site audit when Ahrefs project doesn't exist | `siteaudit_research` → `get_report_schema` → `execute_report`. | +| **GSC** (via `our research search-console`) | First-party Googlebot crawl stats (Coverage / Crawl Stats reports) | Required for ground-truth Googlebot behaviour — server logs show what hit the origin, GSC shows what Google considers crawled. | + +### 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. **Server access logs are available** → ALWAYS process them first (`log_parser.py` + `crawl_budget_analyzer.py`). They are the only source for actual bot behaviour at the origin. +4. **Sitemap vs. crawl comparison needed** → OurSEO `crawl_website` for URL inventory; cross-reference with logs. +5. **No logs available** → fall back to OurSEO crawl + GSC Coverage + Ahrefs/Semrush site audit. State this limitation explicitly in the report. +6. **Default**: server logs (when present) + **OurSEO crawl + index check** for URL inventory. +7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**Local log analysis (primary):** +```bash +python scripts/log_parser.py --log-file access.log --json +python scripts/log_parser.py --log-file access.log.gz --streaming --json +python scripts/log_parser.py --log-file access.log --bot googlebot --json + +python scripts/crawl_budget_analyzer.py --log-file access.log --sitemap https:///sitemap.xml --json +python scripts/crawl_budget_analyzer.py --log-file access.log --scope waste --json +python scripts/crawl_budget_analyzer.py --log-file access.log --scope orphans --json +python scripts/crawl_budget_analyzer.py --log-file access.log --scope bots --json +``` + +**OurSEO CLI (URL inventory + index check):** +```bash +our collect crawl https:// --max-pages 5000 +our collect distributed https:// --workers 8 --max-pages 50000 +our research google index --domain +our audit tech https:// +``` + +**OurSEO MCP (Claude Desktop):** +``` +mcp__ourseo__crawl_website(url="", max_pages=5000) +mcp__ourseo__check_index(domain="") +``` + +**GSC (first-party crawl stats):** +```bash +our research search-console queries --site sc-domain: --days 28 +# See also: GSC Coverage / Crawl Stats reports (UI-only for some sections). +``` + +**Ahrefs MCP (third-party site audit):** +``` +mcp__ahrefs__site-audit-projects() +mcp__ahrefs__site-audit-issues(project_id="") +mcp__ahrefs__site-audit-page-explorer(project_id="") +``` + +**Semrush MCP (alternative site audit):** +``` +mcp__semrush__siteaudit_research(query="", database="us") +``` + +Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like — and explicitly state whether server logs were available. ## Output Format diff --git a/custom-skills/32-seo-crawl-budget/desktop/skill.yaml b/custom-skills/32-seo-crawl-budget/desktop/skill.yaml index fb443ca..bff7e03 100644 --- a/custom-skills/32-seo-crawl-budget/desktop/skill.yaml +++ b/custom-skills/32-seo-crawl-budget/desktop/skill.yaml @@ -1,8 +1,16 @@ name: seo-crawl-budget description: | Crawl budget optimization and log analysis. Triggers: crawl budget, log analysis, bot crawling, Googlebot, crawl waste, orphan pages, crawl efficiency. + +# Allowed tools list every backend the skill can pull crawl/log data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. +# Note: crawl-budget analysis is primarily LOG-based (local files), not API-based. allowed-tools: - - mcp__ahrefs__* + - mcp__ourseo__* # default — crawl_website, check_index, audit_page + - mcp__ahrefs__* # site-audit-issues, site-audit-page-explorer (orphan, redirect chains) + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__semrush__* # siteaudit_research (alternate site audit) + - Bash # `our` CLI + log_parser.py + crawl_budget_analyzer.py - mcp__notion__* - WebSearch - WebFetch diff --git a/custom-skills/32-seo-crawl-budget/desktop/tools/ahrefs.md b/custom-skills/32-seo-crawl-budget/desktop/tools/ahrefs.md index dcb8687..4877b9c 100644 --- a/custom-skills/32-seo-crawl-budget/desktop/tools/ahrefs.md +++ b/custom-skills/32-seo-crawl-budget/desktop/tools/ahrefs.md @@ -1,17 +1,33 @@ -# Ahrefs MCP Tools +# Ahrefs MCP -## site-explorer-pages-history +In crawl-budget work, Ahrefs Site Audit surfaces **orphans, redirect chains, parameter URLs, and soft 404s** without running your own crawler. Useful when an Ahrefs Site Audit project already exists for the domain. -Get historical page data for a domain to compare indexed pages with crawled pages. +## Key endpoints + +- `site-audit-projects` — list available projects +- `site-audit-issues` — current crawl-budget-relevant issues (redirect chains, broken links, parameter URLs) +- `site-audit-page-explorer` — per-URL issue surfacing +- `site-audit-page-content` — content-level signals (thin content, duplicates) +- `site-explorer-pages-history` — page count over time vs. observed bot crawls + +## Example ``` -mcp__ahrefs__site-explorer-pages-history +mcp__ahrefs__site-audit-projects() +mcp__ahrefs__site-audit-issues(project_id="") +mcp__ahrefs__site-audit-page-explorer(project_id="") +mcp__ahrefs__site-explorer-pages-history(target="", history="weekly") ``` -**Parameters**: -- `target` (string, required): Domain or URL to analyze -- `date_from` (string): Start date (YYYY-MM-DD) -- `date_to` (string): End date (YYYY-MM-DD) -- `mode` (string): "domain", "prefix", "exact", "subdomains" +## Strengths for this skill -**Use case**: Compare Ahrefs indexed page counts with server log crawl data to identify indexing gaps and crawl budget inefficiencies. +- Pre-computed orphan detection and redirect-chain surfacing. +- Pages-history helps validate "are we crawling pages that don't exist anymore?" +- Cross-reference Ahrefs indexed-page count with server log crawl data to spot indexing gaps. + +## Not for this skill when + +- **Actual bot behaviour at the origin** — only server access logs show this. Use `scripts/log_parser.py` + `scripts/crawl_budget_analyzer.py`. +- **First-party Googlebot crawl stats** — GSC Coverage / Crawl Stats reports. +- **Naver / Daum / Kakao bot analysis** — Ahrefs covers Googlebot well but underrepresents Korean bots; rely on logs. +- **No Ahrefs project exists for the domain** — fall back to Semrush `siteaudit_research` or OurSEO crawl. diff --git a/custom-skills/32-seo-crawl-budget/desktop/tools/gsc.md b/custom-skills/32-seo-crawl-budget/desktop/tools/gsc.md new file mode 100644 index 0000000..1b1e4fa --- /dev/null +++ b/custom-skills/32-seo-crawl-budget/desktop/tools/gsc.md @@ -0,0 +1,45 @@ +# Google Search Console + +GSC's Coverage + Crawl Stats reports are the **first-party Googlebot view** — what Google considers crawled, indexed, or excluded. Pair with server access logs (the origin view) and OurSEO crawl (the published view) for a complete crawl-budget audit. + +## CLI access + +```bash +our research search-console queries --site sc-domain: --days 28 +our research search-console pages --site sc-domain: --days 28 +``` + +`sc-domain:` prefix for Domain-verified properties. + +Note: full **Coverage** and **Crawl Stats** report data is mostly UI-only in GSC — the API exposes performance (queries / pages) but limited crawl-stats fields. For exhaustive crawl analysis, export via the GSC UI and parse alongside log output. + +## Ahrefs GSC alternates + +When the site is connected as an Ahrefs project: + +``` +mcp__ahrefs__gsc-pages(project_id="") +mcp__ahrefs__gsc-pages-history(project_id="") +mcp__ahrefs__gsc-positions-history(project_id="") +``` + +## How GSC pairs with the rest + +| Source | Shows | +|---|---| +| Server logs | What hit the origin (bot behaviour at HTTP level) | +| OurSEO crawl | What URLs exist on the site today | +| Sitemap | What URLs the site claims to publish | +| **GSC** | **What Google considers indexed / excluded** | + +The intersection (and differences) reveal: +- **Crawled-not-indexed**: Google saw it, won't index — often thin content or duplicates. +- **Indexed-not-crawled-recently**: bot budget moved elsewhere. +- **Discovered-not-crawled**: Google knows about the URL but hasn't fetched it. + +## Not for this skill when + +- **Korean bots** (Yeti, Daumoa) — GSC is Google-only. +- **Bot User-Agent + IP analysis** — server logs. + +Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`. diff --git a/custom-skills/32-seo-crawl-budget/desktop/tools/ourseo.md b/custom-skills/32-seo-crawl-budget/desktop/tools/ourseo.md new file mode 100644 index 0000000..9505662 --- /dev/null +++ b/custom-skills/32-seo-crawl-budget/desktop/tools/ourseo.md @@ -0,0 +1,53 @@ +# OurSEO Agent (CLI + MCP) + +OurSEO contributes the **crawled URL inventory** (vs. server log observations), **index status check**, and **distributed crawl** for large sites. Pair with `scripts/log_parser.py` + `scripts/crawl_budget_analyzer.py` for the full crawl-budget picture. + +## CLI commands (Claude Code) + +```bash +# URL inventory crawl +our collect crawl https:// --max-pages 5000 +our collect crawl https:// --stealth --backend scrapy + +# Distributed crawl for large sites +our collect distributed https:// --workers 8 --max-pages 50000 + +# Index status (Google index coverage) +our research google index --domain + +# Technical audit (redirects, canonicals, etc.) +our audit tech https:// + +# MySQL batch analysis on crawl results +our analyze mysql-batch --session +our analyze mysql-batch --session --export issues --format excel +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__crawl_website(url="", max_pages=5000) +mcp__ourseo__check_index(domain="") +mcp__ourseo__audit_page(url="", audit_type="tech") +``` + +## Strengths for this skill + +- **Configurable crawler** — backend choice (aiohttp, Scrapy), stealth mode, resume support. +- **Distributed crawl** scales to 50K+ URL audits. +- **`check_index`** uses Google PSE to spot-check indexed-or-not per URL. +- Crawl output drops into MySQL workspace — easy to diff against log-derived URL sets. + +## How OurSEO pairs with log analysis + +1. **Logs** (`scripts/log_parser.py`) → what bots actually crawled at the origin +2. **OurSEO crawl** → what URLs exist on the site today +3. **Sitemap** → what URLs the site claims to publish +4. **GSC** → what Google considers indexed +5. **Diff all four** — orphan, ghost, and waste candidates emerge from set differences + +## Not for this skill when + +- **Actual bot User-Agent + frequency** — only logs show this. +- **Per-bot status distribution** — only logs. +- **First-party Googlebot crawl stats** — GSC. diff --git a/custom-skills/32-seo-crawl-budget/desktop/tools/semrush.md b/custom-skills/32-seo-crawl-budget/desktop/tools/semrush.md new file mode 100644 index 0000000..58912c7 --- /dev/null +++ b/custom-skills/32-seo-crawl-budget/desktop/tools/semrush.md @@ -0,0 +1,30 @@ +# Semrush MCP + +Alternative third-party site audit when no Ahrefs project exists for the domain. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key report + +- `siteaudit_research` — site-wide audit catching redirect chains, parameter URLs, thin content, broken links + +## Example + +``` +mcp__semrush__siteaudit_research(query="", database="us") +mcp__semrush__get_report_schema(report_id="") +mcp__semrush__execute_report(report_id="", params={...}) +``` + +## When Semrush is useful here + +- No Ahrefs Site Audit project — Semrush is the quickest alternative. +- User is already in Semrush context. +- Cross-vendor verification of orphan / redirect-chain counts. + +## Not for this skill when + +- **Actual bot behaviour at the origin** — server access logs (Nginx/Apache/CloudFront) only. +- **First-party Googlebot crawl stats** — GSC. +- **Korean bot analysis** (Yeti/Naver, Daumoa/Kakao) — Semrush underrepresents these. Use logs. +- **An Ahrefs project already exists** — prefer Ahrefs `site-audit-*` for historical continuity. diff --git a/custom-skills/33-seo-migration-planner/desktop/SKILL.md b/custom-skills/33-seo-migration-planner/desktop/SKILL.md index dfc7d26..0dd0363 100644 --- a/custom-skills/33-seo-migration-planner/desktop/SKILL.md +++ b/custom-skills/33-seo-migration-planner/desktop/SKILL.md @@ -24,30 +24,84 @@ Comprehensive site migration planning and post-migration monitoring for SEO: cra 10. **Recovery Estimation** - Estimate traffic recovery timeline based on migration type 11. **Alert Generation** - Flag traffic drops >20%, broken redirects, indexation loss -## MCP Tool Usage +## Data Source Selection -### SEO Data -``` -our-seo-agent CLI: Primary SEO baseline data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary migration data +Site migration spans **URL inventory** (crawl), **traffic/keyword/backlink baseline** (third-party + first-party), **redirect verification** (live HTTP), and **post-launch monitoring** (delta over time). Pick per data class — migration baselines often combine 3-4 backends. + +| Backend | Best for | Notes | +|---|---|---| +| **OurSEO** (CLI + MCP) | **Default** for URL inventory, on-page crawl, index status, technical audit, schema baseline | CLI: `our collect crawl`, `our collect distributed`, `our audit tech`, `our research google index`. MCP: `mcp__ourseo__crawl_website`, `mcp__ourseo__check_index`. Distributed crawler for sites >5K URLs. | +| **Firecrawl MCP** (`mcp__firecrawl__*`) | Large-scale URL inventory when OurSEO crawler is unavailable; per-URL redirect verification | `firecrawl_crawl` for full site map; `firecrawl_scrape` for redirect health on a specific URL. Useful when target is JS-heavy. | +| **Ahrefs MCP** (`mcp__ahrefs__*`) | Per-URL **traffic value + backlink count** baseline (risk scoring), top pages by traffic | `site-explorer-top-pages` (traffic per URL), `site-explorer-pages-by-backlinks`, `site-explorer-metrics`, `site-explorer-metrics-history`, `site-explorer-pages-history`. | +| **Semrush MCP** (`mcp__semrush__*`) | Per-URL organic traffic + keyword baseline | `organic_research`, `url_research`, `overview_research`. | +| **GSC** (via `our research search-console`) | **First-party impression baseline** — what Google rendered for each URL pre-migration | Required for ground-truth post-migration comparison. Use `pages` / `combined` reports. | +| **GA4** (via `our research ga4 *`) | First-party traffic baseline (sessions, conversions per URL) | Best for actual user-traffic baseline, complements GSC impressions. | +| **Perplexity MCP** (`mcp__perplexity__*`) | Research migration best practices, common pitfalls per migration type | Not a data source — guidance enrichment. | + +### 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. **URL inventory** → **OurSEO** crawler (CLI primary). Use Firecrawl only when OurSEO crawler can't handle the target (e.g., JS-heavy SPA). +4. **Per-URL traffic value for risk scoring** → Ahrefs `site-explorer-top-pages` is the strongest signal. Semrush `url_research` is the alternate. +5. **First-party baseline (REQUIRED for accurate post-migration diff)** → GSC + GA4 via `our` CLI. Always capture before migration date. +6. **Redirect verification** (post-launch) → Firecrawl `firecrawl_scrape` per URL OR `WebFetch` with redirect following. +7. **Default baseline stack**: OurSEO crawl + Ahrefs top-pages + GSC pages + GA4 traffic. Document every source. +8. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`. + +### Backend call patterns + +**OurSEO CLI (default — URL inventory + audit):** +```bash +our collect crawl https:// --max-pages 5000 +our collect distributed https:// --workers 8 --max-pages 50000 +our audit tech https:// +our research google index --domain ``` -### Firecrawl for URL Inventory & Redirect Verification +**OurSEO MCP (Claude Desktop):** ``` -mcp__firecrawl__firecrawl_crawl: Crawl entire site for URL inventory -mcp__firecrawl__firecrawl_scrape: Verify individual redirect health +mcp__ourseo__crawl_website(url="", max_pages=5000) +mcp__ourseo__check_index(domain="") ``` -### Notion for Report Storage +**Firecrawl (URL inventory + redirect verification):** ``` -mcp__notion__notion-create-pages: Save reports to SEO Audit Log +mcp__firecrawl__firecrawl_crawl(url="", limit=5000) +mcp__firecrawl__firecrawl_scrape(url="", formats=["markdown"]) ``` -### Perplexity for Migration Best Practices +**Ahrefs MCP (per-URL traffic + backlink baseline):** ``` -mcp__perplexity__search: Research migration best practices and common pitfalls +mcp__ahrefs__site-explorer-top-pages(target="", country="us", limit=500) +mcp__ahrefs__site-explorer-pages-by-backlinks(target="", limit=500) +mcp__ahrefs__site-explorer-metrics(target="") +mcp__ahrefs__site-explorer-metrics-history(target="", history="weekly") +mcp__ahrefs__site-explorer-pages-history(target="") ``` +**Semrush MCP (per-URL organic baseline):** +``` +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__url_research(query="", database="us") +mcp__semrush__overview_research(query="", database="us") +``` + +**First-party baseline (GSC + GA4):** +```bash +our research search-console pages --site sc-domain: --days 90 +our research search-console combined --site sc-domain: --days 90 +our research ga4 traffic --property-id +our research ga4 landing-pages --property-id +``` + +**Migration best practices (Perplexity):** +``` +mcp__perplexity__search(query="SEO migration best practices") +``` + +Always record the chosen data source(s) per metric in the **planning report's Baseline** section and re-use the same sources in **post-migration monitoring** so the diff is meaningful. + ## Workflow ### Pre-Migration Planning diff --git a/custom-skills/33-seo-migration-planner/desktop/skill.yaml b/custom-skills/33-seo-migration-planner/desktop/skill.yaml index 594a85f..c398f64 100644 --- a/custom-skills/33-seo-migration-planner/desktop/skill.yaml +++ b/custom-skills/33-seo-migration-planner/desktop/skill.yaml @@ -1,10 +1,18 @@ name: seo-migration-planner description: | SEO site migration planning and monitoring. Triggers: site migration, domain move, redirect mapping, platform migration, URL restructuring, 사이트 이전. + +# Allowed tools list every backend the skill can pull migration-baseline / monitoring data from. +# Per-task selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* - - mcp__firecrawl__* + - mcp__ourseo__* # default — crawl_website, audit_page, check_index + - mcp__firecrawl__* # large-scale URL inventory + redirect verification + - mcp__ahrefs__* # site-explorer-* for traffic-value + backlink baseline + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__semrush__* # organic_research, overview_research baseline + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our` CLI full surface - mcp__notion__* - - mcp__perplexity__* + - mcp__perplexity__* # research migration best practices - WebSearch - WebFetch diff --git a/custom-skills/33-seo-migration-planner/desktop/tools/gsc.md b/custom-skills/33-seo-migration-planner/desktop/tools/gsc.md new file mode 100644 index 0000000..20b02f9 --- /dev/null +++ b/custom-skills/33-seo-migration-planner/desktop/tools/gsc.md @@ -0,0 +1,54 @@ +# Google Search Console + +**Required** for migration baseline + post-launch monitoring. GSC is the only source for first-party impressions / clicks per URL pre-migration — modelled estimates from Semrush/Ahrefs cannot substitute. + +## CLI commands + +```bash +# Pre-migration baseline (PULL THIS BEFORE THE MIGRATION DATE) +our research search-console pages --site sc-domain: --days 90 +our research search-console combined --site sc-domain: --days 90 +our research search-console queries --site sc-domain: --days 90 + +# Post-migration (after new domain is verified in GSC) +our research search-console pages --site sc-domain: --days 28 +our research search-console combined --site sc-domain: --days 28 +``` + +`sc-domain:` prefix for Domain-verified properties; URL-prefix uses plain URL. + +## Baseline checklist + +Pre-migration, capture at minimum: + +| File | Source | Window | +|---|---|---| +| `gsc-pages-90d.json` | `our research search-console pages` | 90 days pre-migration | +| `gsc-combined-90d.json` | `our research search-console combined` | 90 days pre-migration | +| `gsc-queries-90d.json` | `our research search-console queries` | 90 days pre-migration | + +Store these alongside the OurSEO crawl baseline in the migration workspace. + +## Post-launch monitoring + +1. Wait for the new domain to verify in GSC (~24h after DNS propagation + sitemap submission). +2. Pull `pages` and `combined` on the new domain at +7d, +14d, +28d, +60d, +90d. +3. Diff against the baseline: which URLs lost impressions? Which queries dropped? +4. Cross-reference with OurSEO redirect verification — broken redirects are the most common cause of impression loss. + +## Ahrefs GSC alternates + +If both old and new domains are connected as Ahrefs projects: + +``` +mcp__ahrefs__gsc-pages(project_id="") +mcp__ahrefs__gsc-pages-history(project_id="") +mcp__ahrefs__gsc-performance-history(project_id="") +``` + +## Not for this skill when + +- **Pre-migration baseline before GSC verification** of the property — not possible. Get the domain verified well in advance. +- **Competitor migration analysis** — GSC is single-site. + +Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`. diff --git a/custom-skills/33-seo-migration-planner/desktop/tools/ourseo.md b/custom-skills/33-seo-migration-planner/desktop/tools/ourseo.md new file mode 100644 index 0000000..d47d5a4 --- /dev/null +++ b/custom-skills/33-seo-migration-planner/desktop/tools/ourseo.md @@ -0,0 +1,54 @@ +# OurSEO Agent (CLI + MCP) + +**Default** for URL inventory, on-page crawl, technical audit, and index-status baseline. Distributed crawler scales to large catalogs. + +## CLI commands (Claude Code) + +```bash +# URL inventory crawl (pre-migration) +our collect crawl https:// --max-pages 5000 +our collect distributed https:// --workers 8 --max-pages 50000 + +# Technical audit (catches redirect chains, canonical issues that affect migration) +our audit tech https:// + +# Index baseline +our research google index --domain + +# Schema baseline (preserve schema across migration) +our analyze mysql-batch --session --export missing-schema --format excel + +# Post-migration: re-run on new domain and diff +our collect crawl https:// --max-pages 5000 +our research google index --domain +our audit tech https:// +``` + +## MCP tools (Claude Desktop) + +``` +mcp__ourseo__crawl_website(url="", max_pages=5000) +mcp__ourseo__check_index(domain="") +mcp__ourseo__audit_page(url="", audit_type="tech") +``` + +## Strengths for this skill + +- **Distributed crawl** with URL-hash partitioning — handles catalogs >50K URLs. +- **Resume support** (`--resume`) — critical for multi-day baseline captures. +- **MySQL workspace** stores baseline crawl; post-migration diff is a SQL query against the same DB. +- **Index status spot-check** via `check_index` — finds URLs Google still has indexed from the old domain. + +## Pair with Firecrawl + +Firecrawl (`mcp__firecrawl__*`) is already in this skill's `allowed-tools`: + +- Use **OurSEO** as the default crawler for most sites. +- Switch to **Firecrawl** when the target is JS-heavy (React/Vue/Angular SPA) and OurSEO's HTTP-level crawler under-reports URLs. +- Use Firecrawl `firecrawl_scrape` for per-URL **redirect verification** post-launch (cheaper than re-crawling the whole site). + +## Not for this skill when + +- **Per-URL traffic value for risk scoring** — Ahrefs `site-explorer-top-pages` / Semrush `url_research`. +- **First-party impression baseline** — GSC `pages` (REQUIRED for accurate post-migration diff). +- **GA4 traffic baseline** — `our research ga4 *` (covered in OurSEO CLI but distinct from crawl path). diff --git a/custom-skills/33-seo-migration-planner/desktop/tools/semrush.md b/custom-skills/33-seo-migration-planner/desktop/tools/semrush.md new file mode 100644 index 0000000..c54849d --- /dev/null +++ b/custom-skills/33-seo-migration-planner/desktop/tools/semrush.md @@ -0,0 +1,39 @@ +# Semrush MCP + +For migrations, Semrush contributes **per-URL organic baseline**, **traffic value baseline**, and **cross-database comparison** when the migration involves a market change. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Key reports + +- `organic_research` — full organic keyword list for the domain (baseline) +- `url_research` — per-URL organic data (KPI for redirect risk scoring) +- `overview_research` — site-level traffic + visibility baseline +- `trends_research` — period-over-period traffic deltas (post-launch monitoring) + +## Example + +``` +# Pre-migration baseline +mcp__semrush__organic_research(query="", database="us") +mcp__semrush__url_research(query="", database="us") +mcp__semrush__overview_research(query="", database="us") + +# Post-migration monitoring +mcp__semrush__trends_research(query="", database="us") +``` + +Korean market: `database="kr"`. + +## Strengths for this skill + +- **`url_research`** gives per-URL organic data — useful input for redirect risk scoring alongside Ahrefs traffic value. +- **`trends_research`** simplifies post-migration period-over-period delta. +- Cross-database comparison helps validate visibility recovery across markets. + +## Not for this skill when + +- **URL inventory** — OurSEO `crawl_website` / Firecrawl `firecrawl_crawl`. +- **Backlink baseline** for risk scoring — Ahrefs `site-explorer-pages-by-backlinks`. +- **First-party impression baseline** — GSC `pages` / `combined` reports. +- **Redirect health checking post-launch** — Firecrawl `firecrawl_scrape` or WebFetch. diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/SKILL.md b/custom-skills/34-seo-reporting-dashboard/desktop/SKILL.md index 07ee585..2fbdf53 100644 --- a/custom-skills/34-seo-reporting-dashboard/desktop/SKILL.md +++ b/custom-skills/34-seo-reporting-dashboard/desktop/SKILL.md @@ -18,25 +18,84 @@ Aggregate outputs from all SEO skills (11-33) into stakeholder-ready executive r 2. **Interactive Dashboard** - Generate self-contained HTML dashboards with Chart.js visualizations including health gauge, traffic trends, keyword distribution, issue breakdown, and competitor radar 3. **Executive Reporting** - Korean-language executive summary generation with audience-specific detail levels (C-level, marketing team, technical team) and prioritized action items -## MCP Tool Usage +## Data Source Selection -### SEO Data -``` -our-seo-agent CLI: Primary data source (future); use --input for pre-fetched JSON -WebSearch / WebFetch: Supplementary live data +This skill is the **presentation layer** — it aggregates outputs from every other SEO skill (11-33). The Data Source Selection therefore happens **per section of the report**, mirroring the per-task defaults in the source skills. Two distinct flows: + +1. **Aggregating prior audits** → query Notion SEO Audit Log for stored skill outputs; trust the source each skill recorded. +2. **Pulling fresh metrics** → consult each underlying skill's Data Source Selection and apply the same per-task defaults here. + +### Per-section backend defaults + +| Report section | Default backend | Source skill | Notes | +|---|---|---|---| +| Health score header | Semrush `overview_research` + OurSEO `audit_page` | 25-kpi-framework | Combines multiple metrics — see KPI framework. | +| Organic traffic trend | Semrush `overview_research` / Ahrefs `site-explorer-metrics-history` | 25, 33 | Pick one and stay consistent across periods. | +| Keyword visibility | Semrush `tracking_research` or Ahrefs `rank-tracker-*` | 21-position-tracking | Use GSC if site is verified for first-party. | +| Backlinks / DR | Ahrefs `site-explorer-domain-rating` + `-backlinks-stats` | 22-link-building | Ahrefs default. | +| Technical health | OurSEO `audit_page` + `audit tech` | 12-seo-technical-audit | OurSEO default. | +| AI visibility / Brand Radar | Ahrefs `brand-radar-*` | 27-ai-visibility | Ahrefs-only. | +| SERP / Naver presence | OurSEO `check_serp` + `our research naver serp` | 20-serp-analysis | Korean override via Naver. | +| Knowledge Graph / Entity | OurSEO `search_knowledge_graph` | 28-knowledge-graph | OurSEO default. | +| First-party clicks/impressions | GSC via `our research search-console` | 15-seo-search-console | First-party — always preferred when available. | +| GA4 traffic + conversions | `our research ga4 *` | n/a | First-party — always preferred when available. | +| GBP local visibility | `our collect gbp *` + `our audit local` | 18-seo-local-audit | First-party — always preferred when available. | +| Competitor benchmarks | Semrush `organic_research` + Ahrefs `site-explorer-organic-competitors` | 31-seo-competitor-intel | Pair both for cross-check. | +| Industry context | Perplexity MCP | n/a | Narrative enrichment only — not metrics. | + +### How to pick + +1. **Aggregating mode** (querying Notion for prior audits): trust the source recorded in each prior audit. If sources conflict across audits for the same metric, surface the conflict explicitly in the report's "Sources" subsection. +2. **Fresh-pull mode**: apply each underlying skill's Data Source Selection. Don't re-decide here — defer to the source skill. +3. **Consistency over completeness**: if the prior reporting period used Semrush for traffic value, use Semrush this period too. Switching mid-stream breaks every period-over-period chart. +4. **First-party first**: where GSC / GA4 / GBP are available, prefer them over modelled estimates. + +### Reporting rule + +Every dashboard's **Health Score Overview** AND **executive report Sources subsection** MUST list the data source per section. Example: + +```markdown +### Sources +- Organic traffic: Semrush overview_research (database=us) +- Keyword visibility: Ahrefs rank-tracker-overview (project=) +- Backlinks / DR: Ahrefs site-explorer-domain-rating +- Technical health: OurSEO audit_page (latest crawl 2026-05-14) +- AI visibility: Ahrefs brand-radar-sov-overview (brand=) +- GSC: 28-day window, 2026-04-16 → 2026-05-14 +- GA4 property: +- GBP profile: +- Industry context: Perplexity (research timestamp 2026-05-14) ``` -### Notion for Reading Past Audits and Writing Reports +### Aggregation flow + +1. **Identify scope**: target domain + date range + audience (C-level / marketing / technical). +2. **Query Notion SEO Audit Log** for the domain — pull all past audits via `mcp__notion__*`. +3. **For each section needed**, decide aggregate vs. fresh-pull: + - If a prior audit covers it and is recent enough → aggregate from Notion entry. + - If stale or missing → pull fresh from the per-section default backend above. +4. **Normalize** into the unified report structure. +5. **Compute health score** using KPI framework weights (see skill 25). +6. **Render** HTML dashboard + Korean executive markdown. +7. **Push** final report back to Notion + optionally Slack. + +### Backend call patterns + +**Notion (prior audit aggregation):** ``` -mcp__notion__*: Query SEO Audit Log database for past audit entries -mcp__notion__*: Save dashboard reports and executive summaries to Notion +mcp__notion__notion-query-database-view(database_id="2c8581e5-8a1e-8035-880b-e38cefc2f3ef", filters={"Site": ""}) +mcp__notion__notion-fetch(page_id="") ``` -### Perplexity for Context +**Fresh pulls** — see each skill's Data Source Selection (11-33). + +**Perplexity (industry context):** ``` -mcp__perplexity__*: Enrich reports with industry benchmarks and competitor context +mcp__perplexity__search(query=" SEO benchmarks 2026") ``` +Reporting is downstream of every other SEO skill — keep the source attribution rigorous or the dashboard becomes meaningless. + ## Workflow ### Dashboard Generation diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/skill.yaml b/custom-skills/34-seo-reporting-dashboard/desktop/skill.yaml index 2367531..b11cc49 100644 --- a/custom-skills/34-seo-reporting-dashboard/desktop/skill.yaml +++ b/custom-skills/34-seo-reporting-dashboard/desktop/skill.yaml @@ -1,9 +1,17 @@ name: seo-reporting-dashboard description: | SEO reporting dashboard and executive report generation. Triggers: SEO report, dashboard, executive summary, 보고서, 대시보드. + +# Reporting dashboard aggregates from ALL backends — every SEO source can feed a report section. +# Per-section selection happens in SKILL.md > Data Source Selection — NOT here. allowed-tools: - - mcp__ahrefs__* - - mcp__notion__* - - mcp__perplexity__* + - mcp__semrush__* # traffic + organic + visibility data + - mcp__ahrefs__* # backlinks + DR + brand-radar + web-analytics + - mcp__claude_ai_Ahrefs__* # Ahrefs (Claude.ai namespace) + - mcp__ourseo__* # crawl + audit + KG + check_serp + check_index + - mcp__dfs-mcp__* # DataForSEO MCP fallback + - Bash # `our` CLI: full surface (GA4, GSC, GBP, etc.) + - mcp__notion__* # query past audits + push final reports + - mcp__perplexity__* # industry benchmarks + context enrichment - WebSearch - WebFetch diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/tools/ahrefs.md b/custom-skills/34-seo-reporting-dashboard/desktop/tools/ahrefs.md index c605974..68dd1e4 100644 --- a/custom-skills/34-seo-reporting-dashboard/desktop/tools/ahrefs.md +++ b/custom-skills/34-seo-reporting-dashboard/desktop/tools/ahrefs.md @@ -1,20 +1,51 @@ -# Ahrefs +# Ahrefs MCP -Tools used for pulling fresh SEO data into the reporting dashboard. +In the reporting dashboard, Ahrefs is the source for **backlinks**, **DR + history**, **traffic-value alternate**, **Brand Radar AI visibility**, and **per-country traffic** breakouts. -## Tools Used +Namespace: `mcp__ahrefs__*` / `mcp__claude_ai_Ahrefs__*`. -| Tool | Purpose | -|------|---------| -| `mcp__ahrefs__site-explorer-metrics` | Current organic metrics snapshot (traffic, keywords, DR) | -| `mcp__ahrefs__site-explorer-metrics-history` | Historical metrics for trend charts and period comparison | +## Tools used in dashboard sections -## Usage +| Section | Endpoint | +|---|---| +| Backlinks / DR | `site-explorer-domain-rating`, `site-explorer-backlinks-stats` | +| DR trend chart | `site-explorer-domain-rating-history` | +| Refdomains trend chart | `site-explorer-refdomains-history` | +| Traffic / visibility snapshot (alternate) | `site-explorer-metrics` | +| Traffic / visibility trend (alternate) | `site-explorer-metrics-history` | +| AI search visibility / SOV | `brand-radar-sov-overview`, `brand-radar-sov-history` | +| Cited pages in AI answers | `brand-radar-cited-pages`, `brand-radar-cited-domains` | +| Per-country traffic distribution | `web-analytics-countries`, `site-explorer-metrics-by-country` | +| First-party clicks/impressions (if connected) | `gsc-performance-history`, `gsc-pages-history` | -These tools are called when the dashboard needs fresh data beyond what is available from cached skill outputs. The aggregator first checks local JSON files and Notion audit log entries, then optionally pulls current data from Ahrefs to supplement the report. +## Example -## Notes +``` +mcp__ahrefs__site-explorer-metrics(target="") +mcp__ahrefs__site-explorer-metrics-history(target="", history="weekly") +mcp__ahrefs__brand-radar-sov-overview(brand="") +mcp__ahrefs__web-analytics-countries(domain="") +``` -- Ahrefs data has approximately 24-hour freshness lag -- Traffic value from Ahrefs is in cents; divide by 100 for USD -- Historical data availability depends on Ahrefs subscription tier +## Strengths for the dashboard + +- **Pre-computed trend series** — saves the dashboard from synthesizing trends from point-in-time pulls. +- **Brand Radar is Ahrefs-only** — required for AI-visibility report sections. +- Traffic value in **USD cents** — divide by 100 for USD when rendering. + +## Reporting rule + +Whenever an Ahrefs endpoint feeds a section, list it in the report's **Sources** subsection (e.g., `Backlinks / DR: Ahrefs site-explorer-domain-rating`). + +## Not for this skill when + +- **First-party clicks / impressions / CTR** — prefer GSC over `gsc-*` Ahrefs alternates unless Ahrefs project is already configured. +- **Technical health section** — OurSEO `audit_page` / `audit tech`. +- **GA4 sessions / conversions** — `our research ga4 *`. +- **GBP local KPIs** — `our collect gbp *` / `our audit local`. + +Notes: +- Ahrefs data has ~24h freshness lag. +- Historical data window depends on Ahrefs subscription tier — fall back to point-in-time + manual snapshot history if needed. + +Reference: `mcp__ahrefs__doc` once per session. diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/tools/gsc.md b/custom-skills/34-seo-reporting-dashboard/desktop/tools/gsc.md new file mode 100644 index 0000000..d31c75d --- /dev/null +++ b/custom-skills/34-seo-reporting-dashboard/desktop/tools/gsc.md @@ -0,0 +1,49 @@ +# Google Search Console + +GSC is the **first-party data source** for clicks / impressions / CTR / position in the reporting dashboard. Every other source for these metrics is modelled — when GSC is available, it is the authoritative source and should drive the corresponding dashboard sections. + +## Tools used in dashboard sections + +| Section | Source | +|---|---| +| First-party clicks trend | `our research search-console pages --days 90` | +| First-party impressions trend | `our research search-console pages --days 90` | +| Average CTR | computed from `pages` or `queries` | +| Top branded queries | filter `queries` output | +| Top non-branded queries | filter `queries` output | +| Cannibalization flags | `our research search-console combined --days 90` | + +## CLI + +```bash +our research search-console queries --site sc-domain: --days 28 +our research search-console pages --site sc-domain: --days 90 +our research search-console combined --site sc-domain: --days 90 +``` + +`sc-domain:` prefix for Domain-verified properties. + +## Ahrefs GSC alternates (when project connected) + +``` +mcp__ahrefs__gsc-performance-history(project_id="") +mcp__ahrefs__gsc-pages-history(project_id="") +mcp__ahrefs__gsc-positions-history(project_id="") +mcp__ahrefs__gsc-ctr-by-position(project_id="") +mcp__ahrefs__gsc-anonymous-queries(project_id="") +``` + +## Reporting rule + +Whenever GSC feeds a section, list it in the report's **Sources** subsection with the date window (e.g., `Clicks / Impressions: GSC (28d, 2026-04-16 → 2026-05-14)`). + +Use **consistent windows** across reporting periods — switching from 28d to 90d silently changes every CTR number on the page. + +## Not for this skill when + +- **Competitor performance sections** — GSC is single-site. +- **Modelled traffic-value (USD)** — Semrush `overview_research`. +- **Net-new keyword discovery sections** — Semrush / Ahrefs. +- **GA4 sessions / conversions** — `our research ga4 *`. + +Gotcha: `our-claude-skills/custom-skills/15-seo-search-console/code/gotcha/gsc-cli-integration.md`. diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/tools/ourseo.md b/custom-skills/34-seo-reporting-dashboard/desktop/tools/ourseo.md new file mode 100644 index 0000000..6562341 --- /dev/null +++ b/custom-skills/34-seo-reporting-dashboard/desktop/tools/ourseo.md @@ -0,0 +1,48 @@ +# OurSEO Agent (CLI + MCP) + +In the reporting dashboard, OurSEO owns the **technical health**, **indexed pages**, **first-party (GSC / GA4 / GBP)**, **schema coverage**, and **Korean engine** sections. + +## Tools used in dashboard sections + +| Section | Command / tool | +|---|---| +| Technical health score | `our audit tech https://` | +| Crawl errors / issues | `our analyze mysql-batch --session ` | +| Indexed page count | `our research google index --domain ` / `mcp__ourseo__check_index` | +| Schema coverage | `our analyze mysql-batch --session --export missing-schema` | +| First-party clicks/impressions | `our research search-console queries --site sc-domain: --days 28` | +| GA4 sessions / channels | `our research ga4 traffic --property-id `, `our research ga4 channels` | +| GBP visibility | `our collect gbp reviews/locations`, `our audit local` | +| Korean SERP / Naver visibility | `our research naver serp ""` | +| Knowledge Graph entity status | `our research kg lookup ""` | +| Content freshness | `our collect crawl https://` | +| SERP spot-check | `mcp__ourseo__check_serp(...)` | + +## MCP tools (Claude Desktop equivalents) + +``` +mcp__ourseo__check_index(domain="") +mcp__ourseo__audit_page(url="", audit_type="tech") +mcp__ourseo__check_serp(keyword="", domain="", country="kr") +mcp__ourseo__search_knowledge_graph(query="") +``` + +## Strengths for the dashboard + +- **First-party data routed through one CLI** — GSC + GA4 + GBP all in `our research *`. +- **MySQL workspace** — period-over-period diff is a SQL query, not a re-pull. +- Only path for **Korean engine** + **Knowledge Graph entity** sections. +- **Audit ID format** convention (KW-, RANK-, COMP-, etc.) baked into the CLI — keeps Notion Audit Log entries consistent. + +## Reporting rule + +Whenever OurSEO feeds a section, list it in the report's **Sources** subsection with the specific command + date window (e.g., `Technical health: OurSEO audit tech (crawl 2026-05-14)`, `GSC: 28-day window 2026-04-16 → 2026-05-14`). + +## Not for this skill when + +- **Modelled traffic / traffic value** — Semrush `overview_research`. +- **Backlinks / DR** — Ahrefs `site-explorer-domain-rating`. +- **AI visibility / Brand Radar** — Ahrefs `brand-radar-*`. +- **Multi-vendor visibility benchmarks** — pair with Semrush / Ahrefs. + +Cross-reference: see skill 25 (KPI framework) for the per-metric backend map used to feed this dashboard. diff --git a/custom-skills/34-seo-reporting-dashboard/desktop/tools/semrush.md b/custom-skills/34-seo-reporting-dashboard/desktop/tools/semrush.md new file mode 100644 index 0000000..d9bb28c --- /dev/null +++ b/custom-skills/34-seo-reporting-dashboard/desktop/tools/semrush.md @@ -0,0 +1,43 @@ +# Semrush MCP + +In the reporting dashboard, Semrush is the **default for organic traffic, traffic value, visibility, and period-over-period traffic deltas**. + +Call pattern: discovery → `get_report_schema` → `execute_report`. + +## Tools used in dashboard sections + +| Section | Report | +|---|---| +| Health score header (organic traffic) | `overview_research` | +| Traffic value (USD) | `overview_research` | +| Visibility / ranking distribution | `tracking_research`, `organic_research` | +| Period-over-period delta | `trends_research` | +| Competitor benchmark cards | `organic_research` (per competitor) | +| Authority Score (DR alternate) | `backlink_research` | + +## Example + +``` +mcp__semrush__overview_research(query="", database="us") +mcp__semrush__trends_research(query="", database="us") +mcp__semrush__organic_research(query="", database="us") +``` + +Korean market: `database="kr"`. Always state the database used in the dashboard's Sources subsection. + +## Strengths for the dashboard + +- Cleanest combined traffic + traffic-value + visibility snapshot per domain. +- `trends_research` returns period-over-period directly — feeds delta arrows in the executive summary. +- Cross-database calls enable multi-market dashboards without per-market vendor switching. + +## Reporting rule + +Whenever Semrush feeds a section, list it in the report's **Sources** subsection (e.g., `Organic traffic: Semrush overview_research (database=us)`). Keep `database` value visible — it changes the numbers. + +## Not for this skill when + +- **Backlinks / DR section** — Ahrefs. +- **AI visibility / Brand Radar section** — Ahrefs. +- **First-party clicks / impressions / CTR** — GSC. +- **GA4 / GBP / technical-health sections** — OurSEO CLI.