gemoniq-seo

name	gemoniq-seo
description	Full-stack SEO and AEO (Answer Engine Optimization) toolkit. Use this whenever the user asks about: keyword research, search volume, keyword difficulty, competitor keyword gap, SERP analysis, top ranking pages, related keywords, content opportunities, AI search visibility, LLM citations, GEO, AEO, AI Overviews, ChatGPT/Perplexity/Claude visibility, getting cited by AI, content briefs, SEO briefs, AI-optimized content, schema markup, JSON-LD, FAQ schema, Article schema, HowTo schema, Product schema, structured data, robots.txt for AI bots, page extractability, or any combination of traditional SEO and AI search optimization. This skill runs DataForSEO API calls, fetches live pages, and generates structured data. All credentials are loaded from .secrets.json (or env vars) at script runtime.
license	MIT
metadata	{"version":"1.0.0"}

Gemoniq SEO + AEO Skill

A full-stack search optimization toolkit. Covers traditional SEO (ranking in Google) and AEO / GEO (getting cited by ChatGPT, Perplexity, Claude, Gemini, and Google AI Overviews) as one workflow.

Built by Gemoniq for our AI CMO. Portable to any Claude Code / Claude.ai / OpenClaw / ChatGPT agent runtime.

When to use this skill

Use it whenever the user asks about any of these:

SEO research

• "Keyword research for [topic / domain]"
• "Search volume for [phrase]"
• "Keyword difficulty of [phrase]"
• "What keywords do [competitor] rank for that we don't?"
• "Top 10 ranking pages for [query]"
• "Related keywords to [seed]"
• "Content opportunities in [niche]"

AEO / AI visibility

• "How visible are we in AI search?"
• "Do LLMs mention our brand?"
• "Is our content being cited by ChatGPT / Perplexity / AI Overviews?"
• "AEO audit for [domain]"
• "Why are we not in AI answers?"
• "How do we get cited by AI?"
• "Score this page for AI extractability"
• "Are we blocking AI bots in robots.txt?"

Content briefs

• "Write me a brief for [keyword]"
• "SEO brief for [topic]"
• "Outline an article that will rank and get cited by AI"

Schema markup

• "Generate Article / FAQ / HowTo / Product schema for [content]"
• "Add structured data to this page"
• "Validate this JSON-LD"

Before starting

Gather this context before running anything. Push back if it's missing:

1. Target market — country + language (e.g. United States / en, Sweden / sv). Scripts default to DATAFORSEO_LOCATION / DATAFORSEO_LANGUAGE which fall back to United States / en.
2. Seed — a topic, a client domain, or a competitor domain, depending on the task.
3. Goal — rank for something new? Close a gap vs a named competitor? Get cited by AI for specific queries? Write a single piece of content?
4. Budget awareness — DataForSEO is pay-per-call. For a full client onboarding (10 seeds × expansion + 3 competitor gaps + 20 SERP checks) budget ~$1-2 USD of API credit. Mention this before running something expensive.

Quick reference

Task	Script	Reference doc
Keyword ideas from a seed	scripts/keyword_research.py	references/seo-research.md
Competitor keyword gap	scripts/competitor_gap.py	references/seo-research.md
Live SERP for a query	scripts/serp_analysis.py	references/seo-research.md
Related keywords expansion	scripts/related_keywords.py	references/seo-research.md
Brand mentions in AI answers	scripts/ai_mentions.py	references/aeo-audit.md
Google AI Overview inspection	scripts/ai_overview_check.py	references/aeo-audit.md
Page extractability score	scripts/extractability_score.py	references/extractability-checklist.md
robots.txt AI bot access	scripts/robots_ai_check.py	references/ai-bots-robotstxt.md
Generate full content brief	scripts/generate_brief.py	references/brief-template.md
Generate JSON-LD schema	scripts/generate_schema.py	references/schema-cheatsheet.md
Validate JSON-LD	scripts/validate_schema.py	references/schema-cheatsheet.md

Credentials

This skill reads DataForSEO credentials from, in priority order:

1. CLI flags: --login / --password
2. Env vars: DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD
3. .secrets.json inside this skill folder (created by setup.py in the repo root)

Sign up at dataforseo.com to get credentials.

If none of those are set, any DataForSEO call will error with a clear message. The three local scripts that don't need DataForSEO (extractability_score.py, robots_ai_check.py, generate_schema.py, validate_schema.py) work without any credentials at all.

Runtime dependencies

Scripts auto-install missing Python packages on first run using pip in the runtime sandbox. The only packages needed are:

• requests — HTTP calls
• beautifulsoup4 + lxml — HTML parsing for extractability scoring

If auto-install fails (locked-down runtime, no network to PyPI), install them manually before running:

pip install requests beautifulsoup4 lxml

Workflows

Workflow A: full SEO + AEO audit for a new client

1. Seed list — ask the client for 5-10 seed terms that describe what they do.
2. Expand — scripts/keyword_research.py --seed <term> --limit 100 for each seed. Save each output.
3. Cluster by intent — group informational, commercial, transactional (see references/seo-research.md).
4. Competitor gap — scripts/competitor_gap.py --domain client.com --competitor rival.com --limit 200 for each named competitor.
5. Prioritize — pick top 10-20 targets weighted by volume × intent_multiplier / difficulty.
6. SERP check the top 3 — scripts/serp_analysis.py --keyword <target> — read who's ranking, note SERP features, capture AI Overview if present.
7. AI visibility check — scripts/ai_mentions.py --brand "<client name>" --queries "<each target>" — note where client is cited and where competitors are cited instead.
8. Robots.txt audit — scripts/robots_ai_check.py --domain client.com — flag any blocked AI bots.
9. Extractability score — scripts/extractability_score.py --url <top 3 client URLs> — identify structural improvements.
10. Report — summarize into a markdown report. Include: top 10 targets, gap vs competitors, AI citation baseline, robots.txt issues, page-level fixes.

Workflow B: brief for a single target keyword

1. scripts/generate_brief.py --keyword "<target>" --output brief.md — pulls SERP, PAA, related kws, top-page titles/headings and writes a filled-in brief template.
2. Review the brief, add strategic angles (why the client is the authority on this topic).
3. Hand to the writer.
4. After publish: scripts/generate_schema.py article --headline ... --url ... → add the generated JSON-LD to the page <head>.
5. A week after publish: scripts/ai_mentions.py --brand <client> --queries "<target>" to track if the new content starts getting cited.

Workflow C: "why isn't our content being cited by AI?"

1. scripts/extractability_score.py --url <page> — returns a 0-100 score with reasons. Common failures: no definition in first paragraph, no statistics with sources, no FAQ block, missing or weak schema, no "last updated" date, missing author attribution.
2. scripts/ai_overview_check.py --keyword <target query> — see who Google cites in its AI Overview for the query and compare their structure to the client's page.
3. scripts/robots_ai_check.py --domain <client domain> — confirm GPTBot, PerplexityBot, ClaudeBot, Google-Extended are not blocked.
4. scripts/ai_mentions.py --brand <client> --queries <target query> — baseline current AI visibility.
5. Produce a fix list in priority order. AEO fixes in priority order: (1) allow AI bots, (2) add a definition block up top, (3) add stats with cited sources, (4) add FAQ schema with natural-language questions, (5) add last_updated + author attribution, (6) get cited by third-party sources (Wikipedia, Reddit, G2, YouTube).

Methodology

For deep methodology read the reference docs:

• references/seo-research.md — keyword research, competitor gap, and SERP analysis playbook.
• references/aeo-audit.md — the three pillars (structure, authority, presence), Princeton GEO research (2024 KDD), and citation content patterns.
• references/ai-bots-robotstxt.md — which AI crawlers to allow and why.
• references/extractability-checklist.md — the 10-point checklist used by extractability_score.py.
• references/brief-template.md — the content brief format used by generate_brief.py.
• references/content-patterns.md — definition blocks, comparison tables, FAQ blocks, how-to blocks, stat blocks with templates for each.
• references/schema-cheatsheet.md — which schema type for which content, with minimal-required fields.
• references/dataforseo-endpoints.md — DataForSEO endpoint map with cost per call and when to use each.

Load references on demand when the task matches. Don't read them all upfront.

Failure modes

• HTTP 401 from DataForSEO → credentials missing or wrong. Check .secrets.json or env vars.
• HTTP 429 → rate limited. Set DATAFORSEO_SLEEP=0.5 in env to throttle.
• "No results" for a seed that should have volume → wrong location/language. Defaults to United States / en; override per call or via env vars.
• ImportError on requests/bs4 → auto-install failed. Run pip install requests beautifulsoup4 lxml manually.
• extractability_score returns 0 for a real URL → the page is JavaScript-rendered and returns an empty HTML shell. This is itself a finding: JS-only pages get cited by AI at a much lower rate than server-rendered ones. Report it.

What this skill does NOT do

• Backlink analysis (DataForSEO has a backlink API, not wired here)
• Technical SEO audits beyond robots.txt (Core Web Vitals, mobile usability, etc.)
• Rank tracking over time (needs persistent storage, out of scope)
• Content generation (use generate_brief.py to produce the brief, then hand to a writer or a separate content-writing skill)
• Social media monitoring
• Paid ads (Google Ads / Meta Ads)

For those, build or use a separate skill.