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/github_competitor_research.py

View on GitHub
#!/usr/bin/env python3
"""
GitHub Competitor Research

Builds a competitor intelligence snapshot from GitHub search queries, then
extracts metadata and README pattern gaps against the target repository.

Usage:
  python github_competitor_research.py --repo owner/repo --query "seo skill" --json
  python github_competitor_research.py --repo owner/repo --query-file queries.txt --top-n 8 --json
"""

import argparse
import base64
import json
import os
import re
import sys
from collections import Counter
from datetime import datetime, timezone

from github_api import GitHubAPIError, auth_context, fetch_json, get_token, normalize_repo_slug, resolve_repo


def utc_now_iso() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()


def _dedupe(values: list) -> list:
    out = []
    seen = set()
    for item in values:
        key = item.lower().strip()
        if key and key not in seen:
            out.append(item.strip())
            seen.add(key)
    return out


def load_queries(args) -> list:
    queries = []
    if args.query:
        queries.extend([q.strip() for q in args.query if q.strip()])
    if args.query_file:
        if not os.path.exists(args.query_file):
            raise GitHubAPIError(f"Query file not found: {args.query_file}")
        with open(args.query_file, "r", encoding="utf-8") as f:
            for line in f:
                text = line.strip()
                if text and not text.startswith("#"):
                    queries.append(text)
    return _dedupe(queries)


def parse_iso8601(value: str):
    if not value:
        return None
    try:
        return datetime.fromisoformat(value.replace("Z", "+00:00"))
    except Exception:
        return None


def days_since(value: str):
    dt = parse_iso8601(value)
    if not dt:
        return None
    return (datetime.now(timezone.utc) - dt).days


def run_query_candidates(
    repo: str,
    query: str,
    token: str,
    provider: str,
    per_page: int,
    max_pages: int,
) -> dict:
    out = {"query": query, "sampled_results": 0, "total_count": None, "errors": []}
    candidates = []
    rank = 0
    for page in range(1, max_pages + 1):
        params = {"q": query, "per_page": per_page, "page": page}
        try:
            response = fetch_json(
                "/search/repositories",
                token=token,
                params=params,
                provider=provider,
                timeout=35,
            )
            data = response.get("data", {})
        except GitHubAPIError as exc:
            out["errors"].append(f"Page {page}: {exc} (status: {exc.status or 'unknown'})")
            break

        if out["total_count"] is None:
            out["total_count"] = data.get("total_count")

        items = data.get("items", [])
        if not items:
            break

        for item in items:
            rank += 1
            out["sampled_results"] += 1
            full_name = item.get("full_name") or ""
            if full_name.lower() == repo.lower():
                continue
            candidates.append(
                {
                    "full_name": full_name,
                    "rank": rank,
                    "stargazers_count": int(item.get("stargazers_count", 0)),
                    "description": item.get("description") or "",
                    "topics": item.get("topics") or [],
                    "html_url": item.get("html_url"),
                }
            )
    out["candidates"] = candidates
    return out


def aggregate_candidates(query_runs: list) -> dict:
    aggregate = {}
    for run in query_runs:
        query = run["query"]
        for item in run.get("candidates", []):
            slug = item["full_name"]
            entry = aggregate.setdefault(
                slug,
                {
                    "full_name": slug,
                    "seen_in_queries": 0,
                    "best_rank": item["rank"],
                    "query_ranks": {},
                    "sample_item": item,
                },
            )
            if query not in entry["query_ranks"]:
                entry["seen_in_queries"] += 1
            entry["query_ranks"][query] = min(entry["query_ranks"].get(query, 10**9), item["rank"])
            entry["best_rank"] = min(entry["best_rank"], item["rank"])
    return aggregate


def score_competitor(entry: dict) -> tuple:
    # Lower rank and wider query coverage should bubble up.
    return (-entry["seen_in_queries"], entry["best_rank"])


def fetch_repo_metadata(repo: str, token: str, provider: str) -> dict:
    try:
        response = fetch_json(f"/repos/{repo}", token=token, provider=provider, timeout=30)
        return response.get("data", {})
    except GitHubAPIError:
        return {}


def decode_readme_content(payload: dict) -> str:
    content = payload.get("content") or ""
    if not content:
        return ""
    try:
        raw = base64.b64decode(content.encode("utf-8"), validate=False)
        return raw.decode("utf-8", errors="replace")
    except Exception:
        return ""


def fetch_readme_metrics(repo: str, token: str, provider: str) -> dict:
    try:
        response = fetch_json(f"/repos/{repo}/readme", token=token, provider=provider, timeout=30)
        payload = response.get("data", {})
    except GitHubAPIError:
        return {"available": False}

    text = decode_readme_content(payload)
    if not text:
        return {"available": False}

    headings = re.findall(r"^(#{1,6})\s+.+$", text, flags=re.MULTILINE)
    words = re.findall(r"\b[\w']+\b", re.sub(r"```.*?```", "", text, flags=re.DOTALL))
    images = re.findall(r"!\[(.*?)\]\((.*?)\)", text)
    lower = text.lower()

    return {
        "available": True,
        "word_count": len(words),
        "heading_count": len(headings),
        "h1_count": len([h for h in headings if len(h) == 1]),
        "image_count": len(images),
        "images_missing_alt": len([img for img in images if not (img[0] or "").strip()]),
        "has_install_section": "install" in lower or "getting started" in lower or "quickstart" in lower,
        "has_contributing_section": "contribut" in lower,
        "has_examples_section": "example" in lower or "usage" in lower or "demo" in lower,
    }


def summarize_gaps(target_repo_data: dict, competitor_details: list) -> dict:
    target_topics = set((target_repo_data.get("topics") or []))
    target_desc = (target_repo_data.get("description") or "").strip()
    target_desc_words = len(re.findall(r"\b[\w']+\b", target_desc))

    competitor_topics = Counter()
    competitor_readme_signals = Counter()
    competitor_desc_words = []

    for item in competitor_details:
        md = item.get("metadata", {})
        rm = item.get("readme_metrics", {})
        topics = md.get("topics") or []
        competitor_topics.update(topics)
        desc = (md.get("description") or "").strip()
        competitor_desc_words.append(len(re.findall(r"\b[\w']+\b", desc)))

        if rm.get("has_install_section"):
            competitor_readme_signals["install"] += 1
        if rm.get("has_contributing_section"):
            competitor_readme_signals["contributing"] += 1
        if rm.get("has_examples_section"):
            competitor_readme_signals["examples"] += 1

    topic_gaps = []
    for topic, freq in competitor_topics.most_common(40):
        if topic not in target_topics:
            topic_gaps.append({"topic": topic, "covered_by_competitors": freq})
    topic_gaps = topic_gaps[:12]

    avg_desc_words = round(sum(competitor_desc_words) / len(competitor_desc_words), 2) if competitor_desc_words else None

    opportunities = []
    if topic_gaps:
        top = ", ".join([t["topic"] for t in topic_gaps[:5]])
        opportunities.append(
            {
                "severity": "Warning",
                "area": "Topics",
                "finding": "High-frequency competitor topics are missing from target repo.",
                "evidence": f"Missing topic examples: {top}",
                "fix": "Add relevant missing topics (without exceeding 20 total) based on actual repository scope.",
            }
        )

    if avg_desc_words is not None and target_desc_words and target_desc_words < avg_desc_words:
        opportunities.append(
            {
                "severity": "Info",
                "area": "Description",
                "finding": "Target repository description is shorter than competitor baseline.",
                "evidence": f"Target words: {target_desc_words}, competitor average: {avg_desc_words}",
                "fix": "Expand description with intent terms, scope, and supported environments.",
            }
        )

    for signal_key, label in (("install", "install"), ("examples", "usage/examples"), ("contributing", "contributing")):
        if competitor_readme_signals.get(signal_key, 0) >= 2:
            opportunities.append(
                {
                    "severity": "Info",
                    "area": "README",
                    "finding": f"Competitors frequently include `{label}` sections.",
                    "evidence": f"{competitor_readme_signals.get(signal_key, 0)} competitor repos include this pattern.",
                    "fix": f"Ensure README has a clear `{label}` section near the top-level navigation flow.",
                }
            )

    return {
        "target_topics_count": len(target_topics),
        "topic_gaps": topic_gaps,
        "description_word_count_target": target_desc_words,
        "description_word_count_competitor_avg": avg_desc_words,
        "readme_pattern_frequency": dict(competitor_readme_signals),
        "opportunities": opportunities,
    }


def build_report(
    repo: str,
    token: str,
    provider: str,
    queries: list,
    competitors: list,
    per_page: int,
    max_pages: int,
    top_n: int,
) -> dict:
    ctx = auth_context(token=token)
    report = {
        "timestamp_utc": utc_now_iso(),
        "repo": repo,
        "provider": provider,
        "auth_context": ctx,
        "token_present": bool(token),
        "queries": queries,
        "query_runs": [],
        "competitors": [],
        "gaps": {},
        "limitations": [],
    }

    if not token:
        if ctx.get("gh_authenticated"):
            report["limitations"].append(
                "No GitHub token found. Using authenticated gh CLI fallback for competitor research."
            )
        elif ctx.get("gh_available"):
            report["limitations"].append(
                "No GitHub token found and gh CLI is not authenticated. Run `gh auth login -h github.com` or set GITHUB_TOKEN/GH_TOKEN."
            )
        else:
            report["limitations"].append(
                "No GitHub token found and gh CLI is unavailable. Competitor research may be rate-limited; set GITHUB_TOKEN/GH_TOKEN."
            )

    ranked = []
    if competitors:
        for slug in competitors:
            if slug.lower() == repo.lower():
                continue
            ranked.append(
                {
                    "full_name": slug,
                    "seen_in_queries": 0,
                    "best_rank": None,
                    "query_ranks": {},
                    "sample_item": {"description": "", "topics": [], "stargazers_count": 0, "html_url": f"https://github.com/{slug}"},
                }
            )
        ranked = ranked[:top_n]
    elif queries:
        query_run_full = []
        for query in queries:
            run = run_query_candidates(
                repo=repo,
                query=query,
                token=token,
                provider=provider,
                per_page=per_page,
                max_pages=max_pages,
            )
            query_run_full.append(run)
            report["query_runs"].append({
                "query": run["query"],
                "sampled_results": run["sampled_results"],
                "total_count": run["total_count"],
                "errors": run["errors"],
            })
            for err in run.get("errors", []):
                report["limitations"].append(f"{query}: {err}")
        aggregate = aggregate_candidates(query_run_full)
        ranked = sorted(aggregate.values(), key=score_competitor)[:top_n]
    else:
        report["limitations"].append(
            "No competitor inputs provided. Supply `--query/--query-file` from LLM/web search or pass explicit `--competitor` repo slugs."
        )

    target_repo_data = fetch_repo_metadata(repo=repo, token=token, provider=provider)
    competitor_details = []
    for entry in ranked:
        slug = entry["full_name"]
        md = fetch_repo_metadata(repo=slug, token=token, provider=provider)
        rm = fetch_readme_metrics(repo=slug, token=token, provider=provider)
        competitor_details.append(
            {
                "full_name": slug,
                "seen_in_queries": entry["seen_in_queries"],
                "best_rank": entry["best_rank"],
                "query_ranks": entry["query_ranks"],
                "metadata": {
                    "description": md.get("description") or entry["sample_item"].get("description", ""),
                    "topics": md.get("topics") or entry["sample_item"].get("topics", []),
                    "stargazers_count": int(md.get("stargazers_count", entry["sample_item"].get("stargazers_count", 0))),
                    "forks_count": int(md.get("forks_count", 0)),
                    "homepage": md.get("homepage") or "",
                    "pushed_at": md.get("pushed_at"),
                    "pushed_days_ago": days_since(md.get("pushed_at")),
                    "html_url": md.get("html_url") or entry["sample_item"].get("html_url"),
                },
                "readme_metrics": rm,
            }
        )

    report["competitors"] = competitor_details
    report["gaps"] = summarize_gaps(target_repo_data=target_repo_data, competitor_details=competitor_details)
    report["target_metadata"] = {
        "description": target_repo_data.get("description") or "",
        "topics": target_repo_data.get("topics") or [],
        "stargazers_count": int(target_repo_data.get("stargazers_count", 0)),
        "forks_count": int(target_repo_data.get("forks_count", 0)),
        "html_url": target_repo_data.get("html_url") or f"https://github.com/{repo}",
    }
    report["summary"] = {
        "competitors_analyzed": len(competitor_details),
        "queries_used": len(queries),
        "top_topic_gaps": report["gaps"].get("topic_gaps", [])[:5],
    }
    return report


def print_text(report: dict):
    print(f"\nGitHub Competitor Research: {report.get('repo')}")
    print("=" * 60)
    summary = report.get("summary", {})
    print(
        f"Competitors analyzed: {summary.get('competitors_analyzed', 0)} | "
        f"Queries: {summary.get('queries_used', 0)}"
    )
    top_gaps = summary.get("top_topic_gaps", [])
    if top_gaps:
        print("Top topic gaps:")
        for gap in top_gaps:
            print(f"- {gap['topic']} ({gap['covered_by_competitors']} competitors)")
    if report.get("limitations"):
        print("\nLimitations:")
        for item in report["limitations"][:10]:
            print(f"- {item}")


def main():
    parser = argparse.ArgumentParser(description="Run GitHub competitor research against query-defined peers.")
    parser.add_argument("--repo", help="Repository slug or URL (owner/repo). If omitted, infer from git origin.")
    parser.add_argument("--token", help="GitHub token override. Prefer env vars GITHUB_TOKEN or GH_TOKEN.")
    parser.add_argument("--query", action="append", help="Search query (repeatable).")
    parser.add_argument("--query-file", help="Path to newline-delimited query file.")
    parser.add_argument("--competitor", action="append", help="Explicit competitor repo slug/URL (repeatable).")
    parser.add_argument("--per-page", type=int, default=30, help="Results per page (default: 30, max: 100).")
    parser.add_argument("--max-pages", type=int, default=2, help="Max search pages per query (default: 2).")
    parser.add_argument("--top-n", type=int, default=6, help="Number of competitor repos to analyze deeply (default: 6).")
    parser.add_argument(
        "--provider",
        choices=["auto", "api", "gh"],
        default="auto",
        help="GitHub data provider mode (default: auto).",
    )
    parser.add_argument("--json", action="store_true", help="Output JSON.")
    parser.add_argument("--output", help="Write JSON report to path.")
    args = parser.parse_args()

    try:
        repo = resolve_repo(args.repo)
        token = get_token(args.token)
        queries = load_queries(args)
    except GitHubAPIError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(2)

    competitors = []
    if args.competitor:
        for raw in args.competitor:
            slug = normalize_repo_slug(raw)
            if slug:
                competitors.append(slug)
    competitors = _dedupe(competitors)

    report = build_report(
        repo=repo,
        token=token,
        provider=args.provider,
        queries=queries,
        competitors=competitors,
        per_page=max(1, min(100, args.per_page)),
        max_pages=max(1, args.max_pages),
        top_n=max(1, min(25, args.top_n)),
    )

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            json.dump(report, f, indent=2)

    if args.json:
        print(json.dumps(report, indent=2))
    else:
        print_text(report)


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