optimize-loop

An SEO + AI-search (GEO) audit → fix → verify loop for AI coding agents. It finds defects with evidence, fixes them at the template, re-runs the exact check that flagged each one, and never auto-touches anything that can deindex a site. It runs against a local dev server for the fast loop and a production build for the final gate — so the site never needs to be published.

Built as a Claude Code skill, but the method is agent-agnostic — see Using it with other agents.

Three rules run through everything:

1. Deterministic checks before judgement. Scripted checks produce the findings; the model's judgement layer only adds what a script can't measure, and always quotes what it read.
2. Every fix is verified by re-running the check that flagged it. A fix isn't done until that check passes and a full re-run shows nothing regressed.
3. Verify the volatile layer. Crawler tokens, Core Web Vitals thresholds, and which schema still earns a rich result move constantly — the dated facts are re-verified against the primary source before they're relied on.

Most SEO tools either just lint (audit-only) or drift into snake-oil (ranking promises, llms.txt magic, fabricated schema). This one closes the loop — it fixes and proves the fix — while refusing to invent facts or claim rankings, gating every change that could deindex a site (canonicals, robots, noindex, redirects, sitemaps) behind an explicit human yes, and keeping its volatile facts dated and verified so the advice doesn't go stale.

EXAMPLE.md walks a full condensed run on a freshly built site — coverage, a placeholder catch, the AI-rendering gap, a gated robots.txt decision, template-level fixes, and re-verification — showing where it stops and asks rather than inventing.

git clone https://github.com/devonbweaver/optimize-loop ~/.claude/skills/optimize-loop

Or clone anywhere and symlink (keeps git pull easy):

git clone https://github.com/devonbweaver/optimize-loop
./optimize-loop/install.sh

Restart Claude Code, then:

/optimize-loop

or just ask: "audit my site for SEO and AI search." Point it at a dev server for the fast loop; it uses a production build for the final gate. Requirements: Node.js 20+, a shell, and the site reachable over HTTP.

The loop is a methodology. In Claude Code it's this skill. Elsewhere: drop SKILL.md into the agent's rules/system prompt and run the checks in references/checks.md as shell commands — they're plain curl/node, agent-agnostic. Keep the gated-change rule: that safety boundary matters most where a tool can edit files and a wrong canonical or noindex can deindex a site.

SKILL.md                         # the audit → fix → verify loop (9 phases, 3 rules)
EXAMPLE.md                       # a full condensed run
seo.config.example.json          # the business/thresholds config (copy to seo.config.json)
references/
  checks.md                      # the deterministic, runnable checks
  seo-reference.md               # durable traditional SEO (crawling/indexing, on-page, schema, CWV, i18n, local, authority)
  ai-search-reference.md         # AI/generative optimization (how AI search works, crawler taxonomy, the JS-rendering gap, GEO levers, rubric)
  current-facts.md               # the dated volatile layer — re-verify each run (crawler tokens, CWV, deprecated rich results, llms.txt)

MIT — see LICENSE.