Skip to content

balsm-health/website / .claude/skills/seo

Comprehensive SEO analysis for any website or business type. Full site audits, single-page analysis, technical SEO (crawlability, indexability, Core Web Vitals with INP), schema markup, content quality (E-E-A-T), image optimization, sitemap analysis, and GEO for AI Overviews/ChatGPT/Perplexity. Industry detection for SaaS, e-commerce, local, publishers, agencies. Triggers on: SEO, audit, schema, Core Web Vitals, sitemap, E-E-A-T, AI Overviews, GEO, technical SEO, content quality, page speed.

FileKindSize
LICENSE.txtmarkdown143 B
SKILL.mdskill md16.9 KB
bin/claude-seoexecutablescript1.5 KB
extensions/banana/references/cost-tracking.mdmarkdown1.2 KB
extensions/banana/references/gemini-models.mdmarkdown5.8 KB
extensions/banana/references/mcp-tools.mdmarkdown3.7 KB
extensions/banana/references/post-processing.mdmarkdown5.1 KB
extensions/banana/references/presets.mdmarkdown2.2 KB
extensions/banana/references/prompt-engineering.mdmarkdown20.9 KB
extensions/banana/references/seo-image-presets.mdmarkdown4.0 KB
extensions/banana/scripts/batch.pyexecutablescript3.3 KB
extensions/banana/scripts/cost_tracker.pyexecutablescript7.2 KB
extensions/banana/scripts/edit.pyexecutablescript5.6 KB
extensions/banana/scripts/generate.pyexecutablescript6.4 KB
extensions/banana/scripts/presets.pyexecutablescript4.9 KB
extensions/banana/scripts/setup_mcp.pyexecutablescript4.5 KB
extensions/banana/scripts/validate_setup.pyexecutablescript3.8 KB
hooks/hooks.jsonconfig416 B
hooks/run-python-hook.jsscript1.7 KB
hooks/validate-schema.pyexecutablescript5.9 KB
pdf/google-seo-reference.mdmarkdown8.0 KB
references/backlink-quality.mdmarkdown3.4 KB
references/cwv-thresholds.mdmarkdown6.9 KB
references/eeat-framework.mdmarkdown8.1 KB
references/free-backlink-sources.mdmarkdown5.6 KB
references/local-schema-types.mdmarkdown9.2 KB
references/local-seo-signals.mdmarkdown9.6 KB
references/maps-api-endpoints.mdmarkdown5.9 KB
references/maps-free-apis.mdmarkdown6.0 KB
references/maps-gbp-checklist.mdmarkdown5.9 KB
references/maps-geo-grid.mdmarkdown4.3 KB
references/quality-gates.mdmarkdown5.1 KB
references/schema-types.mdmarkdown7.8 KB
references/thinking-framework.mdmarkdown9.3 KB
requirements.txtmanifest1.5 KB
runtime-plugin.jsonconfig1.5 KB
schema/templates.jsonconfig9.4 KB
scripts/agent_ux_check.pyscript8.2 KB
scripts/analyze_visual.pyexecutablescript7.2 KB
scripts/backlinks_auth.pyscript16.1 KB
scripts/bing_webmaster.pyscript21.8 KB
scripts/capture_screenshot.pyexecutablescript6.4 KB
scripts/commoncrawl_graph.pyscript15.6 KB
scripts/consistency_check.pyscript12.5 KB
scripts/content_humanize.pyscript7.2 KB
scripts/content_quality.pyscript9.7 KB
scripts/content_verify.pyscript7.1 KB
scripts/crux_history.pyscript10.7 KB
scripts/dataforseo_costs.pyscript15.8 KB
scripts/dataforseo_merchant.pyexecutablescript16.7 KB
scripts/dataforseo_normalize.pyexecutablescript14.7 KB
scripts/domain_history.pyscript9.6 KB
scripts/drift_baseline.pyscript13.5 KB
scripts/drift_compare.pyscript22.3 KB
scripts/drift_history.pyscript3.4 KB
scripts/drift_report.pyscript11.0 KB
scripts/fetch_page.pyexecutablescript9.4 KB
scripts/ga4_report.pyscript16.8 KB
scripts/gbp_deprecation_lint.pyexecutablescript4.7 KB
scripts/google_auth.pyscript31.0 KB
scripts/google_report.pyscript97.6 KB
scripts/gsc_inspect.pyscript11.0 KB
scripts/gsc_query.pyscript18.6 KB
scripts/indexing_notify.pyscript10.3 KB
scripts/indexnow_submit.pyscript8.8 KB
scripts/iptc_ai_label.pyscript7.6 KB
scripts/keyword_planner.pyscript10.8 KB
scripts/lcp_subparts.pyscript7.2 KB
scripts/moz_api.pyscript14.7 KB
scripts/nlp_analyze.pyscript12.1 KB
scripts/pagespeed_check.pyscript22.9 KB
scripts/parasite_risk.pyexecutablescript8.6 KB
scripts/parse_html.pyexecutablescript8.8 KB
scripts/portability_check.pyscript7.8 KB
scripts/preload_check.pyscript8.1 KB
scripts/release_sign.pyscript5.6 KB
scripts/render_page.pyscript20.9 KB
scripts/runtime.pyexecutablescript15.1 KB
scripts/schema_ecommerce_validate.pyscript11.8 KB
scripts/schema_generate.pyscript12.0 KB
scripts/seo_updates.pyscript4.8 KB
scripts/sitemap_discovery.pyscript10.0 KB
scripts/sync_flow.pyscript11.9 KB
scripts/ucp_check.pyscript8.4 KB
scripts/unlighthouse_run.pyscript5.6 KB
scripts/url_safety.pyscript22.0 KB
scripts/validate_backlink_report.pyscript11.7 KB
scripts/verify_backlinks.pyscript12.9 KB
scripts/verify_release.pyscript4.8 KB
scripts/youtube_search.pyscript12.3 KB

scripts/lcp_subparts.py

View on GitHub
#!/usr/bin/env python3
"""
LCP subparts breakdown via CrUX API.

Since January 2025 CrUX has exposed the four LCP sub-metrics:
  - largest_contentful_paint_image_time_to_first_byte
  - largest_contentful_paint_image_resource_load_delay
  - largest_contentful_paint_image_resource_load_duration
  - largest_contentful_paint_image_element_render_delay

These let you decompose a slow LCP into network, scheduling, fetch,
and render phases — turning "your LCP is 4.2s" into "your TTFB is 1.1s
and your render delay is 2.4s, fix server response and the image
preload sequence". Per the gap analysis, this is the single most
actionable upgrade to claude-seo's CWV reporting.

Usage::

    python scripts/lcp_subparts.py https://example.com/
    python scripts/lcp_subparts.py https://example.com/ --form-factor PHONE --json

Requires the same Google API key used by ``scripts/crux_history.py``.
"""

from __future__ import annotations

import argparse
import json
import os
import sys

import urllib.request
import urllib.error

_SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
if _SCRIPTS_DIR not in sys.path:
    sys.path.insert(0, _SCRIPTS_DIR)
from url_safety import URLSafetyError, validate_url_strict  # noqa: E402
from google_auth import get_api_key, google_api_key_headers, redact_google_api_key  # noqa: E402


CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"


_LCP_SUBPART_METRICS = [
    "largest_contentful_paint_image_time_to_first_byte",
    "largest_contentful_paint_image_resource_load_delay",
    "largest_contentful_paint_image_resource_load_duration",
    "largest_contentful_paint_image_element_render_delay",
]


def _query_crux(url: str, form_factor: str, api_key: str) -> dict:
    payload = {
        "url": url,
        "formFactor": form_factor,
        "metrics": _LCP_SUBPART_METRICS + ["largest_contentful_paint"],
    }
    body = json.dumps(payload).encode("utf-8")
    headers = {"Content-Type": "application/json", **google_api_key_headers(api_key)}
    request = urllib.request.Request(
        CRUX_ENDPOINT,
        data=body,
        headers=headers,
    )
    try:
        with urllib.request.urlopen(request, timeout=30) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as exc:
        return {
            "error": (
                f"CrUX HTTP {exc.code}: "
                f"{redact_google_api_key(exc.read().decode('utf-8', 'replace'))}"
            )
        }
    except urllib.error.URLError as exc:
        return {"error": f"CrUX request failed: {redact_google_api_key(exc.reason)}"}


def _percentile(metric: dict) -> float | None:
    p = metric.get("percentiles", {}).get("p75")
    if p is None:
        return None
    try:
        return float(p)
    except (TypeError, ValueError):
        return None


def analyse(url: str, form_factor: str = "PHONE") -> dict:
    try:
        url, _ = validate_url_strict(url)
    except URLSafetyError as exc:
        return {"error": f"url_safety: {exc}"}

    api_key = get_api_key()
    if not api_key:
        return {
            "error": "Google API key not configured. "
                     "Run `python scripts/google_auth.py --setup`.",
        }

    raw = _query_crux(url, form_factor, api_key)
    if "error" in raw:
        return raw

    metrics = raw.get("record", {}).get("metrics", {})
    breakdown: dict[str, float | None] = {}
    for key in _LCP_SUBPART_METRICS:
        m = metrics.get(key)
        breakdown[key] = _percentile(m) if m else None

    overall_lcp = _percentile(metrics.get("largest_contentful_paint", {})) \
        if metrics.get("largest_contentful_paint") else None

    # Identify the dominant subpart. "Dominant" = subpart that contributes
    # >40% of overall LCP, which is where remediation effort pays back.
    dominant: list[dict] = []
    if overall_lcp:
        for key, val in breakdown.items():
            if val is None:
                continue
            share = val / overall_lcp
            if share >= 0.40:
                dominant.append({"metric": key, "p75_ms": val,
                                 "share": round(share, 2)})

    recommendations: list[str] = []
    for d in dominant:
        if d["metric"].endswith("time_to_first_byte"):
            recommendations.append(
                "TTFB dominates LCP. Check origin response time, server-side "
                "compute, CDN edge cache hit rate. Aim for TTFB < 0.8s."
            )
        elif d["metric"].endswith("resource_load_delay"):
            recommendations.append(
                "Resource load delay dominates. The LCP element is discovered "
                "late; preload the hero image with fetchpriority=high or move "
                "it ahead of blocking resources."
            )
        elif d["metric"].endswith("resource_load_duration"):
            recommendations.append(
                "Resource load duration dominates. The LCP image is large. "
                "Serve responsive sizes (srcset), modern formats (AVIF/WebP), "
                "and add async decoding hints."
            )
        elif d["metric"].endswith("element_render_delay"):
            recommendations.append(
                "Element render delay dominates. The element is loaded but "
                "painting is blocked. Reduce render-blocking CSS/JS above the "
                "fold and avoid font-blocking layout shifts."
            )

    return {
        "url": url,
        "form_factor": form_factor,
        "p75_lcp_ms": overall_lcp,
        "subparts_p75_ms": breakdown,
        "dominant_subparts": dominant,
        "recommendations": recommendations,
        "raw": raw,
    }


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Decompose LCP into its four subparts via CrUX."
    )
    parser.add_argument("url")
    parser.add_argument(
        "--form-factor",
        choices=("PHONE", "DESKTOP", "TABLET", "ALL_FORM_FACTORS"),
        default="PHONE",
    )
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

    result = analyse(args.url, args.form_factor)

    if "error" in result:
        print(f"Error: {result['error']}", file=sys.stderr)
        return 1

    if args.json:
        # Strip the noisy CrUX raw response from JSON output by default.
        out = {k: v for k, v in result.items() if k != "raw"}
        json.dump(out, sys.stdout, indent=2)
        sys.stdout.write("\n")
    else:
        print(f"URL: {result['url']}")
        print(f"Form factor: {result['form_factor']}")
        print(f"Overall p75 LCP: {result['p75_lcp_ms']} ms")
        print("Subparts (p75 ms):")
        for k, v in result["subparts_p75_ms"].items():
            label = k.replace("largest_contentful_paint_image_", "")
            print(f"  {label:35s} {v if v is not None else '—'}")
        if result["dominant_subparts"]:
            print("\nDominant subparts (>= 40% of LCP):")
            for d in result["dominant_subparts"]:
                short = d["metric"].replace("largest_contentful_paint_image_", "")
                print(f"  {short} = {d['p75_ms']:.0f} ms ({d['share']*100:.0f}%)")
        if result["recommendations"]:
            print("\nRecommendations:")
            for r in result["recommendations"]:
                print(f"  - {r}")

    return 0


if __name__ == "__main__":
    sys.exit(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: 472kUpdated 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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated 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