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

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

Browse Source 
Replaces single-vendor (Ahrefs-only) tool defaults with a per-task
backend menu across all 14 SEO skills. Each skill now lists every
capable MCP in allowed-tools and documents how to pick between
Semrush, Ahrefs, OurSEO Agent (CLI + MCP), DataForSEO, and GSC
in its SKILL.md Data Source Selection section.

Tool stubs (~40 new files) populated per skill with capability
deltas, call patterns, and explicit "not for this skill when"
callouts so the menu is self-correcting.

Skills affected: 19-keyword-strategy, 20-serp-analysis,
21-position-tracking, 22-link-building, 23-content-strategy,
24-ecommerce, 25-kpi-framework, 26-international, 27-ai-visibility,
28-knowledge-graph, 31-competitor-intel, 32-crawl-budget,
33-migration-planner, 34-reporting-dashboard.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Yim
2026-05-14 03:15:32 +09:00
committed by GitHub
parent 1ca84f67ed
commit e527fb4b0f
71 changed files with 2647 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
custom-skills/34-seo-reporting-dashboard/desktop/tools/ahrefs.md
View File

@@ -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="<domain>")
mcp__ahrefs__site-explorer-metrics-history(target="<domain>", history="weekly")
mcp__ahrefs__brand-radar-sov-overview(brand="<brand>")
mcp__ahrefs__web-analytics-countries(domain="<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.

49
custom-skills/34-seo-reporting-dashboard/desktop/tools/gsc.md Normal file
View File

@@ -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:<domain> --days 28
our research search-console pages --site sc-domain:<domain> --days 90
our research search-console combined --site sc-domain:<domain> --days 90
```
`sc-domain:` prefix for Domain-verified properties.
## Ahrefs GSC alternates (when project connected)
```
mcp__ahrefs__gsc-performance-history(project_id="<id>")
mcp__ahrefs__gsc-pages-history(project_id="<id>")
mcp__ahrefs__gsc-positions-history(project_id="<id>")
mcp__ahrefs__gsc-ctr-by-position(project_id="<id>")
mcp__ahrefs__gsc-anonymous-queries(project_id="<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`.

48
custom-skills/34-seo-reporting-dashboard/desktop/tools/ourseo.md Normal file
View File

@@ -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://<site>` |
| Crawl errors / issues | `our analyze mysql-batch --session <id>` |
| Indexed page count | `our research google index --domain <site>` / `mcp__ourseo__check_index` |
| Schema coverage | `our analyze mysql-batch --session <id> --export missing-schema` |
| First-party clicks/impressions | `our research search-console queries --site sc-domain:<site> --days 28` |
| GA4 sessions / channels | `our research ga4 traffic --property-id <id>`, `our research ga4 channels` |
| GBP visibility | `our collect gbp reviews/locations`, `our audit local` |
| Korean SERP / Naver visibility | `our research naver serp "<keyword>"` |
| Knowledge Graph entity status | `our research kg lookup "<entity>"` |
| Content freshness | `our collect crawl https://<site>` |
| SERP spot-check | `mcp__ourseo__check_serp(...)` |
## MCP tools (Claude Desktop equivalents)
```
mcp__ourseo__check_index(domain="<site>")
mcp__ourseo__audit_page(url="<url>", audit_type="tech")
mcp__ourseo__check_serp(keyword="<kw>", domain="<site>", country="kr")
mcp__ourseo__search_knowledge_graph(query="<entity>")
```
## 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.

43
custom-skills/34-seo-reporting-dashboard/desktop/tools/semrush.md Normal file
View File

@@ -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="<domain>", database="us")
mcp__semrush__trends_research(query="<domain>", database="us")
mcp__semrush__organic_research(query="<competitor>", 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.