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

79
custom-skills/34-seo-reporting-dashboard/desktop/SKILL.md
View File

@@ -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=<id>)
- 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=<name>)
- GSC: 28-day window, 2026-04-16 → 2026-05-14
- GA4 property: <id>
- GBP profile: <client>
- 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": "<domain>"})
mcp__notion__notion-fetch(page_id="<audit 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="<industry> SEO benchmarks 2026")
```
Reporting is downstream of every other SEO skill — keep the source attribution rigorous or the dashboard becomes meaningless.
## Workflow
### Dashboard Generation

14
custom-skills/34-seo-reporting-dashboard/desktop/skill.yaml
View File

@@ -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

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.