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

73
custom-skills/25-seo-kpi-framework/desktop/SKILL.md
View File

@@ -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="<domain>", database="us")
mcp__semrush__organic_research(query="<domain>", database="us")
mcp__semrush__tracking_research(query="<keyword>", 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="<domain>")
mcp__ahrefs__site-explorer-domain-rating(target="<domain>")
mcp__ahrefs__site-explorer-domain-rating-history(target="<domain>", history="weekly")
mcp__ahrefs__site-explorer-backlinks-stats(target="<domain>")
```
**OurSEO (technical + indexation + first-party):**
```bash
our audit tech https://<domain>
our analyze mysql-batch --session <id>
our research google index --domain <domain>
our research search-console queries --site sc-domain:<domain> --days 28
our research ga4 traffic --property-id <id>
our audit local https://<domain> --gbp-profile <client>
```
**OurSEO MCP (Claude Desktop alternate):**
```
mcp__ourseo__check_index(domain="<domain>")
mcp__ourseo__audit_page(url="<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

10
custom-skills/25-seo-kpi-framework/desktop/skill.yaml
View File

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

38
custom-skills/25-seo-kpi-framework/desktop/tools/ahrefs.md
View File

@@ -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="<domain>")
mcp__ahrefs__site-explorer-metrics-history(target="<domain>", history="weekly")
mcp__ahrefs__site-explorer-domain-rating-history(target="<domain>", 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.

56
custom-skills/25-seo-kpi-framework/desktop/tools/gsc.md Normal file
View File

@@ -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:<domain> --days 28
# Top pages (KPI: clicks, impressions per URL)
our research search-console pages --site sc-domain:<domain> --days 28
# Query × page combined (KPI: cannibalization, content efficiency)
our research search-console combined --site sc-domain:<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="<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>")
```
## 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`.

38
custom-skills/25-seo-kpi-framework/desktop/tools/ourseo.md Normal file
View File

@@ -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://<site>` |
| Crawl efficiency / errors | `our analyze mysql-batch --session <id>` |
| Indexed pages | `our research google index --domain <site>` / `mcp__ourseo__check_index` |
| First-party clicks/impressions/CTR | `our research search-console queries --site sc-domain:<site> --days 28` |
| GA4 sessions / traffic / channel | `our research ga4 traffic --property-id <id>` |
| GA4 landing pages | `our research ga4 landing-pages --property-id <id>` |
| GA4 channel mix | `our research ga4 channels --property-id <id>` |
| GBP visibility / reviews / posts | `our collect gbp reviews/locations/posts ...`, `our audit local` |
| Content freshness | `our collect crawl https://<site>` (extracts last-modified) |
| Schema coverage | `our analyze mysql-batch --session <id> --export missing-schema` |
## MCP equivalents (Claude Desktop)
```
mcp__ourseo__check_index(domain="<site>")
mcp__ourseo__audit_page(url="<url>", audit_type="tech")
mcp__ourseo__crawl_website(url="<site>", 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.

40
custom-skills/25-seo-kpi-framework/desktop/tools/semrush.md Normal file
View File

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