SEO Skills: Universal AI SEO Agent & Technical Optimization Suite

SEO Skills is the universal, open-source AI search engine optimization skill suite and audit engine for modern AI coding agents — including Anthropic Claude Code, Google Antigravity IDE, Cursor IDE, Windsurf Cascade, GitHub Copilot, OpenAI ChatGPT / Codex, Cline & Roo Code, Aider CLI, and DeepSeek R1.

Built upon the Holistic Semantic SEO Framework, Google Information Gain Patent US 11,562,019 B2, 2026 Google Search Essentials, and the open Agent Skills Specification, SEO Skills delivers 27 modular sub-skills, 18 specialist sub-agents, first-party Python adapters (DataForSEO, Firecrawl, Bing Webmaster, IndexNow), optional third-party vendor MCP (Ahrefs, SE Ranking, Profound, Banana, Unlighthouse), and a deterministic zero-telemetry Python execution engine.

---

📈 Real-World Performance & Empirical Results

SEO Skills is proven across both brand-new domains launched from scratch and established websites recovering from algorithmic decay:

1. Brand New Sites: Instant Google Indexation & Organic Ranking

Empirical Google Search Console trajectory for brand new domains launched with SEO Skills structured EAV entity modeling and Schema.org graphs:

Figure 1 (illustrative): Google Search Console performance UI. Property, date range, and filters are whatever appears in the screenshot — not a live export from this repository.

Figure 2 (illustrative): GSC query/page table for an example property. Treat as a UI example, not packaged ranking proof.

---

2. Multi-Engine Indexation: Bing & IndexNow Batch Discovery

Accelerated crawl discovery and top-tier rankings on Bing Search via unified Bing Webmaster and IndexNow automation:

Figure 3 (illustrative): Bing Webmaster Tools UI for an example site and date range.

---

3. Established Domain Recovery: Algorithmic Turnaround

Resolving technical debt, deprecated schemas, and thin content to recover decaying legacy properties:

Figure 4 (illustrative): Search performance chart for a recovering property. Filters and dates are those shown in the image.

---

Installation

Clone the repository and open it as the agent workspace.

git clone https://github.com/seoskillsai/seo-skills-ai.git
cd seo-skills-ai
npx @seoskillsai/cli add cursor

Or without cloning first:

npx @seoskillsai/cli add cursor

Unix / macOS:

bash install.sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\install.ps1

Then point Claude Code, Cursor, Antigravity, Windsurf, Codex, or Cline at this folder. Skills load from skills/. Optional Playwright Chromium is installed by install.sh / install.ps1 for screenshots.

Claude Code CLI

/plugin marketplace add seoskillsai/seo-skills-ai
/plugin install seo-skills@seoskillsai-seo-skills
/seo setup
/seo doctor

Cline / Roo MCP

Copy config/cline_mcp_settings.json into your Cline MCP settings. Tools are not auto-approved; the host must confirm seo_audit and seo_drift because they fetch the URL you pass.

---

🏛️ What Makes SEO Skills Superior to Legacy Tools

Traditional SEO auditing tools (such as standalone browser extensions or single-agent plugins) rely on superficial regex scripts, obsolete Schema.org types, and generic prompt checklists. SEO Skills operates as an autonomous, multi-agent intelligence layer that executes deterministic code, inspects DOM rendering pipelines, and enforces holistic semantic authority:

---

🔍 Generative Engine Optimization (GEO) & AI Search Citability

Google AI Overviews, Perplexity Pro, and ChatGPT Search extract 130–170 word self-contained semantic answer passages directly from structured content. SEO Skills audits passage citability, question-based heading hierarchies, and entity attribution density to ensure your brand is cited as the primary authority.

---

🛠️ The 27 Modular SEO Skills Catalog

Every command in SEO Skills can be executed directly from your terminal CLI or invoked conversationally inside any AI agent workspace.

Core Audits & Architecture

• /seo audit <url>: Parallel full-site audit dispatching up to 15 specialist agents across technical, content, schema, GEO, and link vectors.
• /seo technical <url>: Comprehensive 9-category technical audit (Core Web Vitals INP/LCP/CLS, HTTP security headers, canonical loops, redirect chains, SPA hydration markers).
• /seo crawl <url> [max_pages]: Recursive multi-page site crawler mapping internal PageRank link graphs, crawl depth distribution ($\le 2$ clicks), and orphan pages.
• /seo drift <url>: SQLite on-page baseline snapshotting and 17-rule regression comparator to detect deployment code regressions.
• /seo fix <url>: Prints HTML/Astro remediation snippets for review. Does not modify the repository.

Semantic Content & Topical Authority (Semantic SEO Standard)

• /seo content <url>: Holistic semantic content audit applying Entity-Attribute-Value (EAV) modeling and anti-thin educational prose validation ($800+$ words).
• /seo content-brief <topic>: Generates intent-grounded content briefs with macro/micro context, heading hierarchies, and directional link conduit targets.
• /seo cluster <seed>: SERP-overlap semantic keyword clusterer grouping search queries by top-10 URL overlap ($ \ge 4$ overlapping URLs = single pillar).
• /seo info-gain <url>: Google Patent US 11,562,019 B2 analyzer evaluating empirical data density, entity novelty, and SERP consensus deviation.
• /seo flow [stage]: 7-layer recursive multi-agent execution prompt flow guiding copywriters from entity research to final publication.

Structured Data & AI Search (GEO / AEO)

• /seo schema <url>: 2026 Google-compliant JSON-LD structured data validator and generator (enforces nested @graph with TechArticle, Product, BreadcrumbList).
• /seo llms-txt <url>: Dynamic /public/llms.txt and /public/llms-full.txt generator structuring site documentation for LLM ingestion.
• /seo robots-ai <url>: AI crawler permissions manager balancing citation discovery (GPTBot, ClaudeBot, Google-Extended) with scraper protection.
• /seo geo <url>: Generative Engine Optimization audit scoring passage-level answer citability ($130–170$ word self-contained blocks) and attribution density.
• /seo discover <url>: Google Discover image optimization, <media:content> 1200px 16:9 Media RSS XML feed builder, and First-Exposure AI Editorial Byline disclosures.

Local SEO, Maps Intelligence & E-Commerce

• /seo local <url>: Google Business Profile audit, NAP consistency across citation networks, and multi-location doorway page threshold guardrails ($30/50$ limits).
• /seo maps <url>: Geo-grid ranking radius analysis, review sentiment trends, and local competitor proximity mapping.
• /seo ecommerce <url>: E-commerce product schema validator (hasMerchantReturnPolicy, shippingDetails, aggregateRating, gtin13, IPTC TrainedAlgorithmicMedia).
• /seo competitor-pages <url>: Generates competitor comparison and alternative landing page architectures ("X vs Y").
• /seo programmatic <url>: Programmatic SEO template generator with anti-thin quality gates preventing doorway penalties.
• /seo hreflang <url>: Multi-regional and multi-lingual Hreflang reciprocity validator and XML sitemap generator.

APIs, Performance & Reporting

• /seo google [command]: PSI/CrUX without a Google login; GSC Search Analytics and GA4 organic sessions only after ~/.config/seoskillsai/gsc_ga4.json exists (otherwise UNAVAILABLE, no invented numbers).
• /seo backlinks <url>: Free backlink profile and referring domain audit via Common Crawl Open Web Graph, Moz Free API, and Bing Webmaster Tools.
• /seo images <url>: Visual semantic image audit, next-gen WebP/AVIF compression analysis, and IPTC AI generation metadata verification.
• /seo report <url>: Generates executive-ready HTML and 200 DPI vector PDF audit reports with visual health scorecards.
• /seo doctor: System diagnostic utility checking Python runtime, SQLite databases, and agent harness readiness.
• /seo setup: Runtime provisioner bootstrapping isolated virtual environments and baseline databases.

---

Vendor APIs: first-party HTTP vs third-party MCP

This repo owns a small set of Python HTTP clients. Other vendors are official MCP servers you run with their keys; we do not bundle those servers.

First-party (our HTTP, credentials from env / ~/.config/seoskillsai/):

Third-party MCP (not our implementation): Ahrefs (@ahrefs/mcp), SE Ranking, Profound, Banana, Unlighthouse. See extensions/*/README.md. Example MCP snippets use ${ENV} placeholders — never commit empty "API_KEY": "" as if it were a secret.

---

🧠 Topical & Semantic SEO Principles

SEO Skills is founded upon the Topical Authority & Semantic SEO Standard, prioritizing topical source context and mathematical link equity over superficial keyword density:

1. Entity-Attribute-Value (EAV) Modeling: Every topic is constructed around a central entity ($E_0$), associated secondary entities ($E_1 \dots E_n$), defining attributes ($A$), and verified contextual values ($V$).
2. Directional PageRank Conduits: Link equity flows systematically upwards and horizontally: Outer Cluster Nodes $\rightarrow$ Category Silo Hub $\rightarrow$ Core Flagship Pillar.
3. 3x Anchor Text Diversity Rule: Exact-match target keyword anchor text must never appear more than 3 times across the entire website. Partial-match and semantic variations prevent over-optimization penalties.
4. Anti-Thin Educational Prose Architecture: Interactive tools, calculators, and widgets must be grounded with 800+ words of structured educational body prose to satisfy Google Quality Rater Guidelines (QRG §4.6.5).
5. Centerpiece Above-the-Fold Annotation: The primary interactive element or direct answer must render within the top 350px viewport (<600px mobile) to prevent centerpiece demotion penalties.

---

Security & Privacy

• No product telemetry: Audits and SQLite baselines stay on your machine. SEO Skills AI does not send analytics to seoskillsai.com.
• Network-target policy: User-supplied URLs go through scripts/url_safety.py (scheme, DNS fail-closed, private/metadata IP block, redirect re-check). Optional allowlist: SEOSKILLS_ALLOWED_HOSTS. Headless Chromium uses the same policy for navigation and blocks private-IP subresources.
• Repo scope: Generated files stay under SEOSKILLS_OUT_DIR (default: cwd). Remediation patches are review-only.
• MCP: Shipped Cline config does not autoApprove fetch tools.
• Host-agent hooks: hooks/hooks.json PreToolUse runs hook_validate_fetch.py / hook_validate_write.py on stdin JSON (no {file} shell interpolation).
• Playwright: navigation and private-IP subresources are aborted. Set SEOSKILLS_STRICT_BROWSER=1 to apply SEOSKILLS_ALLOWED_HOSTS to subresources too.
• Optional vendor APIs: PageSpeed, CrUX, RDAP, IndexNow, DataForSEO, Firecrawl, Bing Webmaster, and third-party MCP send the URL you asked to audit to those vendors when you run those commands.
• Credentials: Optional keys in ~/.config/seoskillsai/ with 0o600 permissions, gitignored.

See SECURITY.md.

---

📚 Knowledge Databases & References

Explore our comprehensive reference library directly inside the repository:

• Deployment map (docs/DEPLOYMENT.md)
• Google Algorithm Updates Database (data/google-updates.json)
• 2026 Active Schema.org Catalog (skills/seo-schema/references/schema-types-2026.md)
• Deprecated Schema Migration Guide (skills/seo-schema/references/deprecated-types-guide.md)
• Semantic SEO EAV Methodology Reference (skills/seo-content/references/semantic-eav-methodology.md)
• 10-Principle Falsifiable Thinking Framework (skills/seo/references/thinking-framework.md)
• Helpful Content Fluff Removal Rubric (skills/seo-content/references/helpful-content-humanizer.md)

---

📜 License & Open Source

SEO Skills AI is released under the MIT License — free forever for personal, consultant, agency, and enterprise commercial use.

• Web Portal & Documentation: seoskillsai.com
• GitHub Repository: github.com/seoskillsai/seo-skills-ai
• Community Issues: GitHub Issues