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

View on GitHub
#!/usr/bin/env python3
"""
Google Ads API - Keyword Planner for SEO keyword research.

Gold-standard source for keyword search volume, CPC, and competition data.
Requires a Google Ads Manager account with a developer token.

Usage:
    python keyword_planner.py ideas "seo tools" --json
    python keyword_planner.py volume "seo tools,seo audit,seo checker" --json

Prerequisites:
    - Google Ads Manager account (can be free)
    - Developer Token (apply at Google Ads API Center)
    - OAuth credentials or service account
    - google-ads Python library: pip install google-ads
    - Config: ~/.config/claude-seo/google-api.json with:
      {
        "ads_developer_token": "YOUR_DEV_TOKEN",
        "ads_customer_id": "123-456-7890",
        "ads_login_customer_id": "123-456-7890"
      }

Note: Accounts without active ad spend receive bucketed volume ranges
(e.g., "1K-10K") instead of exact numbers.
"""

import argparse
import json
import os
import sys
from typing import Optional

try:
    from google.ads.googleads.client import GoogleAdsClient
    from google.ads.googleads.errors import GoogleAdsException
    HAS_GOOGLE_ADS = True
except ImportError:
    HAS_GOOGLE_ADS = False

try:
    from google_auth import load_config
except ImportError:
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    from google_auth import load_config


def _build_ads_client() -> Optional[object]:
    """Build Google Ads client from config."""
    if not HAS_GOOGLE_ADS:
        print(
            "Error: google-ads library required. Install with: pip install google-ads",
            file=sys.stderr,
        )
        return None

    config = load_config()
    dev_token = config.get("ads_developer_token")
    customer_id = config.get("ads_customer_id", "").replace("-", "")
    login_customer_id = config.get("ads_login_customer_id", "").replace("-", "")
    oauth_client_path = config.get("oauth_client_path")

    if not dev_token:
        print(
            "Error: No Google Ads developer token configured. "
            "Add 'ads_developer_token' to ~/.config/claude-seo/google-api.json. "
            "Get a token at: https://ads.google.com/aw/apicenter",
            file=sys.stderr,
        )
        return None

    if not customer_id:
        print(
            "Error: No Google Ads customer ID configured. "
            "Add 'ads_customer_id' (format: 123-456-7890) to config.",
            file=sys.stderr,
        )
        return None

    try:
        # Build from dict configuration
        ads_config = {
            "developer_token": dev_token,
            "use_proto_plus": True,
        }
        if login_customer_id:
            ads_config["login_customer_id"] = login_customer_id

        # Try to use OAuth token if available
        token_path = os.path.expanduser("~/.config/claude-seo/oauth-token.json")
        if os.path.exists(token_path):
            with open(token_path) as f:
                token_data = json.load(f)
            if oauth_client_path:
                with open(os.path.expanduser(oauth_client_path)) as f:
                    client_data = json.load(f)
                client_info = client_data.get("web", client_data.get("installed", {}))
                ads_config["client_id"] = client_info.get("client_id")
                ads_config["client_secret"] = client_info.get("client_secret")
                ads_config["refresh_token"] = token_data.get("refresh_token")

        client = GoogleAdsClient.load_from_dict(ads_config)
        return client, customer_id

    except Exception as e:
        print(f"Error building Google Ads client: {e}", file=sys.stderr)
        return None


def generate_keyword_ideas(
    seed_keywords: list,
    language_id: str = "1000",
    location_id: str = "2840",
    limit: int = 50,
) -> dict:
    """
    Generate keyword ideas from seed keywords.

    Args:
        seed_keywords: List of seed keyword strings.
        language_id: Language ID (1000 = English).
        location_id: Location ID (2840 = United States).
        limit: Max results.

    Returns:
        Dictionary with keyword ideas and metrics.
    """
    result = {
        "seed_keywords": seed_keywords,
        "ideas": [],
        "error": None,
    }

    client_data = _build_ads_client()
    if not client_data:
        result["error"] = "Could not build Google Ads client. Check config."
        return result

    client, customer_id = client_data

    try:
        kp_service = client.get_service("KeywordPlanIdeaService")
        request = client.get_type("GenerateKeywordIdeasRequest")
        request.customer_id = customer_id
        request.language = f"languageConstants/{language_id}"
        request.geo_target_constants.append(f"geoTargetConstants/{location_id}")
        request.keyword_plan_network = client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
        request.keyword_seed.keywords.extend(seed_keywords)

        response = kp_service.generate_keyword_ideas(request=request)

        for idea in response.results:
            metrics = idea.keyword_idea_metrics
            monthly_volumes = []
            for mv in metrics.monthly_search_volumes:
                monthly_volumes.append({
                    "year": mv.year,
                    "month": mv.month,
                    "volume": mv.monthly_searches,
                })

            result["ideas"].append({
                "keyword": idea.text,
                "avg_monthly_searches": metrics.avg_monthly_searches,
                "competition": metrics.competition.name if metrics.competition else "UNSPECIFIED",
                "competition_index": metrics.competition_index,
                "low_top_of_page_bid": metrics.low_top_of_page_bid_micros / 1_000_000 if metrics.low_top_of_page_bid_micros else None,
                "high_top_of_page_bid": metrics.high_top_of_page_bid_micros / 1_000_000 if metrics.high_top_of_page_bid_micros else None,
                "monthly_volumes": monthly_volumes[-12:] if monthly_volumes else [],
            })

            if len(result["ideas"]) >= limit:
                break

        # Sort by volume descending
        result["ideas"].sort(key=lambda k: k.get("avg_monthly_searches", 0) or 0, reverse=True)

    except GoogleAdsException as e:
        errors = [err.message for err in e.failure.errors]
        result["error"] = f"Google Ads API error: {'; '.join(errors)}"
    except Exception as e:
        result["error"] = f"Keyword Planner error: {e}"

    return result


def get_keyword_volumes(
    keywords: list,
    language_id: str = "1000",
    location_id: str = "2840",
) -> dict:
    """
    Get search volume for specific keywords.

    Args:
        keywords: List of keywords to check.
        language_id: Language ID.
        location_id: Location ID.

    Returns:
        Dictionary with keyword metrics.
    """
    result = {
        "keywords": [],
        "error": None,
    }

    client_data = _build_ads_client()
    if not client_data:
        result["error"] = "Could not build Google Ads client."
        return result

    client, customer_id = client_data

    try:
        kp_service = client.get_service("KeywordPlanIdeaService")
        request = client.get_type("GenerateKeywordHistoricalMetricsRequest")
        request.customer_id = customer_id
        request.keywords.extend(keywords)
        request.language = f"languageConstants/{language_id}"
        request.geo_target_constants.append(f"geoTargetConstants/{location_id}")
        request.keyword_plan_network = client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH

        response = kp_service.generate_keyword_historical_metrics(request=request)

        for kw_result in response.results:
            metrics = kw_result.keyword_metrics
            result["keywords"].append({
                "keyword": kw_result.text,
                "avg_monthly_searches": metrics.avg_monthly_searches,
                "competition": metrics.competition.name if metrics.competition else "UNSPECIFIED",
                "competition_index": metrics.competition_index,
                "low_top_of_page_bid": metrics.low_top_of_page_bid_micros / 1_000_000 if metrics.low_top_of_page_bid_micros else None,
                "high_top_of_page_bid": metrics.high_top_of_page_bid_micros / 1_000_000 if metrics.high_top_of_page_bid_micros else None,
            })

    except GoogleAdsException as e:
        errors = [err.message for err in e.failure.errors]
        result["error"] = f"Google Ads API error: {'; '.join(errors)}"
    except Exception as e:
        result["error"] = f"Keyword volume error: {e}"

    return result


def main():
    parser = argparse.ArgumentParser(
        description="Google Ads Keyword Planner - SEO keyword research"
    )
    parser.add_argument(
        "command",
        choices=["ideas", "volume"],
        help="Command: ideas (keyword suggestions), volume (search volume lookup)",
    )
    parser.add_argument("keywords", help="Seed keyword(s), comma-separated for volume")
    parser.add_argument("--limit", type=int, default=50, help="Max results for ideas (default: 50)")
    parser.add_argument("--language", default="1000", help="Language ID (default: 1000 = English)")
    parser.add_argument("--location", default="2840", help="Location ID (default: 2840 = US)")
    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")

    args = parser.parse_args()

    if args.command == "ideas":
        seeds = [k.strip() for k in args.keywords.split(",")]
        result = generate_keyword_ideas(seeds, language_id=args.language, location_id=args.location, limit=args.limit)
    elif args.command == "volume":
        kws = [k.strip() for k in args.keywords.split(",")]
        result = get_keyword_volumes(kws, language_id=args.language, location_id=args.location)

    if result.get("error"):
        print(f"Error: {result['error']}", file=sys.stderr)
        if not args.json:
            sys.exit(1)

    if args.json:
        print(json.dumps(result, indent=2, default=str))
    else:
        if args.command == "ideas":
            print(f"=== Keyword Ideas ===")
            for i, idea in enumerate(result.get("ideas", [])[:20], 1):
                vol = idea.get("avg_monthly_searches", "?")
                comp = idea.get("competition", "?")
                bid_low = idea.get("low_top_of_page_bid")
                bid_high = idea.get("high_top_of_page_bid")
                bid_str = f"${bid_low:.2f}-${bid_high:.2f}" if bid_low and bid_high else "N/A"
                print(f"  {i:2d}. {idea['keyword']:40s} | Vol: {vol:>8} | Comp: {comp:8s} | CPC: {bid_str}")
        elif args.command == "volume":
            print(f"=== Keyword Volumes ===")
            for kw in result.get("keywords", []):
                vol = kw.get("avg_monthly_searches", "?")
                comp = kw.get("competition", "?")
                print(f"  {kw['keyword']:40s} | Vol: {vol:>8} | Comp: {comp}")


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: 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