openclaw-master-skills/skills/seo-agi

SEO-AGI

One command. Competitive data in. Ranking pages out.

Most SEO tools tell you what's wrong with your site. This one writes the pages.

/seoagi "airport parking JFK" pulls the current SERP, analyzes what's ranking, finds the gaps in their content, and writes you a complete page -- with the heading structure, depth, FAQ section, and schema markup that actually competes. Not thin content. Not keyword-stuffed filler. Pages backed by live data from the tools the pros use.

I built this because I got tired of the gap between "SEO audit" and "published page." I've been doing SEO for 20+ years in ground transportation (1M+ bookings, 2M+ rides across my companies). The workflow was always the same: pull SERP data, analyze competitors, find gaps, write brief, write page, add schema, publish. Over and over. So I turned that entire workflow into a single skill that any AI agent can execute.

The result? I used this to research a competitor's best-performing pages, built equivalent content with /seoagi, bought the exact-match domains, and every single page is ranking on page 1. That's not theory. That's the workflow.

---

What It Actually Does

You give it a keyword. It builds a page that would survive r/SEO without getting called AI slop.

That's the bar. Not "sounds good." Not "has keywords." Would a practitioner who ranks pages for a living read this and say "this is real." That's the Reddit Test, and every page this skill produces must pass it before you see it.

---

The Methodology (This Is Not "AI Writes a Page")

This skill encodes a complete SEO and GEO (Generative Engine Optimization) methodology built for how ranking actually works in 2026. Not prompt tricks. A belief system, a content architecture, quality gates, and writing rules forged from two decades of ranking pages.

The core belief: AI content is not the problem. Generic content is. If your page just rewrites the first page of Google, you deserve to not rank. Every page this skill produces must create real information gain -- content that cannot be found by reading the top 10 results for the same query.

---

Ranking in 2026: The Game Changed

Traditional SEO optimized for a blue link on Google. That's no longer the only game. The primary goal is now to be the cited source across every answer engine -- Google AI Overviews, ChatGPT, Perplexity, Gemini, Claude.

This means three fundamental shifts the skill is built around:

1. Entity Consensus Over Backlinks. LLMs trust brands mentioned consistently across high-signal domains (Reddit, Wikipedia, LinkedIn, niche authority sites). The skill builds entity-rich, brandable content designed to generate consensus across the platforms where LLMs actually scrape -- not just link equity on forgotten guest posts.

2. Knowledge Graph Connectivity Over Keyword Matching. Google is moving from keyword matching to entity and Knowledge Graph matching. Your site must be seen as a brand with established entities and high topical authority. The skill enforces full official entity names, location entities, service entities, and operator names explicitly throughout every page -- because Google's KG uses different NLP than transformers, and you have to be explicit.

3. Conversational Intent Over Search Volume. AI is changing how people search. Volume on traditional head terms is declining while conversational, intent-heavy queries are surging. The skill maps "Query Fan-Out" questions -- the logical follow-ups an AI will suggest next -- and structures every page to answer them before they're asked.

---

Google's AI Search Pipeline: 7 Ranking Signals

Every page is optimized against the signals Google's AI pipeline actually scores:

Signal	What It Measures	How SEO-AGI Optimizes
Base Ranking	Core algorithm relevance	Strong topical authority, clean technical structure
Gecko Score	Semantic/vector similarity (embeddings)	Covers semantic neighbors, synonyms, co-occurring concepts
Jetstream	Advanced context and nuance	Genuine analysis, honest comparisons, unique framing
BM25	Traditional keyword matching	Exact-match terms, full entity names, high-volume synonyms
PCTR	Predicted click-through rate	Compelling titles with numbers, strong meta descriptions
Freshness	Time-decay recency	"Last verified" dates, updated pricing, seasonal content
Boost/Bury	Manual quality adjustments	No thin sections, no empty headings, no duplicate patterns

---

500-Token Chunk Architecture

Google's AI retrieves content in ~500-token chunks (~375 words). LLMs chunk at ~600 words with ~300-word overlap. Every page this skill produces is engineered to feed that pipeline:

• Question-based H2s matching real search queries and Query Fan-Out questions
• Snippet Answers: first 2-3 sentences after every H2 are a direct, concrete answer. No preamble. No throat-clearing. The answer.
• Contrast Statements: explicit X vs Y comparisons with real numbers inside every chunk
• Self-contained chunks: data tables never split across boundaries. No two H2s stacked without 250+ words of substance between them.
• Front-loaded strength: the strongest content (bottom-line recommendations, key data) appears in the first 3 chunks. AI retrieval may never reach buried material.

---

SEAT Signals (Semantic + E-E-A-T + Entity/Knowledge Graph)

Semantic coverage: every page hits primary head terms, semantic neighbors, geo-modifiers, mode competitors (named even if you don't sell them), and operational terms. You can't rank for a topic if you haven't covered the semantic neighborhood around it.

E-E-A-T that isn't performative:

• Experience: location-specific operational details only someone who's been there would know
• Expertise: pricing comparisons with real math, not "affordable" or "competitive"
• Authority: cites official sources (published rate schedules, government documents, authority websites)
• Trust: honest "Not For You" sections that tell readers when this option is a bad fit. At least one line a competitor would never publish because it might scare off a lead. That's the ultimate trust signal -- and LLMs weight it heavily.

Entity/Knowledge Graph signals: full official entity names at least once, location identifiers as distinct entities, service names as entities not just list items, operating authority names. The Knowledge Graph uses different NLP than transformer models. If you aren't explicit, you don't exist in the graph.

---

Forensic Competitive Analysis

This isn't "look at the top 10 and write something similar." It's a forensic breakdown of why a competitor is winning:

• Knowledge Graph connectivity: how well is their brand connected to established entities?
• Entity salience: which entities does Google associate most strongly with their content?
• Content architecture: what topics do they cover that you don't? What 500-token chunks are they feeding the pipeline?
• Third-party mentions: are they being cited on Reddit, niche authority sites, social platforms? LLMs use this as a trust signal independent of backlinks.
• Information gaps: what data exists in official documents (PDFs, government sites, published reports) that no competitor has surfaced yet?

The skill identifies exactly where your content is weaker, thinner, or less entity-rich than what's currently ranking -- then builds content that exceeds those signals.

---

The Reddit Test (Quality Gate)

Before any page is delivered, it must pass this: if posted to a relevant subreddit, would a knowledgeable practitioner call it "AI slop" or upvote it?

Passing requires at least three of:

1. A hard number from an official or overlooked source (capacity, square footage, wait time, frequency)
2. A layout or navigation detail only someone familiar would know
3. A cost comparison that does real math showing when one option beats another
4. A schedule or operational detail with specifics, not "busy periods" but named days and times
5. A recent change not yet reflected on competing pages
6. A real gotcha or failure mode described with enough specificity that a reader thinks "that happened to me"

---

The Information Gain Test

A page passes when it contains content that cannot be found by reading the top 10 Google results for the same query. The skill searches [topic] filetype:pdf for official documents, published data, and operational records that no competitor page surfaces. That's your information gain. That's what makes the page worth ranking.

---

Verification Tags (No Hallucinated Data)

The skill is forbidden from inventing statistics, pricing, or operational claims. Every specific number gets tagged for human verification:

• {{VERIFY: daily rate $20 | published rate schedule PDF}} -- specific claims with source references
• {{RESEARCH NEEDED: total capacity | check master plan document}} -- sections needing hard data
• {{SOURCE NEEDED: shuttle frequency | check ground transportation page}} -- claims needing citations

You get content that's structured for ranking AND flagged for fact-checking. Not hallucinated garbage dressed up as expertise.

---

LLM / AEO Citation Strategy

LLMs pull from positions 51-100, not just page 1. Being the most structured, most honest comparison page can earn AI citations even without traditional page 1 rankings. A site optimized for LLM discovery can see revenue jumps before it ever shows up in traditional search results.

The skill optimizes every page to become citable by AI answer engines:

• Most complete comparison: all options, all price points, all tradeoffs in clean structured data
• Real HTML tables with labeled columns (not bullet-point lists pretending to be tables -- LLMs parse tables differently)
• Unique operational content: process steps, booking flows, navigation details that no generic page includes
• The page that tells the truth when competitors don't: "Not For You" blocks, honest tradeoffs, real gotchas
• RDFa/Microdata inline: not just JSON-LD in the header (which LLMs often ignore). Semantic labels embedded directly in paragraph markup -- "alt-text for your text" so LLMs extract entities, costs, and services effortlessly
• Entity consensus generation: core 500-token chunks can be reformatted for cross-posting to build brand authority on the platforms where LLMs actually scrape

---

"Not For You" Block (Mandatory)

Every page must include a section honestly telling the reader when this option is a bad fit. Name the specific scenario. Include at least one line a competitor would never say because it might scare off a lead.

This is not optional. This is not a nice-to-have. This is the single strongest trust signal you can send to both human readers and AI systems. When every other page says "we're perfect for everyone," the page that says "here's when we're not the right choice" is the one that gets cited.

---

Tightly Focused Topical Authority

"Topical authority" as it was taught in 2014 is dead. Writing broadly around a topic can now hurt your site by confusing the AI's understanding of your brand. Every piece of content must reinforce a singular, tight brand entity.

If content isn't directly related to your core service, it can dilute your vector of intent. The skill keeps every page tightly focused on its target topic and its semantic neighborhood -- no off-topic fluff, no tangential content farms, no "we should write about that too" pages that weaken your entity signal.

---

The Quality Checklist

Every page is validated before delivery. If any check fails, the skill rewrites before you see it.

Check	Required
Contains information gain over top 10 Google results?	YES
Would a knowledgeable Reddit commenter upvote this?	YES
Core answer in the first 150 words?	YES
Fast-scan summary within 200 words?	YES
2+ hard operational Prove-It facts with traceable citations?	YES
At least one real HTML/Markdown table?	YES
Every section doing a unique job (no repetition)?	YES
All specific numbers tagged with {{VERIFY}}?	YES
"Not For You" block present?	YES
Content structured for LLM extraction (500-token chunks)?	YES
Avoids all banned phrases and AI-slop patterns?	YES

Fails any check = rewrite before delivery. No exceptions.

Data Integrations (BYOK)

Bring your own API keys. Use one, use all. The skill adapts:

Integration	What It Provides	Required?
DataForSEO	Live SERP results, keyword volumes, People Also Ask, competitor content parsing	Yes (core)
Google Search Console	Your actual query data, CTR, positions, cannibalization detection	Optional
Ahrefs (via MCP)	Backlink profiles, domain authority, referring domains	Optional
SEMRush (via MCP)	Traffic estimates, keyword gaps, competitive positioning	Optional

No keys at all? The skill falls back to web search. You lose precision but the workflow still runs.

---

Install + Setup

Step 1: Install the skill

Pick your platform:

Claude Code:

claude install-skill gbessoni/seo-agi

OpenClaw:

git clone https://github.com/gbessoni/seo-agi.git ~/.claude/skills/seo-agi

Codex:

git clone https://github.com/gbessoni/seo-agi.git ~/.codex/skills/seo-agi

Manual (any platform):

git clone https://github.com/gbessoni/seo-agi.git ~/.claude/skills/seo-agi

Step 2: Install Python dependency

pip install requests

Step 3: Configure API keys (optional but recommended)

mkdir -p ~/.config/seo-agi
cp ~/.claude/skills/seo-agi/.env.example ~/.config/seo-agi/.env

Then edit ~/.config/seo-agi/.env with your keys:

# DataForSEO -- sign up at https://dataforseo.com (~$0.002/query)
DATAFORSEO_LOGIN=your_email@example.com
DATAFORSEO_PASSWORD=your_password

# Google Search Console (optional)
GSC_SERVICE_ACCOUNT_PATH=/path/to/service-account.json

No API keys? The skill still works. It falls back to Ahrefs/SEMRush MCP tools (if connected) or web search. You lose SERP content parsing but the framework still writes quality pages.

Step 4: Verify it works

# Test the research pipeline (uses mock data, no API keys needed)
python3 ~/.claude/skills/seo-agi/scripts/research.py "airport parking JFK" --mock --output=compact

You should see SERP results, PAA questions, related keywords, and heading structure data. If you see that, you're good.

Step 5: Use it

Open Claude Code (or OpenClaw, or Codex) and type:

Write an SEO page for "airport parking JFK"

The skill auto-triggers on SEO content requests. It will:

1. Run the research script to pull competitive data
2. Show you a content brief and confirm before writing
3. Write the full page following the SEO-AGI framework
4. Validate against the quality checklist
5. Save to ~/Documents/SEO-AGI/pages/

---

Verify Your Setup (Troubleshooting)

Check if the skill is installed:

ls ~/.claude/skills/seo-agi/SKILL.md && echo "Installed" || echo "Not found"

Check if API keys are configured:

cat ~/.config/seo-agi/.env 2>/dev/null || echo "No .env file -- skill will use fallback mode"

Test with live DataForSEO (if you have keys):

python3 ~/.claude/skills/seo-agi/scripts/research.py "best crm software" --output=compact

Run unit tests:

cd ~/.claude/skills/seo-agi
python3 tests/test_env.py && python3 tests/test_serp_analyze.py && python3 tests/test_dataforseo.py

---

Use Cases

Exact-match domain play: Research competitor's top pages with OpenClaw, generate equivalent content with /seoagi, buy the domains, publish. Page 1.

Location page generation: /seoagi "plumber in [city]" x 50 cities. Each page gets city-specific research, local PAA questions, LocalBusiness schema. Not cookie-cutter templates.

Content refresh: Point it at your underperforming URLs. It pulls your actual GSC data, compares against current top 3, and tells you exactly what to add, expand, or restructure. Then does it.

Competitive intelligence: /seoagi research "competitor keyword" gives you the full landscape without writing anything. Word count ranges, heading structures, topic gaps, related keywords with volumes.

Brief handoff: /seoagi brief "keyword" generates a structured content brief you can hand to a human writer. Research-backed, not vibes-based.

---

The Workflow That Got Me Here

I've been running this workflow manually for 20 years across ParkingAccess.com (1M+ bookings) and Shuttlefare.com (2M+ rides). The pattern never changed:

1. Find what's ranking
2. Figure out what they cover that you don't
3. Write something deeper
4. Add the technical SEO (schema, meta, structure)
5. Publish and move on

seo-agi is that pattern, automated. The 20 years of pattern recognition compressed into a SKILL.md file, backed by live data APIs, running inside a super agent that can decompose and parallelize the work.

It's not AI replacing SEO expertise. It's SEO expertise finally having the right delivery mechanism.

---

Testing

See "Verify Your Setup" above for full test commands. Quick version:

cd ~/.claude/skills/seo-agi

# Unit tests (no API keys needed)
python3 tests/test_env.py && python3 tests/test_serp_analyze.py && python3 tests/test_dataforseo.py

# Mock mode (full pipeline with fixture data)
python3 scripts/research.py "airport parking JFK" --mock --output=compact

# No-creds mode (returns skeleton for agent to fill via MCP/WebSearch)
python3 scripts/research.py "test keyword" --output=compact

---

Contributing

Open source, MIT license. PRs welcome.

The skill is modular. Want to add a new page template? Edit references/page-templates.md. New schema pattern? references/schema-patterns.md. Better quality checks? references/quality-checklist.md. New data source? Add a client in scripts/lib/ and wire it into research.py.

---

Credits

Built by Greg Bessoni (@gregbessoni).

License

MIT