@opendirectory.dev/skills 0.1.0

package/skills/google-trends-api-skills/google-trends-api/scripts/discover_keywords.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+"""
+Google Trends Keyword Discovery Script
+
+Discovers trending keywords and related topics for a given query using SerpApi.
+Designed for SEO keyword research before blog generation.
+
+Usage:
+    python discover_keywords.py "your topic"
+    python discover_keywords.py "your topic" --geo US --date "today 3-m"
+    python discover_keywords.py "your topic" --full  # includes timeseries validation
+
+Requirements:
+    pip install requests
+
+Environment:
+    SERPAPI_KEY - your SerpApi API key (required)
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:
+    print("Error: 'requests' package required. Install with: pip install requests")
+    sys.exit(1)
+
+API_BASE = "https://serpapi.com/search"
+CACHE_DIR = Path.home() / ".cache" / "google-trends-api"
+CACHE_DAYS = 7
+
+
+def get_api_key():
+    key = os.environ.get("SERPAPI_KEY")
+    if not key:
+        print("Error: SERPAPI_KEY environment variable not set.")
+        print("Get a free key at https://serpapi.com/ (250 searches/month)")
+        sys.exit(1)
+    return key
+
+
+def get_cache_path(query, data_type, geo, date):
+    safe_name = f"{query}_{data_type}_{geo}_{date}".replace(" ", "_").replace("/", "_")
+    return CACHE_DIR / f"{safe_name}.json"
+
+
+def load_cache(cache_path):
+    if not cache_path.exists():
+        return None
+    try:
+        data = json.loads(cache_path.read_text(encoding="utf-8"))
+        cached_at = datetime.fromisoformat(data.get("_cached_at", "2000-01-01"))
+        if datetime.now() - cached_at < timedelta(days=CACHE_DAYS):
+            return data
+    except (json.JSONDecodeError, ValueError):
+        pass
+    return None
+
+
+def save_cache(cache_path, data):
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    data["_cached_at"] = datetime.now().isoformat()
+    cache_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def query_trends(query, data_type, api_key, geo="", date="today 3-m"):
+    cache_path = get_cache_path(query, data_type, geo, date)
+    cached = load_cache(cache_path)
+    if cached:
+        print(f"  [cached] {data_type}")
+        return cached
+
+    params = {
+        "engine": "google_trends",
+        "q": query,
+        "data_type": data_type,
+        "date": date,
+        "api_key": api_key,
+    }
+    if geo:
+        params["geo"] = geo
+
+    print(f"  [api call] {data_type}...")
+    resp = requests.get(API_BASE, params=params, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+
+    if data.get("search_metadata", {}).get("status") != "Success":
+        error = data.get("error", "Unknown error")
+        print(f"  [error] {data_type}: {error}")
+        return None
+
+    save_cache(cache_path, data)
+    return data
+
+
+def extract_keywords(related_queries):
+    """Extract and categorize keywords from RELATED_QUERIES response."""
+    if not related_queries:
+        return {"breakout": [], "high_growth": [], "moderate": [], "long_tail": [], "top": []}
+
+    rq = related_queries.get("related_queries", {})
+    rising = rq.get("rising", [])
+    top = rq.get("top", [])
+
+    question_words = ("how", "what", "why", "when", "where", "which", "can", "is", "does", "should")
+
+    breakout = []
+    high_growth = []
+    moderate = []
+    long_tail = []
+
+    for item in rising:
+        query = item.get("query", "")
+        formatted = item.get("formatted_value", "")
+
+        if formatted == "Breakout":
+            breakout.append({"query": query, "growth": "Breakout (5000%+)"})
+        elif "%" in formatted:
+            pct = int(formatted.replace("+", "").replace("%", "").replace(",", ""))
+            entry = {"query": query, "growth": formatted}
+            if pct >= 100:
+                high_growth.append(entry)
+            elif pct >= 50:
+                moderate.append(entry)
+
+        if query.lower().startswith(question_words):
+            long_tail.append(query)
+
+    # Also check top queries for long-tail
+    for item in top:
+        query = item.get("query", "")
+        if query.lower().startswith(question_words) and query not in long_tail:
+            long_tail.append(query)
+
+    top_kws = [{"query": item["query"], "score": item.get("value", 0)} for item in top[:10]]
+
+    return {
+        "breakout": breakout,
+        "high_growth": high_growth,
+        "moderate": moderate,
+        "long_tail": long_tail,
+        "top": top_kws,
+    }
+
+
+def extract_topics(related_topics):
+    """Extract topics from RELATED_TOPICS response."""
+    if not related_topics:
+        return {"rising": [], "top": []}
+
+    rt = related_topics.get("related_topics", {})
+
+    rising = [
+        {"title": item["topic"]["title"], "type": item["topic"].get("type", "Topic"),
+         "growth": item.get("formatted_value", "")}
+        for item in rt.get("rising", [])
+        if "topic" in item
+    ]
+
+    top = [
+        {"title": item["topic"]["title"], "type": item["topic"].get("type", "Topic"),
+         "score": item.get("extracted_value", 0)}
+        for item in rt.get("top", [])
+        if "topic" in item
+    ]
+
+    return {"rising": rising[:10], "top": top[:10]}
+
+
+def check_trend_direction(timeseries_data):
+    """Analyze TIMESERIES data to determine if trend is rising or falling."""
+    if not timeseries_data:
+        return None
+
+    timeline = timeseries_data.get("interest_over_time", {}).get("timeline_data", [])
+    if len(timeline) < 4:
+        return None
+
+    values = [entry["values"][0]["extracted_value"] for entry in timeline if entry.get("values")]
+    if not values:
+        return None
+
+    midpoint = len(values) // 2
+    first_half_avg = sum(values[:midpoint]) / midpoint
+    second_half_avg = sum(values[midpoint:]) / (len(values) - midpoint)
+
+    if second_half_avg > first_half_avg * 1.1:
+        direction = "RISING"
+    elif second_half_avg < first_half_avg * 0.9:
+        direction = "DECLINING"
+    else:
+        direction = "STABLE"
+
+    return {
+        "direction": direction,
+        "early_avg": round(first_half_avg, 1),
+        "recent_avg": round(second_half_avg, 1),
+        "change_pct": round(((second_half_avg - first_half_avg) / max(first_half_avg, 1)) * 100, 1),
+    }
+
+
+def select_primary_keyword(keywords, original_query):
+    """Select the best primary keyword for blog targeting."""
+    if keywords["breakout"]:
+        return keywords["breakout"][0]["query"], "BREAKOUT"
+    if keywords["high_growth"]:
+        return keywords["high_growth"][0]["query"], "HIGH_GROWTH"
+    if keywords["top"]:
+        return keywords["top"][0]["query"], "TOP"
+    return original_query, "ORIGINAL"
+
+
+def print_report(query, keywords, topics, trend=None):
+    """Print a formatted keyword research report."""
+    primary, priority = select_primary_keyword(keywords, query)
+
+    print("\n" + "=" * 60)
+    print(f"  KEYWORD RESEARCH REPORT: {query}")
+    print("=" * 60)
+
+    print(f"\n  PRIMARY KEYWORD: {primary}")
+    print(f"  PRIORITY LEVEL:  {priority}")
+
+    if keywords["breakout"]:
+        print(f"\n  BREAKOUT KEYWORDS (5000%+ growth):")
+        for kw in keywords["breakout"]:
+            print(f"    >>> {kw['query']} — {kw['growth']}")
+
+    if keywords["high_growth"]:
+        print(f"\n  HIGH-GROWTH KEYWORDS (100%+):")
+        for kw in keywords["high_growth"]:
+            print(f"    >> {kw['query']} — {kw['growth']}")
+
+    if keywords["moderate"]:
+        print(f"\n  MODERATE-GROWTH KEYWORDS (50-99%):")
+        for kw in keywords["moderate"]:
+            print(f"    > {kw['query']} — {kw['growth']}")
+
+    if keywords["long_tail"]:
+        print(f"\n  LONG-TAIL KEYWORDS (question-based):")
+        for q in keywords["long_tail"][:8]:
+            print(f"    ? {q}")
+
+    if keywords["top"]:
+        print(f"\n  TOP QUERIES (by popularity):")
+        for kw in keywords["top"][:5]:
+            print(f"    - {kw['query']} (score: {kw['score']})")
+
+    if topics["rising"]:
+        print(f"\n  RISING TOPICS (use as H2 headings):")
+        for t in topics["rising"][:5]:
+            print(f"    ^ {t['title']} — {t['growth']}")
+
+    if topics["top"]:
+        print(f"\n  TOP TOPICS:")
+        for t in topics["top"][:5]:
+            print(f"    - {t['title']} (score: {t['score']})")
+
+    if trend:
+        arrow = {"RISING": "^", "DECLINING": "v", "STABLE": "="}
+        print(f"\n  TREND DIRECTION: {arrow.get(trend['direction'], '?')} {trend['direction']}")
+        print(f"    Early avg: {trend['early_avg']} -> Recent avg: {trend['recent_avg']} ({trend['change_pct']:+}%)")
+
+    # Blog structure suggestion
+    h2_topics = [t["title"] for t in (topics["rising"] + topics["top"])[:5]]
+    h3_questions = keywords["long_tail"][:8]
+
+    print(f"\n  SUGGESTED BLOG STRUCTURE:")
+    print(f"    Title: {primary} — Complete Guide {datetime.now().year}")
+    if h2_topics:
+        for i, topic in enumerate(h2_topics, 1):
+            print(f"    H2 [{i}]: {topic}")
+            matching = [q for q in h3_questions if any(word in q.lower() for word in topic.lower().split())]
+            for q in matching[:2]:
+                print(f"      H3: {q}")
+    print()
+
+    print("=" * 60)
+    return {
+        "primary_keyword": primary,
+        "priority": priority,
+        "keywords": keywords,
+        "topics": topics,
+        "trend": trend,
+        "h2_suggestions": h2_topics,
+        "h3_suggestions": h3_questions,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Discover trending keywords via Google Trends")
+    parser.add_argument("query", help="The topic to research")
+    parser.add_argument("--geo", default="", help="Geographic filter (e.g., US, GB, US-CA)")
+    parser.add_argument("--date", default="today 3-m", help="Time range (default: today 3-m)")
+    parser.add_argument("--full", action="store_true", help="Include timeseries validation (uses extra API credit)")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    parser.add_argument("--no-cache", action="store_true", help="Skip cache, force fresh API calls")
+    args = parser.parse_args()
+
+    if args.no_cache:
+        global CACHE_DAYS
+        CACHE_DAYS = 0
+
+    api_key = get_api_key()
+
+    print(f"\nResearching: \"{args.query}\"")
+    print(f"Region: {args.geo or 'Worldwide'} | Date: {args.date}")
+    print("-" * 40)
+
+    # Required calls (2 API credits)
+    rq_data = query_trends(args.query, "RELATED_QUERIES", api_key, args.geo, args.date)
+    rt_data = query_trends(args.query, "RELATED_TOPICS", api_key, args.geo, args.date)
+
+    keywords = extract_keywords(rq_data)
+    topics = extract_topics(rt_data)
+
+    # Optional: trend validation (1 extra API credit)
+    trend = None
+    if args.full:
+        ts_data = query_trends(args.query, "TIMESERIES", api_key, args.geo, "today 12-m")
+        trend = check_trend_direction(ts_data)
+
+    if args.json:
+        result = {
+            "query": args.query,
+            "primary_keyword": select_primary_keyword(keywords, args.query)[0],
+            "priority": select_primary_keyword(keywords, args.query)[1],
+            "keywords": keywords,
+            "topics": topics,
+            "trend": trend,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print_report(args.query, keywords, topics, trend)
+
+
+if __name__ == "__main__":
+    main()

package/skills/google-trends-api-skills/seo-keyword-research/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: seo-keyword-research
+description: SEO keyword research workflow for blog generation using Google Trends data. Use when writing blog posts, planning content calendars, or optimizing articles for search engines. Finds breakout keywords, builds content structure, and generates SEO-optimized blog outlines targeting tech and developer audiences.
+license: MIT
+compatibility: Requires the google-trends-api skill (or direct SerpApi access with SERPAPI_KEY). Designed for Claude Code and similar AI coding agents.
+metadata:
+  author: farizanjum
+  version: "2.0"
+  domain: tech-developer-blogs
+allowed-tools: Bash(python:*) Bash(curl:*) Read
+---
+
+# SEO Keyword Research Skill
+
+Find trending, high-opportunity keywords BEFORE writing blog content. This skill turns generic blog topics into SEO-optimized content that ranks.
+
+## When to Use
+
+- User asks to write a blog post or article
+- User wants keyword research for a topic
+- User needs a content calendar or content plan
+- User wants to optimize existing content for SEO
+- Any blog generation task for a tech/developer-focused audience
+
+## Core Principle
+
+**Always research keywords BEFORE generating blog content.**
+
+```
+BAD:  Write blog -> Hope it ranks -> Usually doesn't
+GOOD: Research keywords -> Find breakout opportunity -> Write optimized blog -> Ranks well
+```
+
+## Keyword Priority System
+
+When analyzing Google Trends RELATED_QUERIES results, prioritize keywords in this order:
+
+### 1. Breakout Keywords — HIGHEST priority
+- `formatted_value: "Breakout"` = 5000%+ growth
+- Very low competition (trend is new)
+- Use as PRIMARY blog keyword
+- Create content IMMEDIATELY (first-mover advantage)
+
+### 2. High-Growth Keywords — VERY HIGH priority
+- `formatted_value: "+100%"` or higher
+- Low to moderate competition
+- Use as primary or strong secondary keyword
+- Create content within 2-4 weeks
+
+### 3. Moderate-Growth Keywords — HIGH priority
+- `formatted_value: "+50%"` to `"+99%"`
+- Moderate competition
+- Use as secondary keywords in body content
+
+### 4. Long-Tail Keywords — STRATEGIC priority
+- Question-based queries (how, what, why, when, where)
+- Low competition, high conversion
+- Use as H3 headings — target featured snippets and voice search
+
+### 5. Established Keywords — MODERATE priority
+- Top queries with stable interest, high competition
+- Use in body content, not as primary target
+
+## SEO Research Workflow
+
+### Step 1: Keyword Discovery (1 API call — REQUIRED)
+
+Query `RELATED_QUERIES` with the user's blog topic:
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=USER_TOPIC&data_type=RELATED_QUERIES&date=today+3-m&api_key=$SERPAPI_KEY"
+```
+
+From the response, extract:
+- **Breakout keywords** → candidate primary keywords
+- **High-growth keywords** (+100%) → secondary candidates
+- **Question-based queries** → H3 headings and featured snippet targets
+
+Select the primary keyword:
+1. First breakout keyword (if any)
+2. Else first high-growth keyword
+3. Else top query by score
+
+### Step 2: Content Structure (1 API call — REQUIRED)
+
+Query `RELATED_TOPICS` with the same topic:
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=USER_TOPIC&data_type=RELATED_TOPICS&date=today+3-m&api_key=$SERPAPI_KEY"
+```
+
+Extract topic titles from rising + top results. These become your H2 section headings (pick 3-5).
+
+### Step 3: Trend Validation (1 API call — OPTIONAL)
+
+Only if choosing between multiple candidate keywords or validating viability:
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=KEYWORD&data_type=TIMESERIES&date=today+12-m&api_key=$SERPAPI_KEY"
+```
+
+Compare recent 2-month average vs. earlier 2-month average. If recent > earlier, trend is rising — proceed. If declining, consider a different keyword.
+
+### Step 4: Generate Blog Outline
+
+Build the outline using this structure:
+
+```
+Title: [Primary Keyword] — [Benefit/Number] [Year]
+  (max 60 characters, must include primary keyword)
+
+Meta Description: (150-160 chars, primary + 1-2 secondary keywords)
+
+# [H1 — same as or variation of title]
+
+## Introduction (150 words)
+  - Primary keyword in first 100 words
+  - Hook with a problem or question
+  - Preview what they'll learn
+
+## [H2: Related Topic 1 from Step 2]
+### [H3: Long-tail question from Step 1]
+  Content answering the question (150-200 words)
+### [H3: Another long-tail question]
+  Content (150-200 words)
+
+## [H2: Related Topic 2]
+### [H3: Long-tail question]
+### [H3: Long-tail question]
+
+## [H2: Related Topic 3]
+### [H3: Long-tail question]
+### [H3: Long-tail question]
+
+## Conclusion (100 words)
+  - Summarize key points
+  - Primary keyword mentioned once
+  - Call-to-action
+
+Target: 1500-2500 words total
+```
+
+## Keyword Placement Rules
+
+| Location | Rule |
+|----------|------|
+| Title | Include primary keyword, max 60 chars |
+| H1 | Same as title or slight variation |
+| H2 headings (3-5) | Use related topics, natural language |
+| H3 headings (8-12) | Use long-tail keywords, question format |
+| First paragraph | Primary keyword in first 100 words |
+| Body content | Primary keyword 1-2% density, secondary 0.5-1% |
+| Conclusion | Primary keyword once |
+| Meta description | Primary + 1-2 secondary, 150-160 chars |
+
+**Never keyword-stuff.** Content must read naturally. Google penalizes unnatural repetition.
+
+## Quality Checklist
+
+Before generating the blog, verify:
+
+- [ ] Found at least 1 breakout or +100% keyword (or justified using established keyword)
+- [ ] Have 3-5 H2 topics from RELATED_TOPICS
+- [ ] Have long-tail keywords for H3 headings
+- [ ] Primary keyword is specific enough to rank for
+- [ ] Blog structure follows the outline template above
+- [ ] Meta description is written (150-160 chars)
+- [ ] Target length is 1500-2500 words
+
+If no breakout or high-growth keywords exist for the topic, inform the user that SEO opportunity is limited and suggest alternative angles or related topics that do have growth.
+
+## Budget Awareness
+
+**Free tier: 250 searches/month**
+
+| Strategy | Calls/Blog | Monthly Capacity |
+|----------|-----------|-----------------|
+| Minimal (recommended) | 2 | 125 blogs |
+| Standard | 3 | 83 blogs |
+| Complete | 4 | 62 blogs |
+
+Default to 2 calls (RELATED_QUERIES + RELATED_TOPICS). Only add TIMESERIES or GEO_MAP when specifically needed.
+
+## Common Mistakes to Avoid
+
+1. **Skipping research** — writing without checking trends misses breakout opportunities
+2. **Ignoring breakout keywords** — using a generic term when a breakout variant exists
+3. **Keyword stuffing** — repeating keywords unnaturally; keep density at 1-2%
+4. **No long-tail keywords** — missing featured snippet and voice search opportunities
+5. **Generic H2 headings** — always use RELATED_TOPICS data for section structure
+
+## Example Script
+
+For a complete working example, run:
+
+```bash
+python scripts/blog_seo_research.py "your blog topic"
+```
+
+See [scripts/blog_seo_research.py](scripts/blog_seo_research.py) for the implementation.
+
+## References
+
+- [references/keyword-placement-guide.md](references/keyword-placement-guide.md) — Detailed placement rules and examples
+- [references/tech-blog-examples.md](references/tech-blog-examples.md) — Real-world examples for tech/developer blogs

package/skills/google-trends-api-skills/seo-keyword-research/references/keyword-placement-guide.md

@@ -0,0 +1,89 @@
+# Keyword Placement Guide
+
+Detailed rules and examples for placing SEO keywords in blog content.
+
+## Title (max 60 characters)
+
+**Format**: `[Primary Keyword] — [Benefit/Number] [Year]`
+
+**Good examples**:
+- "Kubernetes Alternatives — 10 Best Options in 2026"
+- "AI Code Review Tools — Complete Developer Guide"
+- "Rust vs Go — Performance Comparison for Backend"
+
+**Bad examples**:
+- "Everything You Need to Know About Kubernetes" (no keyword focus)
+- "Top Kubernetes Kubernetes Tools Kubernetes Guide" (stuffed)
+
+## H1 Heading
+
+Same as title or a slight variation. One H1 per page.
+
+## H2 Headings (3-5 per article)
+
+Source these from RELATED_TOPICS API results. Use natural language.
+
+**Example**: If researching "kubernetes deployment", RELATED_TOPICS might return:
+- "Container Orchestration" -> H2: Container Orchestration with Kubernetes
+- "Docker" -> H2: Docker vs Kubernetes for Deployment
+- "Helm" -> H2: Using Helm Charts for Kubernetes Deployment
+- "CI/CD" -> H2: CI/CD Pipelines with Kubernetes
+
+## H3 Headings (2-3 per H2 section)
+
+Source from RELATED_QUERIES long-tail keywords. Prefer question format.
+
+**Example**: Under "Container Orchestration with Kubernetes":
+- H3: What Is Container Orchestration?
+- H3: How Does Kubernetes Handle Container Scaling?
+
+## First Paragraph
+
+Include primary keyword within the first 100 words. Make it natural.
+
+**Good**:
+> Looking for the best **kubernetes deployment** strategies? As container adoption grows, understanding how to deploy applications on Kubernetes has become essential for modern engineering teams.
+
+**Bad**:
+> Kubernetes deployment is important. If you want kubernetes deployment, you need to learn about kubernetes deployment strategies for your kubernetes deployment needs.
+
+## Body Content Density
+
+**Primary keyword**: 1-2% of total word count
+- 1500-word article = 15-30 natural mentions
+- Spread evenly, not clustered
+
+**Secondary keywords**: 0.5-1% each
+- Use 2-4 secondary keywords throughout
+
+**Semantic variations**: Use related terms naturally
+- "kubernetes deployment" -> also use "k8s deploy", "deploying on kubernetes", "container deployment"
+
+## Meta Description (150-160 characters)
+
+Include primary keyword + 1-2 secondary keywords. Make it compelling.
+
+**Good**:
+> Learn kubernetes deployment best practices. Covers Helm charts, CI/CD pipelines, container orchestration, and scaling strategies for production.
+
+**Bad**:
+> This article is about kubernetes. Read to learn more about kubernetes deployment.
+
+## Featured Snippet Optimization
+
+For each long-tail H3 keyword:
+1. Answer the question directly in 40-60 words immediately after the heading
+2. Use bullet points or numbered lists
+3. Provide a concise answer first, then expand
+
+**Example**:
+```markdown
+### What Is Container Orchestration?
+
+Container orchestration automates the deployment, scaling, networking,
+and management of containerized applications across clusters of machines.
+Tools like Kubernetes handle scheduling, load balancing, and self-healing,
+allowing teams to manage thousands of containers efficiently.
+
+In more detail, container orchestration solves several key challenges...
+```