Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(backlinks): enforce the Common-Crawl-only no-score rule

Sergio37bd5dbbf83b
diff --git a/scripts/validate_backlink_report.py b/scripts/validate_backlink_report.py
index f0cafb5..179acd1 100644
--- a/scripts/validate_backlink_report.py
+++ b/scripts/validate_backlink_report.py
@@ -234,6 +234,102 @@ def validate_health_score(scoring_factors: dict) -> list:
return issues
+# Sources that can support a numeric backlink health score. Common Crawl is
+# deliberately absent: it provides rank/presence signals only, not the
+# referring-domain quality, anchor, or toxicity data a score implies.
+SCOREABLE_SOURCES = ("moz_data", "bing_data", "dataforseo_data")
+
+# Finding sources that mean "we did not measure this".
+UNMEASURED_SOURCES = ("not-assessed", "not_assessed")
+
+
+def _is_numeric_score(value) -> bool:
+ """True when value is a real number (bool excluded) or a numeric string."""
+ if value is None or isinstance(value, bool):
+ return False
+ if isinstance(value, (int, float)):
+ return True
+ if isinstance(value, str):
+ try:
+ float(value.strip())
+ except (TypeError, ValueError):
+ return False
+ return True
+ return False
+
+
+def _scoreable_sources_present(report_data: dict) -> list:
+ """Return the scoreable sources that actually carry data in this report."""
+ present = []
+ for key in SCOREABLE_SOURCES:
+ value = report_data.get(key)
+ if isinstance(value, dict):
+ if value and not value.get("error"):
+ present.append(key)
+ elif value:
+ present.append(key)
+ return present
+
+
+def validate_source_score_consistency(report_data: dict) -> list:
+ """Enforce: never emit a numeric score for data that was not measured.
+
+ Two failure modes, both observed in real audits despite the instruction
+ already existing in the skill:
+
+ 1. Common Crawl is the only source available, but a numeric health score is
+ still produced.
+ 2. A finding is marked `source: not-assessed` yet carries a score.
+ """
+ issues = []
+
+ scoring_factors = report_data.get("scoring_factors") or {}
+ score = scoring_factors.get("score") if isinstance(scoring_factors, dict) else None
+
+ scoreable = _scoreable_sources_present(report_data)
+ has_cc = bool(report_data.get("cc_data"))
+
+ if _is_numeric_score(score) and not scoreable:
+ detail = (
+ "Common Crawl was the only source available"
+ if has_cc else "no backlink data source was available"
+ )
+ issues.append({
+ "severity": "error",
+ "field": "health_score",
+ "message": (
+ f"Numeric score ({score}) produced when {detail}. Common Crawl "
+ "supplies rank/presence signals only and MUST NOT be scored. "
+ "Report 'Not Assessed' with no numeric value."
+ ),
+ "fix": "Set the score to null and report Not Assessed.",
+ })
+
+ findings = report_data.get("findings")
+ if isinstance(findings, list):
+ for i, finding in enumerate(findings):
+ if not isinstance(finding, dict):
+ continue
+ source = str(finding.get("source", "")).strip().lower()
+ if source not in UNMEASURED_SOURCES:
+ continue
+ for field in ("score", "value", "health_score"):
+ if _is_numeric_score(finding.get(field)):
+ issues.append({
+ "severity": "error",
+ "field": f"findings[{i}].{field}",
+ "message": (
+ f"Finding '{finding.get('title', 'untitled')}' is "
+ f"source: not-assessed but carries a numeric "
+ f"{field} ({finding[field]}). A not-assessed finding "
+ "MUST NOT be scored."
+ ),
+ "fix": f"Omit {field} or set it to null.",
+ })
+
+ return issues
+
+
def validate_report(report_data: dict) -> dict:
"""
Run all validations on a backlink report.
@@ -266,6 +362,10 @@ def validate_report(report_data: dict) -> dict:
if report_data.get("scoring_factors"):
all_issues.extend(validate_health_score(report_data["scoring_factors"]))
+ # Always run: this gate must fire even when the agent supplies no
+ # scoring_factors block at all.
+ all_issues.extend(validate_source_score_consistency(report_data))
+
# Classify
errors = [i for i in all_issues if i["severity"] == "error"]
warnings = [i for i in all_issues if i["severity"] == "warning"]
@@ -288,6 +388,7 @@ def validate_report(report_data: dict) -> dict:
"checks_run": [
"schema_claims", "verification_results", "h1_claims",
"cc_claims", "reciprocal_links", "health_score",
+ "source_score_consistency",
],
},
}
diff --git a/skills/seo-backlinks/SKILL.md b/skills/seo-backlinks/SKILL.md
index d5e1dd9..9cf5f8f 100644
--- a/skills/seo-backlinks/SKILL.md
+++ b/skills/seo-backlinks/SKILL.md
@@ -184,9 +184,40 @@ Calculate a 0-100 score. When mixing sources, apply confidence weighting:
Show individual factor scores that ARE available with their source and confidence.
Recommend: "Configure Moz API (free) for a scoreable profile. Run `/seo backlinks setup`"
-When only CC is available, do not produce a numeric score; report low-confidence rank/presence data only.
-A numeric score with fewer than 4 data sources is **misleading**, it implies poor health when
-the reality is we simply lack data.
+### MUST NOT: score what you did not measure
+
+**When Common Crawl is the only available source, you MUST NOT produce a numeric
+score of any kind** -- not a health score, not a per-factor score, not an
+"approximate" or "estimated" figure. Common Crawl supplies rank and presence
+signals only. Report low-confidence rank/presence data and the literal string
+`Not Assessed` in place of every number.
+
+**A finding written with `source: not-assessed` MUST NOT carry a numeric score.**
+
+A numeric score with fewer than 4 data sources is **misleading**: it implies poor
+health when the reality is that we simply lack data.
+
+### Validation gate (required, not optional)
+
+This rule has been stated in this skill before and was violated anyway, so it is
+now checkable. **Before writing any backlink output, run the validator:**
+
+```bash
+claude-seo run validate_backlink_report.py --report <report>.json --json
+```
+
+Pass the sources you actually collected (`cc_data`, `moz_data`, `bing_data`,
+`dataforseo_data`, `scoring_factors`, and your `findings` list). The
+`source_score_consistency` check fails the report with `status: FAIL` when:
+
+- a numeric score is present but no scoreable source (Moz, Bing, or DataForSEO)
+ supplied data -- i.e. the Common-Crawl-only case, and
+- any finding marked `source: not-assessed` carries a numeric `score`, `value`,
+ or `health_score`.
+
+**If the validator returns `status: FAIL`, do not present the report.** Fix the
+findings -- replace the offending numbers with `Not Assessed` -- and re-run until
+it passes.
## Output Format
diff --git a/tests/test_backlink_score_gate.py b/tests/test_backlink_score_gate.py
new file mode 100644
index 0000000..c10e071
--- /dev/null
+++ b/tests/test_backlink_score_gate.py
@@ -0,0 +1,110 @@
+"""Backlink scoring: never emit a number for data that was not measured.
+
+The rule already existed as prose in the skill and was violated in a real audit
+anyway. These tests pin it to something checkable.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+_SCRIPTS = str(REPO_ROOT / "scripts")
+if _SCRIPTS not in sys.path:
+ sys.path.insert(0, _SCRIPTS)
+
+import validate_backlink_report as vbr # noqa: E402
+
+
+# ─── Backlink score gating ───────────────────────────────────────────────────
+
+BACKLINKS_SKILL = REPO_ROOT / "skills" / "seo-backlinks" / "SKILL.md"
+
+
+def test_backlinks_skill_states_must_not_and_names_the_validator() -> None:
+ text = BACKLINKS_SKILL.read_text(encoding="utf-8")
+ assert "MUST NOT" in text
+ assert "validate_backlink_report.py" in text
+ assert "status: FAIL" in text
+
+
+def test_common_crawl_only_numeric_score_fails_validation() -> None:
+ result = vbr.validate_report({
+ "cc_data": {"rank": 1234, "in_degree": 57},
+ "scoring_factors": {"score": 42, "factors_with_data": 2, "total_factors": 7},
+ })
+
+ assert result["status"] == "FAIL"
+ messages = [i["message"] for i in result["data"]["issues"]]
+ assert any("Common Crawl was the only source available" in m for m in messages)
+
+
+def test_common_crawl_only_without_a_score_passes() -> None:
+ """Not Assessed is the correct output, and it must validate cleanly."""
+ result = vbr.validate_report({
+ "cc_data": {"rank": 1234, "in_degree": 57},
+ "scoring_factors": {"score": None, "factors_with_data": 2, "total_factors": 7},
+ "findings": [
+ {"title": "Backlink profile", "source": "not-assessed", "score": None},
+ ],
+ })
+
+ errors = [i for i in result["data"]["issues"] if i["severity"] == "error"]
+ assert errors == []
+
+
+def test_not_assessed_finding_with_a_numeric_score_fails_validation() -> None:
+ result = vbr.validate_report({
+ "moz_data": {"domain_authority": 30},
+ "findings": [
+ {"title": "Referring domain quality", "source": "not-assessed", "score": 55},
+ ],
+ })
+
+ assert result["status"] == "FAIL"
+ messages = [i["message"] for i in result["data"]["issues"]]
+ assert any("MUST NOT be scored" in m for m in messages)
+
+
+def test_numeric_score_string_is_still_caught() -> None:
+ """A score serialised as a string is the same misleading number."""
+ result = vbr.validate_report({
+ "cc_data": {"rank": 1},
+ "scoring_factors": {"score": "42"},
+ })
+ assert result["status"] == "FAIL"
+
+
+def test_score_is_allowed_once_a_scoreable_source_has_data() -> None:
+ result = vbr.validate_report({
+ "cc_data": {"rank": 1},
+ "moz_data": {"domain_authority": 41},
+ "scoring_factors": {"score": 68, "factors_with_data": 5, "total_factors": 7},
+ })
+
+ errors = [i for i in result["data"]["issues"] if i["severity"] == "error"]
+ assert errors == []
+
+
+def test_errored_source_does_not_count_as_available() -> None:
+ """A Moz call that failed must not unlock scoring."""
+ result = vbr.validate_report({
+ "cc_data": {"rank": 1},
+ "moz_data": {"error": "401 unauthorized"},
+ "scoring_factors": {"score": 68},
+ })
+
+ assert result["status"] == "FAIL"
+
+
+def test_source_score_consistency_runs_without_a_scoring_factors_block() -> None:
+ """The gate must fire even when the agent omits scoring_factors entirely."""
+ result = vbr.validate_report({
+ "findings": [
+ {"title": "Anchor text", "source": "not-assessed", "health_score": 12},
+ ],
+ })
+
+ assert result["status"] == "FAIL"
+ assert "source_score_consistency" in result["metadata"]["checks_run"]