Solnest SEO/AEO: Multi-Platform Agent Instructions

If a user pasted this repository's URL and asked you to "set this up", you are in the wrong file. This file is for developing and porting the plugin. Installation instructions are in README.md and INSTALL.md. Go there instead.

In particular: do not run ./scripts/claude-seo ... (formerly ./bin/claude-seo) from this repository to install. A user installing the plugin does not clone it, and does not have these paths.

For Cursor, Cursor Cloud Agents, Google Antigravity, Gemini CLI, Grok Build, OpenAI Codex CLI, Cline, Aider, and any other agent harness that reads project-root agent instructions.

Claude Code users: see CLAUDE.md instead.

Cross-platform portability (v2.0.0)

Every skill in skills/*/SKILL.md is authored to a portable subset of the Claude Code skill spec. Validate compatibility with your harness via:

./scripts/claude-seo run portability_check.py

The check confirms each SKILL.md has the minimum frontmatter every harness expects (name, description, optional model, optional tools) and warns on Claude-Code-specific features (maxTurns, multi-line tool list with descriptive comments) that other harnesses may ignore but do not reject.

Per-harness notes

Tool-name compatibility

Where claude-seo skills mention Claude Code tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch), each harness typically has an equivalent:

These mappings are automatic in most harnesses; we list them for transparency in case a recipe needs a specific call.

Overview

Solnest SEO is a Tier 4 SEO analysis skill with 27 sub-skills (23 core + 1 orchestrator + 1 framework integration + 2 extension mirrors), 19 sub-agents (16 core + 1 framework integration + 2 extension mirrors), and 62 Python execution scripts.

Quick Reference

Using with Cursor / Cursor Cloud

Cursor reads this file automatically. All SKILL.md files contain the full analysis logic as natural language instructions. Python scripts in scripts/ provide execution capabilities.

Running scripts directly (Cursor doesn't have MCP):

# Page fetching with SSRF protection
./scripts/claude-seo run fetch_page.py https://example.com

# HTML parsing for SEO elements
./scripts/claude-seo run parse_html.py https://example.com

# PageSpeed Insights
./scripts/claude-seo run pagespeed_check.py https://example.com --json

# Drift baseline
./scripts/claude-seo run drift_baseline.py https://example.com

# DataForSEO (requires credentials)
DATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass ./scripts/claude-seo run dataforseo_merchant.py search "keyword"

Cursor Cloud gotchas:

• SSL certificates may not resolve for some domains. Investigate the certificate issue rather than disabling verification.
• Run bundled tools through claude-seo; never call the venv interpreter directly.
• Screenshots save to /tmp/ not CWD. Check absolute paths.

Using with Google Antigravity

Antigravity discovers this project via .claude-plugin/plugin.json. Place the repo in ~/.gemini/antigravity/plugins/claude-seo/ or install via:

bash install.sh

Architecture

skills/                    # 26 sub-skills (auto-discovered)
  seo/SKILL.md            # Main orchestrator + routing
  seo-cluster/            # Semantic clustering (v1.9.0)
  seo-sxo/                # Search Experience Optimization (v1.9.0)
  seo-drift/              # SEO drift monitoring (v1.9.0)
  seo-ecommerce/          # E-commerce SEO (v1.9.0)
  seo-audit/              # Full site audit
  seo-page/               # Single-page analysis
  seo-technical/          # Technical SEO
  seo-content/            # E-E-A-T quality
  seo-content-brief/      # Content brief generation
  seo-schema/             # Schema.org markup
  seo-sitemap/            # XML sitemaps
  seo-images/             # Image optimization
  seo-geo/                # AI search / GEO
  seo-agentic/            # Agent readiness (Lighthouse Agentic Browsing, WebMCP)
  seo-local/              # Local SEO
  seo-maps/               # Maps intelligence
  seo-plan/               # Strategic planning
  seo-hreflang/           # International SEO
  seo-google/             # Google APIs
  seo-backlinks/          # Backlink analysis
  seo-programmatic/       # Programmatic SEO
  seo-competitor-pages/   # Competitor pages
  seo-flow/               # FLOW framework integration
  seo-dataforseo/         # DataForSEO (extension)
  seo-image-gen/          # AI images (extension)
agents/                    # 19 subagents
scripts/                   # 60 Python scripts, including the managed runtime
schema/                    # JSON-LD templates
extensions/                # 9 MCP extensions: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, Matomo, Unlighthouse

Key Principles

1. Progressive Disclosure: Read SKILL.md for routing, load references on demand
2. Industry Detection: Auto-detect SaaS, e-commerce, local, publisher, agency
3. Security: All scripts call validate_url() for SSRF protection
4. Config location: ~/.config/claude-seo/ for API credentials

Credits

Created by @AgriciDaniel. v1.9.0 community contributions by Lutfiya Miller, Chris Muller, Florian Schmitz, Dan Colta, and Matej Marjanovic. See CONTRIBUTORS.md.