Skip to content

Bhanunamikaze/Agentic-SEO-Skill

Deterministic 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.

FileKindSize
SKILL.mdskill md19.4 KB
scripts/__init__.pyscript34 B
scripts/a11y_seo_checker.pyscript3.4 KB
scripts/ai_crawler_policy_matrix.pyscript2.2 KB
scripts/analyze_visual.pyexecutablescript6.5 KB
scripts/anchor_text_audit.pyscript7.7 KB
scripts/answer_block_scanner.pyscript3.9 KB
scripts/article_seo.pyscript27.1 KB
scripts/audit_runner.pyscript3.1 KB
scripts/broken_links.pyscript8.3 KB
scripts/cache_compression_checker.pyscript6.7 KB
scripts/canonical_checker.pyscript3.4 KB
scripts/capture_screenshot.pyexecutablescript4.4 KB
scripts/citation_readiness.pyscript5.1 KB
scripts/collection_page_checker.pyscript4.2 KB
scripts/competitor_gap.pyscript10.2 KB
scripts/content_decay_detector.pyscript6.2 KB
scripts/content_intent_matcher.pyscript5.4 KB
scripts/crawl_audit.pyscript7.2 KB
scripts/critical_request_chain.pyscript4.8 KB
scripts/duplicate_content.pyscript14.0 KB
scripts/eeat_signal_checker.pyscript5.5 KB
scripts/entity_checker.pyscript19.4 KB
scripts/env_loader.pyscript3.6 KB
scripts/external_link_quality.pyscript6.6 KB
scripts/faceted_nav_audit.pyscript3.3 KB
scripts/fetch_page.pyexecutablescript3.6 KB
scripts/finding_verifier.pyscript4.9 KB
scripts/font_audit.pyscript5.9 KB
scripts/freshness_checker.pyscript6.2 KB
scripts/generate_report.pyscript80.7 KB
scripts/github_api.pyscript12.8 KB
scripts/github_community_health.pyscript8.9 KB
scripts/github_competitor_research.pyscript17.2 KB
scripts/github_readme_lint.pyscript14.9 KB
scripts/github_repo_audit.pyscript21.0 KB
scripts/github_search_benchmark.pyscript7.7 KB
scripts/github_seo_report.pyscript32.0 KB
scripts/github_traffic_archiver.pyscript6.3 KB
scripts/github_weekly_scorecard.pyscript4.4 KB
scripts/gsc_checker.pyscript11.4 KB
scripts/hreflang_checker.pyscript24.2 KB
scripts/hreflang_sitemap_validator.pyscript6.4 KB
scripts/image_inventory.pyscript2.8 KB
scripts/image_weight_audit.pyscript4.8 KB
scripts/indexability_matrix.pyscript3.5 KB
scripts/indexnow_checker.pyscript9.4 KB
scripts/internal_links.pyscript10.5 KB
scripts/javascript_render_audit.pyscript2.9 KB
scripts/lcp_subparts.pyscript7.3 KB
scripts/lib/__init__.pyscript46 B
scripts/lib/safe_http.pyscript6.1 KB
scripts/lighthouse_runner.pyscript6.0 KB
scripts/link_profile.pyscript12.5 KB
scripts/llms_txt_checker.pyscript7.5 KB
scripts/llms_txt_generator.pyscript2.9 KB
scripts/local_seo_checker.pyscript3.7 KB
scripts/log_file_analyzer.pyscript6.0 KB
scripts/mobile_render_checker.pyscript6.9 KB
scripts/orphan_pages_from_sitemap.pyscript6.2 KB
scripts/pagespeed.pyscript12.9 KB
scripts/parse_html.pyexecutablescript12.2 KB
scripts/pre_commit_seo_check.shexecutablescript2.9 KB
scripts/product_schema_checker.pyscript4.9 KB
scripts/readability.pyscript14.5 KB
scripts/redirect_backlink_reclaim.pyscript5.7 KB
scripts/redirect_checker.pyscript6.2 KB
scripts/reference_freshness.pyexecutablescript2.9 KB
scripts/repo_docs_site_checker.pyscript5.7 KB
scripts/repo_file_inventory.pyscript3.6 KB
scripts/repo_release_seo.pyscript6.6 KB
scripts/repo_social_preview_checker.pyscript4.1 KB
scripts/repo_topic_suggester.pyscript6.3 KB
scripts/review_schema_checker.pyscript4.0 KB
scripts/rich_results_guard.pyscript3.4 KB
scripts/robots_checker.pyscript7.2 KB
scripts/robots_path_tester.pyscript1.8 KB
scripts/schema_diff.pyscript3.1 KB
scripts/schema_required_props.pyscript8.1 KB
scripts/schema_template_generator.pyscript5.4 KB
scripts/security_headers.pyscript6.8 KB
scripts/seo_common.pyscript14.1 KB
scripts/sitemap_checker.pyscript6.5 KB
scripts/sitemap_generator.pyscript3.4 KB
scripts/social_meta.pyscript8.7 KB
scripts/third_party_script_audit.pyscript4.7 KB
scripts/topical_cluster_mapper.pyscript6.4 KB
scripts/url_quality.pyscript2.5 KB
scripts/validate_schema.pyexecutablescript4.3 KB
scripts/validate_skill_inventory.pyexecutablescript4.8 KB
scripts/video_schema_checker.pyscript3.6 KB
scripts/visual_regression_snapshot.pyscript5.3 KB
scripts/x_robots_header_checker.pyscript2.0 KB

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()
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall