SEO Agentic (Antigravity / Claude / Codex)

An LLM-first SEO analysis skill for agent IDEs, with 19 specialized sub-skills, 7 specialist agents, and 29 scripts used as evidence collectors and workflow automation.

IDE Compatibility

Antigravity IDE (.agent/skills/seo)
Claude Code (~/.claude/skills/seo)
Codex (~/.codex/skills/seo)

🚀 Getting Started (Claude Code)

Important: These are natural language commands typed in the Claude Code chat window — not terminal commands. Do not type them in a shell.

Step 1 — Clone and open in Claude Code

git clone https://github.com/buithang/seo-agentic.git
cd seo-agentic
pip install requests beautifulsoup4

Open Claude Code, then open the seo-agentic folder as your working directory.

Step 2 — Create your first project

Type this in the Claude Code chat:

project new MyBlog myblog.com

This creates a project profile at ~/.seo-projects/myblog/context.md and sets it as active. Fill in the brand, audience, and tone fields — skills use them automatically.

Other project commands:

project list              ← show all projects, mark active
project switch diverFi    ← switch active project
project status            ← show current project context

Step 3 — Run your first audit

seo audit myblog.com

Or use your project name directly (no need to type the URL):

seo audit MyBlog

Step 4 — Write content

content write What is DeFi and why it matters

The skill will research the topic, propose an outline, wait for your approval, then write the full article in your writing voice.

Note: content write requires a Writing DNA file at ~/.seo-voices/<your-name>.md. Copy the template first: cp resources/context/writing-dna.template.md ~/.seo-voices/your-name.md

All available commands

See SKILL.md for the full command list.

📦 Current Inventory

Specialized sub-skills: 19
Specialist agents: 7
Scripts in scripts/: 29 (25 Python + 1 shell + 1 JS + 2 voice shell scripts)

✨ Features

Sub-Skill	Description
`seo audit`	Full website audit with evidence-backed scoring
`seo article`	Article data extraction & LLM-driven content optimization
`seo page`	Deep single-page analysis
`seo technical`	Crawlability, indexability, security, Core Web Vitals, AI crawlers
`content audit`	Content quality & E-E-A-T assessment (Sept 2025 QRG)
`content write`	SEO content writing in your personal voice with DNA learning loop
`seo schema`	Schema.org detection, validation & JSON-LD generation
`seo sitemap`	XML sitemap analysis & generation
`seo images`	Image optimization audit (alt text, formats, lazy loading, CLS)
`seo geo`	Generative Engine Optimization — AI Overviews, ChatGPT, Perplexity
`seo aeo`	Answer Engine Optimization — Featured Snippets, PAA, Knowledge Panel
`seo links`	Link profile analysis — internal links, backlinks, anchor text, orphan pages
`seo programmatic`	Programmatic SEO safeguards & quality gates
`seo competitors`	Comparison & alternatives page generation
`seo hreflang`	International SEO / hreflang validation
`seo plan`	Strategic SEO planning with topical clusters & industry templates
`marketing interview`	30-question interview to extract positioning and content pillars into `marketing-context.md`
`content calendar`	Generate 7-day or 30-day content plan from marketing context and writing DNA
`voice correct` / `voice calibrate add`	Record AI-vs-preferred correction pairs; build a voice calibration file that tightens output style

🧠 LLM-First Workflow

This skill is designed for reasoning-first SEO analysis:

Collect page evidence (read_url_content first, scripts optional).
Analyze with LLM using explicit proof for each finding.
Apply confidence labels (Confirmed, Likely, Hypothesis).
Prioritize by impact and effort.
Produce a structured action plan.

Required Rubric

All audits should apply:

resources/references/llm-audit-rubric.md

The rubric standardizes:

evidence format (Finding, Evidence, Impact, Fix)
severity (Critical, Warning, Pass, Info)
confidence labeling
output contract for audit reports

🤖 Specialist Agents

Technical SEO — crawlability, indexability, security, mobile, JS rendering
Content Quality — E-E-A-T scoring, AI content detection
Performance — Core Web Vitals (LCP, INP, CLS) analysis
Schema Markup — JSON-LD detection, validation, generation
Sitemap — XML sitemap validation, quality gates
Visual Analysis — screenshots, above-the-fold, responsiveness (Playwright)
Verifier (Global) — dedupe/contradiction suppression before final reporting

📚 Reference Data (Updated Feb 2026)

Core Web Vitals thresholds (INP replaced FID)
E-E-A-T framework (Sept 2025 QRG + Dec 2025 core update)
Schema.org types — active, restricted, deprecated
Content quality gates & word count minimums
Google SEO quick reference
LLM audit rubric for consistent outputs

🏭 Industry Templates

Pre-built strategy templates for: SaaS, E-commerce, Local Business, Publisher/Media, Agency, and Generic businesses.

✍️ Writing Content in Your Voice

The content write sub-skill writes SEO articles in your personal writing style. It learns from every article you write and gets better over time.

How it works

Three phases, one command:

Research + outline — Web search + SERP analysis, gap identification, outline proposal. You approve before writing starts.
Writing — Full article in your voice, following your hard stops and style rules.
DNA Review — Automatic after every draft. The skill proposes learnings from the article (new examples, signature phrases, pattern refinements). You approve each one.

Approved learnings accumulate in ~/drafts/writing-dna-learnings.md. When you have enough, run merge dna to fold them back into your DNA file with a full diff preview.

Step 1: Create your Writing DNA file

Your Writing DNA is a personal voice profile — it tells the skill how you sound, what you never do, and how you think.

# Copy the template
cp resources/context/writing-dna.template.md ~/.seo-voices/your-name.md

# Edit it with your own examples, rules, and patterns

The template has sections for:

Who I am — your background and what makes your perspective different
How I sound — example hooks, body paragraphs, and disclaimers in your voice
Signature phrases — recurring structures you use
Hard stops — things you never do (e.g., "never open with a definition")
Thinking patterns — how you move from theory to reality to stakes

The DNA file lives at ~/.seo-voices/ and is never committed to git. It's yours.

Step 2: Write an article

content write What is DeFi and why I almost lost everything

# With a brief:
content write What is DeFi
Brief: perspective from someone who actually used DeFi, target: new investors

The skill will:

Search the web and fetch top-ranking pages for your keyword
Show you an outline with angle, H2/H3 structure, and a hook draft
Wait for your approval (ok / yes)
Write the full article in your voice
Save it to ~/drafts/<slug>-draft.md
Run DNA Review automatically

Step 3: Approve DNA learnings

After the draft is saved, the skill presents proposals one by one:

DNA Proposal #1 — Examples

"[excerpt from the article that shows a strong voice pattern]"

Reason: Short-line break after a claim — not yet in DNA, very characteristic

Diff:
  Section: How I sound — Body section
+ "[excerpt]" ← short-line break after claim

Save to learnings? (y/n/edit)

y — save this learning
n — skip
edit [your version] — save your edited version instead

Step 4: Merge learnings into your DNA

When you've written enough articles (3–5 is a good point), merge:

merge dna

The skill will:

Load ~/drafts/writing-dna-learnings.md
Deduplicate against your current DNA
Show a full diff preview with every proposed change
Resolve any conflicts with you
Update ~/.seo-voices/<name>.md with a version bump
Archive the learnings log

Word count defaults

Brief	Output
No brief	1200–2000 words
"short" / "quick"	800–1000 words
"pillar" / "deep" / "comprehensive"	2500–4000 words

Draft location

Every article saves to ~/drafts/<slug>-draft.md with frontmatter:

---
title: What is DeFi and why I almost lost everything
keyword: what is defi
date: 2026-04-17
status: draft
word_count: 1450
---

🔧 Installation (All IDEs)

Quick Install Script (Antigravity / Claude / Codex)

# 1) Clone
git clone https://github.com/buithang/seo-agentic.git
cd seo-agentic

# 2) Install for your target
# Antigravity (project-local):
bash install.sh --target antigravity --project-dir /path/to/your/project

# Claude:
bash install.sh --target claude

# Codex:
bash install.sh --target codex

# Global user install (Claude + Codex):
bash install.sh --target global

# All targets (Antigravity + Claude + Codex):
bash install.sh --target all --project-dir /path/to/your/project

# Install from another local checkout:
bash install.sh --target codex --repo-path /path/to/seo-agentic

Install directly from GitHub (remote source mode):

curl -fsSL https://raw.githubusercontent.com/buithang/seo-agentic/main/install.sh | \
  bash -s -- --target codex

Manual Installation

Step 1: Clone the Repository

git clone https://github.com/buithang/seo-agentic.git

Step 2: Install Python Dependencies

pip install requests beautifulsoup4

Optional — for visual analysis (screenshots & layout checks):

pip install playwright && playwright install chromium

Step 3: Choose Target Directory (Manual Install)

If you prefer not to use install.sh, copy or symlink manually:

Antigravity IDE (project-local)

mkdir -p .agent/skills
cp -r /path/to/seo-agentic .agent/skills/seo
# or: ln -s /path/to/seo-agentic .agent/skills/seo

Claude Code (user-global)

mkdir -p ~/.claude/skills
cp -r /path/to/seo-agentic ~/.claude/skills/seo
# or: ln -s /path/to/seo-agentic ~/.claude/skills/seo

Codex (user-global)

mkdir -p ~/.codex/skills
cp -r /path/to/seo-agentic ~/.codex/skills/seo
# or: ln -s /path/to/seo-agentic ~/.codex/skills/seo

Step 4: Verify Triggering

The skill will auto-trigger when you mention SEO-related keywords in your IDE. Try:

"Run an SEO audit on example.com"
"Check the schema markup on my homepage"
"Analyze Core Web Vitals for my site"
"Create an SEO plan for my SaaS product"

💬 Example Prompts (https://diverFi.com)

How Prompts Route to Agents & Scripts

The IDE uses an LLM orchestration layer to match your natural language intent to the correct underlying sub-skill (e.g., seo-hreflang.md, seo-schema.md). You do not need to use explicit flags or commands.

To run a specific test: Ask for it specifically (e.g., "Check hreflang"). The LLM will only trigger the necessary scripts.
To force ALL agents/tests: Ask for a "full, comprehensive audit running all checks". The LLM will route this to seo-audit.md, which acts as the master orchestrator calling all available scripts and analyzing the combined output.

Here's how specific phrases map to the skill's capabilities:

You type...	Scope	Agent(s) activated	Scripts used
"Run SEO audit"	🌐 Full domain	All 6 core website agents (technical, content, schema, performance, sitemap, visual)	`parse_html.py`, `pagespeed.py`, `robots_checker.py`, `security_headers.py`, `broken_links.py`, `readability.py`
"Analyze this article" / blog post URL	📄 Single page	Content + Schema + Technical	`article_seo.py`, `parse_html.py`, `readability.py`
"Check technical SEO"	🔧 Technical only	Technical	`robots_checker.py`, `security_headers.py`, `redirect_checker.py`, `parse_html.py`
"Review content quality" / "E-E-A-T"	📝 Content only	Content	`article_seo.py`, `readability.py`, `entity_checker.py`
"Check schema markup"	🏷️ Schema only	Schema	`parse_html.py`, `validate_schema.py`
"Audit sitemap"	🗺️ Sitemap only	Sitemap	`broken_links.py`
"Check page speed" / "Core Web Vitals"	⚡ Performance only	Performance	`pagespeed.py`
"Take screenshots" / "mobile check"	📱 Visual only	Visual	`capture_screenshot.py`, `analyze_visual.py`
"Check GEO readiness" / "AI search"	🤖 GEO/AI only	Technical + Content	`llms_txt_checker.py`, `robots_checker.py`, `parse_html.py`
"Analyze links" / "backlink profile"	🔗 Links only	Technical	`link_profile.py`, `internal_links.py`, `broken_links.py`
"Check hreflang"	🌍 i18n only	Technical	`hreflang_checker.py`
"Create SEO plan" / "SEO strategy"	📋 Strategy	None (LLM reasoning)	`competitor_gap.py` (optional)
"AEO analysis" / "Featured Snippets"	🎯 AEO only	Content	`article_seo.py`, `parse_html.py`
"Entity SEO" / "Knowledge Graph"	🏛️ Entity only	Content + Schema	`entity_checker.py`, `parse_html.py`
"Check IndexNow"	📡 IndexNow only	Technical	`indexnow_checker.py`
"Find content gaps" / "competitor analysis"	📊 Gap analysis	None (LLM reasoning)	`competitor_gap.py`
"Check for duplicates" / "thin content"	📋 Dupe check	Content	`duplicate_content.py`
"GSC data" / "Search Console"	📈 GSC only	None	`gsc_checker.py`

Domain vs URL vs Blog Post — What's Different?

Input type	What happens	Example
Domain (`diverfi.com`)	Crawls multiple pages, checks robots.txt, sitemap, site-wide patterns	Full audit, link profile, sitemap check
URL (`diverfi.com/page`)	Single page deep-dive: HTML, meta, schema, content, CWV	Page audit, schema check, technical check
Blog post URL	Article-specific: readability, keyword density, heading structure, JSON-LD `Article`/`BlogPosting` schema, publish date	Article analysis, AEO check

🌐 Full Domain Audit

Run a full SEO audit for https://diverfi.com and prioritize fixes by impact.

📄 Single Page / Blog Post Analysis

Analyze this article: https://www.diverfi.com/learn/defi-basics/01-what-is-defi

Do a single-page SEO analysis of https://diverfi.com and show critical issues first.

🔧 Technical SEO

Analyze technical SEO for https://diverFi.com (robots, crawlability, canonicals, redirects, headers).

📝 Content Quality & E-E-A-T

Review content quality and E-E-A-T signals on https://diverFi.com and suggest concrete rewrites.

🏷️ Schema Markup

Check schema markup on https://diverFi.com, validate errors, and generate corrected JSON-LD.

⚡ Performance & Core Web Vitals

Run Core Web Vitals analysis on https://diverFi.com and break down LCP subparts.

🤖 GEO / AI Search Readiness

Evaluate GEO readiness for https://diverFi.com (AI crawler access, llms.txt, citation structure).

🎯 Answer Engine Optimization (AEO)

Analyze AEO signals for https://diverFi.com — Featured Snippet targeting, PAA optimization, Knowledge Panel readiness.

🔗 Link Profile Analysis

Analyze internal link structure and backlink profile for https://diverFi.com.

🏛️ Entity SEO / Knowledge Graph

Check entity SEO for https://diverFi.com — Wikidata presence, sameAs links, Knowledge Graph signals.

📊 Competitor Topic Gap

Find content gaps between https://diverFi.com and competitors https://www.binance.com/en/academy https://www.fidelity.com/learning-center/trading-investing/crypto/.

🌍 Hreflang / International SEO

Validate hreflang implementation on https://diverFi.com — BCP-47 tags, bidirectional links, x-default.

📡 IndexNow

Check IndexNow implementation for https://diverFi.com with key abc123def456.

📋 Topical Cluster Planning

Create a topical authority cluster plan for https://diverFi.com covering cybersecurity topics.

📈 Google Search Console (requires credentials)

Pull GSC performance data for https://diverFi.com and identify striking-distance keywords.

🗺️ Sitemap Audit

Audit sitemap quality for https://diverFi.com and flag missing, redirected, or noindex URLs.

🖼️ Image SEO

Run image SEO checks for https://diverFi.com (alt text, lazy loading, dimensions, format suggestions).

📋 Strategic SEO Plan

Create a 6-month SEO strategy for https://diverFi.com with milestones and KPIs.

📱 Visual / Mobile Analysis

Take desktop and mobile screenshots of https://diverFi.com and analyze above-the-fold content.

Run Everything at Once

To run all analysis types on a single URL:

Run a complete SEO audit on https://diverFi.com — include technical, content, schema, performance,
links, GEO, AEO, entity SEO, and sitemap analysis. Provide a prioritized action plan.

Example generated outputs:

FULL-AUDIT-REPORT.md — comprehensive findings
ACTION-PLAN.md — prioritized fixes

📊 Report Generation

You can generate reports in two ways:

LLM-first report in your IDE (Antigravity / Claude / Codex) (recommended for strategy + prioritization):

Run a full SEO audit for https://diverFi.com and produce a prioritized action plan with evidence for each finding.

Interactive HTML dashboard (recommended for shareable technical snapshots):

python3 scripts/generate_report.py "https://diverFi.com" --output seo-report-diverFi.html

The HTML report includes:

overall score and category breakdown
environment detection (platform/runtime inference)
environment-specific fix plan
section-level issues and recommendations
readability "what to replace" suggestions

Example generated dashboard:

⚙️ Optional Script Workflow

Use scripts when you need additional verification or structured JSON outputs.

# Example target
URL="https://example.com"

# Fetch + parse HTML
python3 scripts/fetch_page.py "$URL" --output /tmp/page.html
python3 scripts/parse_html.py /tmp/page.html --url "$URL" --json

# Core checks
python3 scripts/robots_checker.py "$URL" --json
python3 scripts/llms_txt_checker.py "$URL" --json
python3 scripts/pagespeed.py "$URL" --strategy mobile --json
python3 scripts/security_headers.py "$URL" --json
python3 scripts/redirect_checker.py "$URL" --json
python3 scripts/social_meta.py "$URL" --json

# Content + structure checks
python3 scripts/readability.py /tmp/page.html --json
python3 scripts/internal_links.py "$URL" --depth 1 --max-pages 20 --json
python3 scripts/broken_links.py "$URL" --workers 5 --json
python3 scripts/article_seo.py "$URL" --json

# New analysis scripts
python3 scripts/hreflang_checker.py "$URL" --json
python3 scripts/entity_checker.py "$URL" --json
python3 scripts/duplicate_content.py "$URL" --json
python3 scripts/link_profile.py "$URL" --json
python3 scripts/competitor_gap.py "$URL" --competitor https://competitor.com --json
# python3 scripts/gsc_checker.py "$URL" --credentials creds.json --json  # requires GSC credentials
# python3 scripts/indexnow_checker.py "$URL" --key YOUR_KEY --json          # requires IndexNow key

# Generic verifier stage (can be used by any workflow before final reporting)
python3 scripts/finding_verifier.py --findings-json raw-findings.json --json

Generate a single HTML dashboard if needed:

python3 scripts/generate_report.py "$URL"

🛡️ Critical Rules Enforced

Rule	Detail
INP not FID	FID removed Sept 2024. INP is the sole interactivity metric.
FAQ schema restricted	FAQPage only for government/healthcare authority sites (Aug 2023)
HowTo deprecated	Rich results removed Sept 2023
JSON-LD only	Never recommend Microdata or RDFa
E-E-A-T everywhere	Applies to ALL competitive queries since Dec 2025
Mobile-first complete	100% mobile-first indexing since July 2024
Location page limits	⚠️ Warning at 30+ pages, 🛑 Hard stop at 50+

📋 Requirements

Requirement	Version
Python	3.8+
`requests`	Any
`beautifulsoup4`	Any
Playwright	Optional (for visual analysis)

🙏 Credits

This project is heavily built from claude-seo by AgriciDaniel. All core SEO logic, reference data, agent definitions, utility scripts, and sub-skill instructions originate from that project.

This repository restructures and adapts the content to function as a compatible skill package for Antigravity IDE, Claude Code, and Codex, while preserving the same core skill layout (SKILL.md + scripts/ + resources/).

📄 License

Licensed under the MIT License. See LICENSE.

Portions are derived from claude-seo, which is also MIT-licensed.

Name		Name	Last commit message	Last commit date
Latest commit History 88 Commits
.claude		.claude
.context		.context
.github/workflows		.github/workflows
docs		docs
resources		resources
scripts		scripts
templates		templates
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
SKILL-DOCS.md		SKILL-DOCS.md
SKILL.md		SKILL.md
TODOS.md		TODOS.md
VERSION		VERSION
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

SEO Agentic (Antigravity / Claude / Codex)

IDE Compatibility

🚀 Getting Started (Claude Code)

Step 1 — Clone and open in Claude Code

Step 2 — Create your first project

Step 3 — Run your first audit

Step 4 — Write content

All available commands

📦 Current Inventory

✨ Features

🧠 LLM-First Workflow

Required Rubric

🤖 Specialist Agents

📚 Reference Data (Updated Feb 2026)

🏭 Industry Templates

✍️ Writing Content in Your Voice

How it works

Step 1: Create your Writing DNA file

Step 2: Write an article

Step 3: Approve DNA learnings

Step 4: Merge learnings into your DNA

Word count defaults

Draft location

🔧 Installation (All IDEs)

Quick Install Script (Antigravity / Claude / Codex)

Install directly from GitHub (remote source mode):

Manual Installation

Step 1: Clone the Repository

Step 2: Install Python Dependencies

Step 3: Choose Target Directory (Manual Install)

Antigravity IDE (project-local)

Claude Code (user-global)

Codex (user-global)

Step 4: Verify Triggering

💬 Example Prompts (https://diverFi.com)

How Prompts Route to Agents & Scripts

Domain vs URL vs Blog Post — What's Different?

🌐 Full Domain Audit

📄 Single Page / Blog Post Analysis

🔧 Technical SEO

📝 Content Quality & E-E-A-T

🏷️ Schema Markup

⚡ Performance & Core Web Vitals

🤖 GEO / AI Search Readiness

🎯 Answer Engine Optimization (AEO)

🔗 Link Profile Analysis

🏛️ Entity SEO / Knowledge Graph

📊 Competitor Topic Gap

🌍 Hreflang / International SEO

📡 IndexNow

📋 Topical Cluster Planning

📈 Google Search Console (requires credentials)

🗺️ Sitemap Audit

🖼️ Image SEO

📋 Strategic SEO Plan

📱 Visual / Mobile Analysis

Run Everything at Once

📊 Report Generation

⚙️ Optional Script Workflow

🛡️ Critical Rules Enforced

📋 Requirements

🙏 Credits

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages