@olives/devos 2.1.0

package/.agents/skills/seo-geo/scripts/competitor_gap.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Competitor keyword gap analysis using DataForSEO API
+Finds keywords where competitor ranks but you don't
+
+Usage: python3 scripts/competitor_gap.py "opc.dev" "claudemarketplaces.com" --limit 50
+"""
+import argparse
+from dataforseo_api import api_post, get_result, format_count
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Competitor keyword gap analysis")
+    parser.add_argument("my_domain", help="Your domain (without https://)")
+    parser.add_argument("competitor_domain", help="Competitor domain (without https://)")
+    parser.add_argument("--location", "-loc", type=int, default=2840,
+                        help="Location code (default: 2840 = US)")
+    parser.add_argument("--limit", "-l", type=int, default=50, 
+                        help="Max results (default: 50)")
+    args = parser.parse_args()
+
+    data = [{
+        "target1": args.my_domain,
+        "target2": args.competitor_domain,
+        "location_code": args.location,
+        "language_code": "en",
+        "intersections": False,  # Only show keywords where target2 ranks but target1 doesn't
+        "limit": args.limit
+    }]
+    
+    response = api_post("dataforseo_labs/google/domain_intersection/live", data)
+    results = get_result(response)
+    
+    print(f"my_domain: {args.my_domain}")
+    print(f"competitor_domain: {args.competitor_domain}")
+    print(f"location: {args.location}")
+    print()
+    
+    if results:
+        all_items = []
+        for result in results:
+            items = result.get("items", [])
+            if items:
+                all_items.extend(items)
+        
+        if not all_items:
+            print("No keyword gaps found")
+            return
+        
+        # Results show keywords where competitor ranks but you don't
+        print(f"keyword_gaps[{len(all_items)}]{{keyword,volume,difficulty,comp_position}}:")
+        for item in all_items:
+            kw_data = item.get("keyword_data", {})
+            keyword = kw_data.get("keyword", "N/A")
+            
+            # Get search volume from keyword_info
+            kw_info = kw_data.get("keyword_info", {})
+            volume = format_count(kw_info.get("search_volume", 0))
+            
+            # Get keyword difficulty
+            difficulty = kw_info.get("competition_level", "N/A")
+            
+            # Get competitor's ranking position
+            # When intersections=false, we get keywords where only second_domain (competitor) ranks
+            comp_element = item.get("second_domain_serp_element")
+            if comp_element and isinstance(comp_element, dict):
+                comp_pos = comp_element.get("rank_absolute", comp_element.get("rank_group", "N/A"))
+            else:
+                comp_pos = "N/A"
+            
+            print(f"  {keyword},{volume},{difficulty},{comp_pos}")
+    else:
+        print("No keyword gaps found")
+    
+    print()
+    print("Tip: Focus on keywords with high volume and low difficulty where competitor ranks in top 10")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/seo-geo/scripts/credential.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""
+Credential helper for DataForSEO API
+"""
+import os
+
+
+def get_dataforseo_credentials() -> tuple:
+    """Get DataForSEO login and password from environment"""
+    login = os.environ.get("DATAFORSEO_LOGIN")
+    password = os.environ.get("DATAFORSEO_PASSWORD")
+    return login, password

package/.agents/skills/seo-geo/scripts/dataforseo_api.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+DataForSEO API wrapper
+"""
+import urllib.request
+import urllib.parse
+import json
+import base64
+import sys
+from credential import get_dataforseo_credentials
+
+API_BASE = "https://api.dataforseo.com/v3"
+
+
+def api_post(endpoint: str, data: list) -> dict:
+    """Make POST request to DataForSEO API"""
+    login, password = get_dataforseo_credentials()
+    if not login or not password:
+        print("error: DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD not set", file=sys.stderr)
+        print("Run: export DATAFORSEO_LOGIN=your_login", file=sys.stderr)
+        print("     export DATAFORSEO_PASSWORD=your_password", file=sys.stderr)
+        sys.exit(1)
+    
+    url = f"{API_BASE}/{endpoint}"
+    auth = base64.b64encode(f"{login}:{password}".encode()).decode()
+    headers = {
+        "Authorization": f"Basic {auth}",
+        "Content-Type": "application/json"
+    }
+    
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(data).encode(),
+        headers=headers,
+        method="POST"
+    )
+    
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode()
+        print(f"error: HTTP {e.code} - {error_body}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def format_count(n) -> str:
+    """Format numbers (1234567 -> 1.2M)"""
+    if n is None:
+        return "0"
+    n = int(n)
+    if n >= 1_000_000_000:
+        return f"{n/1_000_000_000:.1f}B"
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n/1_000:.1f}K"
+    return str(n)
+
+
+def get_result(response: dict) -> list:
+    """Extract result from API response"""
+    if not response.get("tasks"):
+        return []
+    task = response["tasks"][0]
+    if task.get("status_code") != 20000:
+        print(f"error: {task.get('status_message', 'Unknown error')}", file=sys.stderr)
+        return []
+    return task.get("result", [])
+
+
+def print_keywords_list(keywords: list):
+    """Print list of keywords"""
+    print(f"keywords[{len(keywords)}]{{keyword,volume,difficulty}}:")
+    for kw in keywords:
+        keyword = kw.get("keyword", "N/A")
+        volume = format_count(kw.get("search_volume"))
+        difficulty = kw.get("keyword_difficulty", "N/A")
+        print(f"  {keyword},{volume},{difficulty}")
+
+
+def print_serp_list(items: list):
+    """Print SERP results"""
+    organic = [i for i in items if i.get("type") == "organic"]
+    print(f"serp[{len(organic)}]{{position,title,domain}}:")
+    for item in organic[:20]:
+        pos = item.get("rank_absolute", "N/A")
+        title = (item.get("title") or "")[:50]
+        domain = item.get("domain", "N/A")
+        print(f"  {pos},{title},{domain}")
+
+
+def print_backlinks_list(items: list):
+    """Print backlinks"""
+    print(f"backlinks[{len(items)}]{{from,to,rank,dofollow}}:")
+    for item in items:
+        url_from = (item.get("url_from") or "")[:50]
+        url_to = (item.get("url_to") or "")[:30]
+        rank = item.get("rank", "N/A")
+        dofollow = item.get("dofollow", False)
+        print(f"  {url_from},{url_to},{rank},{dofollow}")

package/.agents/skills/seo-geo/scripts/domain_overview.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+Domain overview using DataForSEO API
+Usage: python3 scripts/domain_overview.py "example.com"
+"""
+import argparse
+from dataforseo_api import api_post, get_result, format_count
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Domain overview")
+    parser.add_argument("domain", help="Target domain")
+    parser.add_argument("--location", "-loc", type=int, default=2840,
+                        help="Location code (default: 2840 = US)")
+    args = parser.parse_args()
+
+    data = [{
+        "target": args.domain,
+        "location_code": args.location,
+        "language_code": "en",
+        "limit": 1  # We only need overview metrics
+    }]
+    
+    response = api_post("dataforseo_labs/google/ranked_keywords/live", data)
+    results = get_result(response)
+    
+    print(f"domain: {args.domain}")
+    print(f"location: {args.location}")
+    
+    if results:
+        for result in results:
+            metrics = result.get("metrics", {})
+            if not metrics:
+                continue
+            organic = metrics.get("organic", {})
+            print(f"organic_keywords: {format_count(organic.get('count', 0))}")
+            print(f"organic_traffic: {format_count(organic.get('etv', 0))}")
+            print(f"top_3_positions: {organic.get('pos_1', 0) + organic.get('pos_2_3', 0)}")
+    else:
+        print("No results found")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/seo-geo/scripts/keyword_research.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+Keyword research using DataForSEO API
+Usage: python3 scripts/keyword_research.py "seo tools" --limit 20
+"""
+import argparse
+from dataforseo_api import api_post, get_result, print_keywords_list
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Keyword research")
+    parser.add_argument("keyword", help="Seed keyword")
+    parser.add_argument("--location", "-loc", type=int, default=2840,
+                        help="Location code (default: 2840 = US)")
+    parser.add_argument("--limit", "-l", type=int, default=20, help="Max results")
+    args = parser.parse_args()
+
+    data = [{
+        "keywords": [args.keyword],  # API requires 'keywords' array (up to 20)
+        "location_code": args.location,
+        "language_code": "en",
+        "limit": args.limit
+    }]
+    
+    response = api_post("keywords_data/google_ads/keywords_for_keywords/live", data)
+    results = get_result(response)
+    
+    print(f"keyword: {args.keyword}")
+    print(f"location: {args.location}")
+    
+    if results:
+        print_keywords_list(results[:args.limit])
+    else:
+        print("No results found")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/seo-geo/scripts/related_keywords.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+Related keywords from Google "searches related to" using DataForSEO API
+Get up to 4,680 keyword ideas from Google's related searches
+
+Usage: python3 scripts/related_keywords.py "AI agent" --depth 2 --limit 50
+"""
+import argparse
+from dataforseo_api import api_post, get_result, format_count
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Related keywords from Google")
+    parser.add_argument("keyword", help="Seed keyword")
+    parser.add_argument("--location", "-loc", type=int, default=2840,
+                        help="Location code (default: 2840 = US)")
+    parser.add_argument("--depth", "-d", type=int, default=1,
+                        help="Search depth 1-3 (default: 1, max keywords: depth^3 * 10)")
+    parser.add_argument("--limit", "-l", type=int, default=50, 
+                        help="Max results to display (default: 50)")
+    args = parser.parse_args()
+
+    # Validate depth
+    if args.depth < 1 or args.depth > 3:
+        print("Error: depth must be between 1 and 3")
+        return
+
+    data = [{
+        "keyword": args.keyword,
+        "location_code": args.location,
+        "language_code": "en",
+        "depth": args.depth,
+        "limit": 1000  # API limit, we'll filter in display
+    }]
+    
+    response = api_post("dataforseo_labs/google/related_keywords/live", data)
+    results = get_result(response)
+    
+    print(f"keyword: {args.keyword}")
+    print(f"location: {args.location}")
+    print(f"depth: {args.depth}")
+    print()
+    
+    if results:
+        keywords = []
+        for result in results:
+            items = result.get("items", [])
+            for item in items:
+                kw_data = item.get("keyword_data", {})
+                keyword = kw_data.get("keyword", item.get("keyword", ""))
+                volume = kw_data.get("search_volume", item.get("search_volume", 0))
+                difficulty = kw_data.get("keyword_difficulty", item.get("keyword_difficulty", "N/A"))
+                
+                if keyword:
+                    keywords.append({
+                        "keyword": keyword,
+                        "volume": volume if volume is not None else 0,
+                        "difficulty": difficulty
+                    })
+        
+        # Sort by volume desc
+        keywords.sort(key=lambda x: x["volume"], reverse=True)
+        
+        # Display limited results
+        display_keywords = keywords[:args.limit]
+        print(f"related_keywords[{len(display_keywords)} of {len(keywords)}]{{keyword,volume,difficulty}}:")
+        for kw in display_keywords:
+            keyword = kw["keyword"]
+            volume = format_count(kw["volume"])
+            difficulty = kw["difficulty"]
+            print(f"  {keyword},{volume},{difficulty}")
+        
+        if len(keywords) > args.limit:
+            print(f"\n... and {len(keywords) - args.limit} more keywords (use --limit to show more)")
+    else:
+        print("No related keywords found")
+    
+    print()
+    print("Tip: Higher depth finds more keywords but costs more API credits")
+    print(f"  Depth 1: ~10 keywords, Depth 2: ~100, Depth 3: ~1,000+")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/seo-geo/scripts/seo_audit.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+SEO audit script (no API required)
+Usage: python3 scripts/seo_audit.py "https://example.com"
+"""
+import argparse
+import urllib.request
+import urllib.parse
+import re
+import time
+import sys
+
+
+def fetch_url(url: str, timeout: int = 30) -> tuple:
+    """Fetch URL and return (content, headers, load_time)"""
+    try:
+        start = time.time()
+        req = urllib.request.Request(url, headers={"User-Agent": "SEO-Audit/1.0"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            content = resp.read().decode("utf-8", errors="ignore")
+            headers = dict(resp.headers)
+            load_time = time.time() - start
+            return content, headers, load_time
+    except Exception as e:
+        return None, None, None
+
+
+def extract_meta(html: str) -> dict:
+    """Extract meta tags from HTML"""
+    result = {}
+    
+    # Title
+    title_match = re.search(r"<title[^>]*>([^<]+)</title>", html, re.I)
+    result["title"] = title_match.group(1).strip() if title_match else None
+    
+    # Meta description
+    desc_match = re.search(r'<meta[^>]+name=["\']description["\'][^>]+content=["\']([^"\']+)["\']', html, re.I)
+    if not desc_match:
+        desc_match = re.search(r'<meta[^>]+content=["\']([^"\']+)["\'][^>]+name=["\']description["\']', html, re.I)
+    result["description"] = desc_match.group(1).strip() if desc_match else None
+    
+    # OG tags
+    og_match = re.search(r'<meta[^>]+property=["\']og:title["\']', html, re.I)
+    result["og_tags"] = bool(og_match)
+    
+    # JSON-LD
+    jsonld_count = len(re.findall(r'application/ld\+json', html, re.I))
+    result["jsonld_count"] = jsonld_count
+    
+    # H1 (handle inline tags like <br>)
+    h1_match = re.search(r"<h1[^>]*>(.*?)</h1>", html, re.I | re.DOTALL)
+    if h1_match:
+        h1_text = re.sub(r"<[^>]+>", " ", h1_match.group(1))  # Remove inner tags
+        h1_text = re.sub(r"\s+", " ", h1_text).strip()  # Normalize whitespace
+        result["h1"] = h1_text[:100]
+    else:
+        result["h1"] = None
+    
+    return result
+
+
+def check_robots(url: str) -> dict:
+    """Check robots.txt"""
+    parsed = urllib.parse.urlparse(url)
+    robots_url = f"{parsed.scheme}://{parsed.netloc}/robots.txt"
+    content, _, _ = fetch_url(robots_url)
+    
+    result = {"exists": False, "ai_bots": []}
+    if content:
+        result["exists"] = True
+        ai_bots = ["GPTBot", "PerplexityBot", "ClaudeBot", "anthropic-ai", "ChatGPT-User"]
+        for bot in ai_bots:
+            if bot.lower() in content.lower():
+                result["ai_bots"].append(bot)
+    return result
+
+
+def check_sitemap(url: str) -> bool:
+    """Check if sitemap.xml exists"""
+    parsed = urllib.parse.urlparse(url)
+    sitemap_url = f"{parsed.scheme}://{parsed.netloc}/sitemap.xml"
+    content, _, _ = fetch_url(sitemap_url)
+    if not content:
+        return False
+    # Check for common sitemap indicators
+    return "<urlset" in content.lower() or "<sitemapindex" in content.lower() or "<?xml" in content.lower()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="SEO audit")
+    parser.add_argument("url", help="URL to audit")
+    args = parser.parse_args()
+    
+    url = args.url
+    if not url.startswith("http"):
+        url = f"https://{url}"
+    
+    print(f"=== SEO Audit: {url} ===")
+    print()
+    
+    # Fetch page
+    content, headers, load_time = fetch_url(url)
+    if not content:
+        print("error: Could not fetch URL")
+        sys.exit(1)
+    
+    # Meta tags
+    print("## Meta Tags")
+    meta = extract_meta(content)
+    title = meta["title"]
+    print(f"title: {title[:60] if title else 'MISSING'}{'...' if title and len(title) > 60 else ''}")
+    print(f"title_length: {len(title) if title else 0} chars")
+    desc = meta["description"]
+    print(f"description: {desc[:80] if desc else 'MISSING'}{'...' if desc and len(desc) > 80 else ''}")
+    print(f"description_length: {len(desc) if desc else 0} chars")
+    print(f"og_tags: {'yes' if meta['og_tags'] else 'no'}")
+    print(f"h1: {meta['h1'] if meta['h1'] else 'MISSING'}")
+    print()
+    
+    # Schema
+    print("## Schema Markup")
+    print(f"json_ld_blocks: {meta['jsonld_count']}")
+    print()
+    
+    # Performance
+    print("## Performance")
+    print(f"load_time: {load_time:.2f}s")
+    print(f"status: {'good' if load_time < 3 else 'slow'}")
+    print()
+    
+    # robots.txt
+    print("## robots.txt")
+    robots = check_robots(url)
+    print(f"exists: {'yes' if robots['exists'] else 'no'}")
+    if robots["ai_bots"]:
+        print(f"ai_bots_mentioned: {', '.join(robots['ai_bots'])}")
+    else:
+        print("ai_bots_mentioned: none")
+    print()
+    
+    # Sitemap
+    print("## Sitemap")
+    has_sitemap = check_sitemap(url)
+    print(f"sitemap_xml: {'yes' if has_sitemap else 'no'}")
+    print()
+    
+    print("=== Audit Complete ===")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/seo-geo/scripts/serp_analysis.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""
+SERP analysis using DataForSEO API
+Usage: python3 scripts/serp_analysis.py "best seo tools" --depth 20
+"""
+import argparse
+from dataforseo_api import api_post, get_result, print_serp_list, format_count
+
+
+def main():
+    parser = argparse.ArgumentParser(description="SERP analysis")
+    parser.add_argument("keyword", help="Search keyword")
+    parser.add_argument("--location", "-loc", type=int, default=2840,
+                        help="Location code (default: 2840 = US)")
+    parser.add_argument("--depth", "-d", type=int, default=20, help="Search depth")
+    args = parser.parse_args()
+
+    data = [{
+        "keyword": args.keyword,
+        "location_code": args.location,
+        "language_code": "en",
+        "depth": args.depth
+    }]
+    
+    response = api_post("serp/google/organic/live/advanced", data)
+    results = get_result(response)
+    
+    print(f"keyword: {args.keyword}")
+    print(f"location: {args.location}")
+    
+    if results:
+        result = results[0]
+        print(f"total_results: {format_count(result.get('se_results_count'))}")
+        items = result.get("items", [])
+        print_serp_list(items)
+    else:
+        print("No results found")
+
+
+if __name__ == "__main__":
+    main()