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.pyindex 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))+# Classifyerrors = [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.mdindex 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 Formatdiff --git a/tests/test_backlink_score_gate.py b/tests/test_backlink_score_gate.pynew file mode 100644index 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"]