Architecture
Four layers. One registry. Zero orphans.
Most "AI SEO plugins" are a folder of Markdown files stapled together. Antigravity SEO treats commands, agents, skills and MCP data as first-class layers of one system — with a signed contract between them.
┌──────────────────────────────────────────────────────────────┐
│ You type: /seo audit https://acme.com │
└──────────────┬───────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ L1 Command router │
│ commands/audit.md → spawn seo-supervisor │
└──────────────┬───────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ L2 Agent orchestrator │
│ seo-supervisor.toml → skills = [ ... 65 allowed ] │
│ fans out to: technical-auditor · content-agent · ... │
└──────┬────────────┬────────────┬────────────┬────────────────┘
▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ L3 │ │ L3 │ │ L3 │ │ L3 │
│ skill│ │ skill│ │ skill│ │ skill│
└──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
└───────────┴──────┬────┴───────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ L4 Data plane │
│ DataForSEO · Firecrawl · GSC · GA4 · CrUX/PSI │
└──────────────────────────────────────────────────────────────┘
▼
ranked findings + fix planSlash commands
Entry points you type. Each command is a routed intent, not a script — it decides which agent to spawn.
Agents
Specialists with a signed skill list. An agent can only call skills the registry says it owns — no hallucinated tool calls.
Skills
Atomic capabilities with a SKILL.md contract: inputs, outputs, when-to-use. Grouped by six domains.
Data sources
Real market and first-party data behind the skills. Verified per-install; missing keys downgrade skills, they don't crash them.
No hallucinated tools
The registry validates every agent-skill link at build time. An agent referencing a missing skill fails the build, not a user's audit.
No dangling skills
All 65 skills are claimed by at least one agent. Orphan detection runs on every registry build — count today: 0.
No black-box installs
The plugin lives entirely under ~/.gemini/extensions/seo/. Uninstall reverts settings.json; no leftovers.
Self-healing
verify_environment.py --json returns a machine-readable failure map. Any Antigravity agent can parse it and fix itself.
Recovery loop
When install fails, the fix is one paste.
Instead of a cryptic error, the installer writes a structured Markdown prompt to ~/.gemini/logs/antigravity-seo/last-error.md — plus a machine-readable JSON block from verify_environment.py --json. Paste it into Antigravity CLI / IDE, Claude or Codex — the agent parses it and self-installs.
{
"ok": false,
"required": [ { "name": "python3", "ok": true, "version": "3.11.7" } ],
"registry": { "ok": true, "counts": { "skills": 65, "agents": 32 } },
"optional_mcps": [
{ "name": "firecrawl", "enabled": false,
"fix": "Set FIRECRAWL_API_KEY from https://firecrawl.dev" }
]
}