The-AI-Directory-Company/agents-and-skills / skills/discovery-gseo
discovery-gseo
VerifiedFind, evaluate, and prioritize keyword and content opportunities for both search engine ranking and AI platform citation — using live browser automation, SERP analysis, competitor intelligence, community listening, and GEO-aware scoring to produce a prioritized content plan that drives traffic and AI visibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.2 KB |
| references/browser-automation-guide.md | markdown | 15.4 KB |
| references/community-listening.md | markdown | 7.9 KB |
| references/competitor-intelligence.md | markdown | 8.3 KB |
| references/evaluation-and-scoring.md | markdown | 16.0 KB |
| references/keyword-expansion.md | markdown | 11.7 KB |
| references/seed-generation.md | markdown | 8.1 KB |
| scripts/analyze-serp-live.py | script | 8.9 KB |
| scripts/build-topic-clusters.py | script | 7.6 KB |
| scripts/classify-intent-live.py | script | 8.0 KB |
| scripts/competitor-gap-analysis.py | script | 5.3 KB |
| scripts/evaluate-keywords.py | script | 7.1 KB |
| scripts/extract-paa.py | script | 6.4 KB |
| scripts/find-quick-wins.py | script | 7.0 KB |
| scripts/harvest-autocomplete.py | script | 7.9 KB |
| scripts/prioritize-opportunities.py | script | 9.2 KB |
| scripts/probe-ai-discovery.py | script | 5.5 KB |
| scripts/scrape-community-keywords.py | script | 6.8 KB |
| scripts/scrape-related-searches.py | script | 5.9 KB |
scripts/build-topic-clusters.py
View on GitHub#!/usr/bin/env python3
"""
build-topic-clusters.py — Group keywords by semantic similarity, identify pillars, generate cluster map.
Pure local processing — no external tools required. Takes an evaluated keyword list
and groups keywords into topic clusters, identifies pillar candidates, assigns
supporting keywords, and generates an internal link topology. Includes GEO citation
mapping to prioritize content creation within each cluster.
Usage:
python3 build-topic-clusters.py --keywords evaluated-keywords.json
python3 build-topic-clusters.py --keywords evaluated-keywords.json --min-cluster-size 3
AI Agent Usage:
This script runs locally. No external API calls needed.
1. Load evaluated keyword data (JSON from evaluate-keywords.py)
2. Extract root topics from each keyword (strip modifiers: best, free, how to, etc.)
3. Group keywords sharing the same root topic
4. Merge near-duplicate groups (overlapping root topics)
5. Per group: identify pillar (highest volume, broadest scope)
6. Assign remaining keywords as supports or H2 sections
7. Apply "own page" test: distinct intent + deep enough for 800+ words + SERP shows standalone pages
8. GEO citation mapping: rank supports by GEO score, highest-GEO created first
9. Generate internal link topology: pillar ↔ supports, related supports ↔ supports
"""
import argparse
import json
import sys
import re
from collections import defaultdict
# Modifier words to strip when extracting root topics
MODIFIERS = [
"best", "top", "free", "cheap", "affordable", "premium",
"how to", "what is", "why", "when", "where",
"guide", "tutorial", "tips", "examples", "template",
"alternative", "vs", "versus", "comparison", "review",
"for beginners", "for freelancers", "for small business",
"online", "software", "tool", "app", "platform", "service",
]
def extract_root_topic(keyword):
"""Extract the root topic from a keyword by stripping common modifiers."""
kw = keyword.lower().strip()
for mod in sorted(MODIFIERS, key=len, reverse=True):
kw = kw.replace(mod, "")
kw = re.sub(r"\s+", " ", kw).strip()
return kw if kw else keyword.lower().strip()
def group_keywords(keywords_data):
"""Group keywords by root topic similarity."""
groups = defaultdict(list)
for entry in keywords_data:
kw = entry.get("keyword", "")
root = extract_root_topic(kw)
groups[root].append(entry)
# Merge groups with very similar root topics
merged = {}
used = set()
roots = list(groups.keys())
for i, root1 in enumerate(roots):
if root1 in used:
continue
merged_group = list(groups[root1])
used.add(root1)
for j in range(i + 1, len(roots)):
root2 = roots[j]
if root2 in used:
continue
# Simple overlap check — if one root contains the other
if root1 in root2 or root2 in root1:
merged_group.extend(groups[root2])
used.add(root2)
# Use the shortest root as the group name
merged[root1] = merged_group
return merged
def identify_pillar(keywords_in_group):
"""Identify the pillar keyword (highest volume, broadest scope)."""
pillar = None
max_volume = -1
for entry in keywords_in_group:
vol = entry.get("volume_estimate")
if vol is None:
vol = 0
if isinstance(vol, str):
try:
vol = int(vol)
except ValueError:
vol = 0
if vol > max_volume:
max_volume = vol
pillar = entry
if pillar is None and keywords_in_group:
pillar = keywords_in_group[0]
return pillar
def build_clusters(keywords_data, min_cluster_size=2):
"""Build topic clusters from evaluated keyword data."""
groups = group_keywords(keywords_data)
clusters = []
unassigned = []
for root_topic, kw_entries in groups.items():
if len(kw_entries) < min_cluster_size:
unassigned.extend(kw_entries)
continue
pillar = identify_pillar(kw_entries)
supports = [e for e in kw_entries if e != pillar]
# Sort supports by GEO score descending for creation priority
supports.sort(
key=lambda x: (x.get("geo_score") or 0, x.get("volume_estimate") or 0),
reverse=True,
)
# Assign GEO priority (1 = create first)
for idx, s in enumerate(supports):
s["geo_priority"] = idx + 1
# Determine page type for each support
for s in supports:
intent = s.get("intent", "informational")
if intent == "commercial":
s["page_type"] = "comparison"
elif intent == "transactional":
s["page_type"] = "product page or tool"
else:
s["page_type"] = "guide"
cluster = {
"name": root_topic.title() if root_topic else "Uncategorized",
"pillar": {
"keyword": pillar.get("keyword", ""),
"volume": pillar.get("volume_estimate"),
"kd": pillar.get("kd_estimate"),
"geo_score": pillar.get("geo_score"),
},
"supports": [
{
"keyword": s.get("keyword", ""),
"volume": s.get("volume_estimate"),
"kd": s.get("kd_estimate"),
"geo_score": s.get("geo_score"),
"page_type": s.get("page_type", "guide"),
"geo_priority": s.get("geo_priority", 99),
}
for s in supports
],
"internal_links": {
"pillar_to_supports": True,
"supports_to_pillar": True,
"cross_links": [], # Agent identifies related supports to cross-link
},
}
clusters.append(cluster)
# Sort clusters by pillar volume descending
clusters.sort(
key=lambda c: c["pillar"].get("volume") or 0,
reverse=True,
)
return clusters, unassigned
def main():
parser = argparse.ArgumentParser(
description="Group keywords into topic clusters with pillar/support assignments."
)
parser.add_argument(
"--keywords",
type=str,
required=True,
help="Path to JSON file from evaluate-keywords.py",
)
parser.add_argument(
"--min-cluster-size",
type=int,
default=2,
help="Minimum keywords per cluster (default: 2)",
)
args = parser.parse_args()
try:
with open(args.keywords, "r") as f:
data = json.load(f)
except FileNotFoundError:
print(json.dumps({"error": f"Keywords file not found: {args.keywords}"}))
sys.exit(1)
except json.JSONDecodeError:
print(json.dumps({"error": "Invalid JSON in keywords file."}))
sys.exit(1)
# Support both raw list and evaluate-keywords.py output format
if isinstance(data, list):
keywords_data = data
elif isinstance(data, dict) and "keywords" in data:
keywords_data = data["keywords"]
else:
print(json.dumps({"error": "Unexpected JSON format. Expected list or {keywords: [...]}"}))
sys.exit(1)
clusters, unassigned = build_clusters(keywords_data, args.min_cluster_size)
total_assigned = sum(1 + len(c["supports"]) for c in clusters)
result = {
"total_clusters": len(clusters),
"total_keywords_assigned": total_assigned,
"clusters": clusters,
"unassigned_keywords": len(unassigned),
}
print(json.dumps(result, indent=2))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |