Bhanunamikaze/Agentic-SEO-Skill
seo
VerifiedDeterministic LLM-first SEO audits for websites, blog posts, and GitHub repositories. Use this when the user asks to "perform SEO analysis", "run SEO audit", "analyze SEO", "check technical SEO", "review schema", "Core Web Vitals", "E-E-A-T", "hreflang", "GEO", "AEO", or GitHub repository SEO optimization. For full/page/repo audits, run bundled scripts for evidence and return prioritized, confidence-labeled fixes.
scripts/entity_checker.py
View on GitHub#!/usr/bin/env python3
"""
Entity SEO Checker
Validates entity presence across Knowledge Graph signals: Wikidata,
Wikipedia, sameAs properties in JSON-LD, and Google Knowledge Graph
Search API (optional, requires API key).
Usage:
python entity_checker.py https://example.com --json
python entity_checker.py https://example.com --entity "Example Corp"
python entity_checker.py https://example.com --kg-api-key YOUR_KEY
"""
import argparse
import json
import re
import sys
import urllib.parse
from urllib.parse import urlparse
try:
from bs4 import BeautifulSoup
except ImportError:
print("Error: beautifulsoup4 required. Install with: pip install beautifulsoup4")
sys.exit(1)
try:
from lib.safe_http import safe_get, safe_head
except ImportError:
from scripts.lib.safe_http import safe_get, safe_head
# Authoritative sameAs targets (ranked by KG signal strength)
SAMEAS_PLATFORMS = {
"wikipedia.org": {"name": "Wikipedia", "priority": "Critical", "kg_signal": "Primary"},
"wikidata.org": {"name": "Wikidata", "priority": "Critical", "kg_signal": "Primary"},
"linkedin.com": {"name": "LinkedIn", "priority": "High", "kg_signal": "Strong"},
"twitter.com": {"name": "Twitter/X", "priority": "High", "kg_signal": "Strong"},
"x.com": {"name": "Twitter/X", "priority": "High", "kg_signal": "Strong"},
"crunchbase.com": {"name": "Crunchbase", "priority": "Medium", "kg_signal": "Moderate"},
"github.com": {"name": "GitHub", "priority": "Medium", "kg_signal": "Moderate"},
"youtube.com": {"name": "YouTube", "priority": "Medium", "kg_signal": "Moderate"},
"facebook.com": {"name": "Facebook", "priority": "Low", "kg_signal": "Weak"},
"instagram.com": {"name": "Instagram", "priority": "Low", "kg_signal": "Weak"},
}
# ---------------------------------------------------------------------------
# Fetch
# ---------------------------------------------------------------------------
def fetch_html(url: str, timeout: int = 12) -> str:
try:
return safe_get(url, timeout=timeout).text
except Exception as exc:
print(f"Error fetching {url}: {exc}", file=sys.stderr)
return ""
# ---------------------------------------------------------------------------
# Schema extraction
# ---------------------------------------------------------------------------
def extract_entities_from_schema(soup: BeautifulSoup) -> list:
"""Extract Organization/Person entities and their sameAs from JSON-LD."""
entities = []
for script in soup.find_all("script", type="application/ld+json"):
try:
data = json.loads(script.string or "")
except (json.JSONDecodeError, TypeError):
continue
# Handle @graph arrays
items = []
if isinstance(data, list):
items = data
elif isinstance(data, dict):
if "@graph" in data:
items = data["@graph"]
else:
items = [data]
for item in items:
if not isinstance(item, dict):
continue
schema_type = item.get("@type", "")
# Look for entity types
if schema_type in ("Organization", "Person", "Corporation",
"LocalBusiness", "Brand", "MedicalOrganization",
"EducationalOrganization", "GovernmentOrganization"):
entities.append({
"type": schema_type,
"name": item.get("name", ""),
"url": item.get("url", ""),
"sameAs": item.get("sameAs", []),
"logo": item.get("logo", ""),
"description": item.get("description", ""),
"identifier": item.get("identifier", ""),
})
return entities
# ---------------------------------------------------------------------------
# sameAs analysis
# ---------------------------------------------------------------------------
def analyze_sameas(same_as_list: list) -> dict:
"""Analyze sameAs URLs for completeness and validity."""
if isinstance(same_as_list, str):
same_as_list = [same_as_list]
found = {}
missing = {}
issues = []
for url in same_as_list:
if not isinstance(url, str):
continue
parsed = urlparse(url)
domain = parsed.netloc.replace("www.", "").lower()
matched = False
for platform_domain, info in SAMEAS_PLATFORMS.items():
if platform_domain in domain:
found[info["name"]] = {
"url": url,
"priority": info["priority"],
"kg_signal": info["kg_signal"],
}
matched = True
break
if not matched:
found[domain] = {
"url": url,
"priority": "Low",
"kg_signal": "Unknown",
}
# Identify missing critical platforms
for platform_domain, info in SAMEAS_PLATFORMS.items():
if info["priority"] in ("Critical", "High"):
if info["name"] not in found:
missing[info["name"]] = {
"domain": platform_domain,
"priority": info["priority"],
"kg_signal": info["kg_signal"],
}
# Check for broken URLs (quick HEAD check on first 3)
for name, data in list(found.items())[:3]:
url = data["url"]
try:
resp = safe_head(url, timeout=6)
if resp.status_code >= 400:
issues.append({
"severity": "Warning",
"finding": f"sameAs URL returns HTTP {resp.status_code}: {url}",
"fix": f"Update sameAs URL for {name} to a valid, non-redirecting destination.",
})
except Exception:
issues.append({
"severity": "Info",
"finding": f"Could not verify sameAs URL: {url}",
"fix": "Manually confirm this URL is accessible and correct.",
})
return {
"found": found,
"missing": missing,
"issues": issues,
"total_found": len(found),
"total_missing_critical": len(missing),
}
# ---------------------------------------------------------------------------
# Wikidata lookup
# ---------------------------------------------------------------------------
def check_wikidata(entity_name: str) -> dict:
"""Search Wikidata for the entity name. Returns QID if found."""
if not entity_name:
return {"found": False, "qid": None, "url": None}
try:
query = urllib.parse.quote(entity_name)
url = f"https://www.wikidata.org/w/api.php?action=wbsearchentities&search={query}&language=en&format=json&limit=3"
data = safe_get(url, timeout=8).json()
results = data.get("search", [])
if results:
best = results[0]
return {
"found": True,
"qid": best.get("id"),
"label": best.get("label"),
"description": best.get("description", ""),
"url": f"https://www.wikidata.org/wiki/{best.get('id')}",
"confidence": "High" if best.get("label", "").lower() == entity_name.lower() else "Medium",
}
except Exception:
pass
return {"found": False, "qid": None, "url": None}
# ---------------------------------------------------------------------------
# Wikipedia check
# ---------------------------------------------------------------------------
def check_wikipedia(entity_name: str) -> dict:
"""Check if the entity has a Wikipedia article."""
if not entity_name:
return {"found": False, "url": None}
try:
query = urllib.parse.quote(entity_name.replace(" ", "_"))
url = f"https://en.wikipedia.org/w/api.php?action=query&titles={query}&format=json&redirects=1"
data = safe_get(url, timeout=8).json()
pages = data.get("query", {}).get("pages", {})
for page_id, page_data in pages.items():
if page_id != "-1":
return {
"found": True,
"title": page_data.get("title"),
"url": f"https://en.wikipedia.org/wiki/{urllib.parse.quote(page_data.get('title', '').replace(' ', '_'))}",
}
except Exception:
pass
return {"found": False, "url": None}
def check_google_knowledge_graph(entity_name: str, api_key: str = "") -> dict:
"""Search Google Knowledge Graph Search API when a key is available."""
if not api_key:
return {"checked": False, "found": False, "result": None}
if not entity_name:
return {"checked": True, "found": False, "result": None, "error": "No entity name to search"}
try:
response = safe_get(
"https://kgsearch.googleapis.com/v1/entities:search",
params={
"query": entity_name,
"key": api_key,
"limit": 3,
"indent": "false",
},
timeout=8,
max_response_bytes=1_000_000,
)
data = response.json()
items = data.get("itemListElement", [])
if not items:
return {"checked": True, "found": False, "result": None}
best = items[0]
result = best.get("result", {}) if isinstance(best, dict) else {}
return {
"checked": True,
"found": True,
"name": result.get("name"),
"kg_id": result.get("@id"),
"description": result.get("description"),
"detailed_description": (result.get("detailedDescription") or {}).get("articleBody", ""),
"url": (result.get("detailedDescription") or {}).get("url"),
"types": result.get("@type", []),
"score": best.get("resultScore"),
}
except Exception as exc:
return {"checked": True, "found": False, "result": None, "error": str(exc)}
# ---------------------------------------------------------------------------
# NAP consistency check
# ---------------------------------------------------------------------------
def check_nap_consistency(soup: BeautifulSoup, entities: list) -> list:
"""Check Name/Address/Phone consistency signals on the page."""
issues = []
# Look for structured LocalBusiness / Organization
local_entities = [e for e in entities if e["type"] in ("LocalBusiness", "Organization")]
if not local_entities:
return []
for entity in local_entities:
name = entity.get("name", "")
if not name:
issues.append({
"severity": "Warning",
"finding": f"{entity['type']} schema is missing 'name' property.",
"fix": "Add the exact business name to the schema.",
})
# Check for visible phone/address on page
page_text = soup.get_text(separator=" ")
has_phone = bool(re.search(r"[\+]?[\d\-\(\)\s]{7,15}", page_text))
has_address = bool(re.search(r"\d{1,5}\s+\w+\s+(street|st|avenue|ave|road|rd|blvd|drive|dr|lane|ln)", page_text, re.I))
if not has_phone and local_entities:
issues.append({
"severity": "Info",
"finding": "No phone number detected on page for LocalBusiness entity.",
"fix": "Display phone number visibly and include 'telephone' in LocalBusiness schema.",
})
return issues
# ---------------------------------------------------------------------------
# Main analysis
# ---------------------------------------------------------------------------
def run_entity_check(url: str, entity_name: str = "", kg_api_key: str = "") -> dict:
"""Run full entity SEO check."""
html = fetch_html(url)
if not html:
return {"error": f"Failed to fetch {url}", "url": url}
soup = BeautifulSoup(html, "html.parser")
# Extract entities from schema
entities = extract_entities_from_schema(soup)
# Determine entity name
if not entity_name and entities:
entity_name = entities[0].get("name", "")
if not entity_name:
# Try og:site_name or title
og_site = soup.find("meta", property="og:site_name")
if og_site:
entity_name = og_site.get("content", "")
else:
title = soup.find("title")
if title:
entity_name = title.get_text(strip=True).split("|")[0].split("-")[0].strip()
# Analyze sameAs from all entities
all_same_as = []
for e in entities:
sa = e.get("sameAs", [])
if isinstance(sa, str):
all_same_as.append(sa)
elif isinstance(sa, list):
all_same_as.extend(sa)
sameas_analysis = analyze_sameas(all_same_as)
# External lookups
wikidata = check_wikidata(entity_name)
wikipedia = check_wikipedia(entity_name)
google_kg = check_google_knowledge_graph(entity_name, kg_api_key)
has_notability_signal = bool(wikidata.get("found") or wikipedia.get("found") or google_kg.get("found"))
# NAP consistency
nap_issues = check_nap_consistency(soup, entities)
# Build issues list
issues = []
if not entities:
issues.append({
"severity": "Critical",
"area": "Schema",
"finding": "No Organization/Person entity found in JSON-LD.",
"fix": "Add Organization or Person schema with name, url, logo, and sameAs properties.",
})
if entities and not all_same_as:
issues.append({
"severity": "Critical",
"area": "sameAs",
"finding": "Entity schema exists but has no sameAs properties.",
"fix": "Add sameAs URLs pointing to Wikipedia, LinkedIn, Twitter/X, etc.",
})
if not wikidata["found"]:
issues.append({
"severity": "Info",
"area": "Wikidata",
"finding": f"No Wikidata entry found for '{entity_name}'.",
"fix": "If the entity meets Wikidata notability guidelines, create or improve an item with accurate third-party references. Do not create one solely for SEO.",
})
if not wikipedia["found"]:
issues.append({
"severity": "Info",
"area": "Wikipedia",
"finding": f"No Wikipedia article found for '{entity_name}'.",
"fix": "Only pursue Wikipedia if the entity meets independent notability standards. Otherwise, strengthen official schema, sameAs profiles, citations, and About/Contact signals.",
})
if google_kg.get("checked") and not google_kg.get("found"):
issues.append({
"severity": "Info",
"area": "Google Knowledge Graph",
"finding": f"No Google Knowledge Graph Search API match found for '{entity_name}'.",
"fix": "Improve entity consistency across official site schema, sameAs profiles, authoritative mentions, and organization/person pages.",
})
for name, data in sameas_analysis.get("missing", {}).items():
missing_primary_kg_profile = name in ("Wikipedia", "Wikidata")
issues.append({
"severity": "Warning" if data["priority"] == "Critical" and has_notability_signal else "Info",
"area": "sameAs",
"finding": f"Missing sameAs link to {name} ({data['kg_signal']} KG signal).",
"fix": (
f"Add the existing official '{data['domain']}' URL to sameAs; do not create this profile solely for SEO."
if missing_primary_kg_profile
else f"Add '{data['domain']}' profile URL to sameAs array in your entity schema."
),
})
issues.extend(sameas_analysis.get("issues", []))
issues.extend(nap_issues)
return {
"url": url,
"entity_name": entity_name,
"entities_in_schema": entities,
"sameas_analysis": sameas_analysis,
"wikidata": wikidata,
"wikipedia": wikipedia,
"google_kg": google_kg,
"nap_issues": nap_issues,
"issues": issues,
"summary": {
"entities_found": len(entities),
"sameas_count": len(all_same_as),
"sameas_missing_critical": sameas_analysis["total_missing_critical"],
"wikidata_found": wikidata["found"],
"wikipedia_found": wikipedia["found"],
"google_kg_checked": google_kg.get("checked", False),
"google_kg_found": google_kg.get("found", False),
"total_issues": len(issues),
},
}
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def main():
parser = argparse.ArgumentParser(
description="Entity SEO Checker ā Knowledge Graph, Wikidata, sameAs validation"
)
parser.add_argument("url", help="Page URL to check")
parser.add_argument("--entity", default="", help="Entity name to search (auto-detected from schema/title if omitted)")
parser.add_argument("--kg-api-key", default="", help="Google Knowledge Graph API key (optional). Falls back to GOOGLE_KG_API_KEY / GOOGLE_API_KEY env vars or .env file.")
parser.add_argument("--json", action="store_true", help="Output as JSON")
args = parser.parse_args()
from env_loader import get_env
kg_api_key = args.kg_api_key or get_env("GOOGLE_KG_API_KEY", "GOOGLE_API_KEY")
report = run_entity_check(args.url, entity_name=args.entity, kg_api_key=kg_api_key)
if args.json:
print(json.dumps(report, indent=2, default=str))
return
if report.get("error"):
print(f"Error: {report['error']}")
sys.exit(1)
print(f"\nEntity SEO Check ā {report['url']}")
print("=" * 60)
print(f"Entity Name : {report['entity_name']}")
print(f"Entities in Schema: {report['summary']['entities_found']}")
if report["entities_in_schema"]:
for e in report["entities_in_schema"]:
print(f" [{e['type']}] {e['name']}")
print(f"\nsameAs Properties : {report['summary']['sameas_count']}")
sa = report["sameas_analysis"]
for name, data in sa["found"].items():
print(f" ā
{name}: {data['url']} ({data['kg_signal']} signal)")
for name, data in sa["missing"].items():
icon = "š“" if data["priority"] == "Critical" else "ā ļø"
print(f" {icon} Missing: {name} ({data['kg_signal']} signal)")
wd = report["wikidata"]
print(f"\nWikidata : {'ā
' + wd['qid'] + ' ā ' + wd.get('description', '') if wd['found'] else 'ā Not found'}")
wp = report["wikipedia"]
print(f"Wikipedia : {'ā
' + wp.get('url', '') if wp['found'] else 'ā Not found'}")
kg = report.get("google_kg", {})
if kg.get("checked"):
if kg.get("found"):
print(f"Google KG : ā
{kg.get('name', '')} ({kg.get('kg_id', '')})")
else:
suffix = f" ā {kg.get('error')}" if kg.get("error") else ""
print(f"Google KG : ā Not found{suffix}")
else:
print("Google KG : Not checked (no API key)")
if report["issues"]:
sev_icon = {"Critical": "š“", "Warning": "ā ļø", "Info": "ā¹ļø"}
print(f"\nIssues ({report['summary']['total_issues']}):")
for issue in report["issues"]:
icon = sev_icon.get(issue.get("severity", "Info"), "ā¹ļø")
print(f" {icon} [{issue.get('area', issue.get('severity'))}] {issue['finding']}")
print(f" Fix: {issue['fix']}")
else:
print("\nā
No entity SEO issues detected.")
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |