agentleFS
devonbweaverdevonbweaver/optimize-loop/SKILL.md

optimize-loop

Skill0 starsChanged 3 months agoMITView on GitHub

Audit a site for SEO and AI-search readiness, then FIX what it finds and re-verify each fix — a closed audit → implement → verify loop. Use whenever the user mentions SEO, search visibility, AI/LLM/generative search readiness, metadata, titles, canonicals, structured data / schema, Open Graph, sitemaps, robots.txt, internal linking, crawlability, headings, alt text, or asks whether a site is "ready to launch", "findable", or "optimized" — even if they never say SEO. Also use it proactively right after building or substantially changing a site, since pre-deploy is when these fixes are cheapest. Works 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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. chuang44-tiff/optivibe-mcp★ 19same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the fast loop against whatever is reachable over HTTP — a dev server is fine for structure, metadata, schema, headings, links, content.

    line 49
  2. Distinctive:

    Run the deterministic checks across a crawl.

    line 73
  3. Distinctive:

    Coverage first: If pages failed to fetch or the crawl hit its limit, say so before anything else.

    line 74
  4. Very specific:

    Read references/ai-search-reference.md (how AI search works + the judgement rubric) and assess the fetched page text for content quality, …

    line 105
  5. Very specific:

    Run a final audit against a production build.

    line 140
  6. Distinctive:

    No finding, and no fix, without observed evidence.

    line 152
  7. Distinctive:

    Every fix re-verified by the check that flagged it.

    line 154
  8. Distinctive:

    Never invent business facts, authors, statistics, reviews, or credentials.

    line 155
  9. Distinctive:

    Never claim a change improves rankings, traffic, or indexing, or that a page will be cited by any AI-search product.

    line 157
  10. Very specific:

    No black-hat: keyword stuffing, hidden text, doorway/bulk-generated pages, schema that doesn't match visible content, llms.txt as a ranking …

    line 159

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

optimize-loop

A closed loop for SEO + AI-search readiness: find defects with evidence, fix them at the template, and re-run the exact check that failed to prove each fix cleared — looping until only human-decision or deploy-day items remain. It fixes; it does not guess, fabricate, or quietly touch anything that can deindex a site.

Two rules run through everything:

  1. Deterministic checks before judgement. Scripted checks (references/checks.md) produce the findings. The model's judgement layer only adds what a script can't measure — content quality, passage retrieval, information gain — 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 else regressed. A check that would also pass on the pre-fix page is not a check.
  3. Verify the volatile layer. Crawler tokens, Core Web Vitals thresholds, and which schema still earns a rich result change constantly. Treat references/current-facts.md as dated — re-verify any high-stakes or stale (>~3 months) item against the primary source (Google Search Central, the crawler owner's docs, schema.org) before acting.

The full knowledge base lives in references/: seo-reference.md (durable traditional SEO), ai-search-reference.md (AI/generative optimization), current-facts.md (the dated volatile layer), checks.md (runnable checks). Load the one for the category you're in.

Dev vs production

  • Run the fast loop against whatever is reachable over HTTP — a dev server is fine for structure, metadata, schema, headings, links, content.
  • Content must be in the server HTML. AI crawlers (GPTBot, ClaudeBot, PerplexityBot) do not execute JavaScript — client-rendered content is invisible to AI even when it ranks in Google. Check the curl HTML, not the browser DOM; if content only appears after client render, that's a build-sensitive finding: needs SSR/SSG. Confirm on the production build.
  • Build-sensitive and deploy-gated checks settle only on a production build or the live origin: static generation vs client-only render, minification, no dev/HMR scripts, server-rendered meta, canonical host, status codes, redirects, response headers, sitemap at the real origin, Core Web Vitals field data. Never call the site done until a production build (next build && next start, vite build && vite preview, astro build && astro preview, …) passes clean.

Phase 0 — Preflight

Confirm the site is reachable (if not, ask them to start it, or start it only with their ok). Note whether you're on dev or a prod build. Find the source that renders the pages (framework + templates/components) so fixes land at the template, not per-route. Locate or seed seo.config.json (copy seo.config.example.json); its business block is what makes later runs quiet.

Phase 1 — Audit

Run the deterministic checks across a crawl. In order:

  • Coverage first. If pages failed to fetch or the crawl hit its limit, say so before anything else. Never describe a page that was not fetched.
  • The door, before the shell. robots.txt states a policy; the CDN/WAF decides the reality. On the live origin, fetch as each citation bot and confirm the edge isn't 403ing it, serving a challenge, or feeding it different HTML (checks.md — Access). A locked door makes every downstream check moot, and it is the most-missed failure: robots can say allowed while the edge blocks. Live-origin only — a dev server has no CDN, so this settles at the production gate (Phase 8), not the fast loop.
  • Placeholders first among findings. Example domains, 555 numbers, lorem, unreplaced {{tokens}}, "Your Company", TODO — highest risk on a fresh site. Never build structured data from a value flagged as a placeholder.
  • Group by template, not route. Present the file to edit and the number of routes affected. Don't re-list every URL.
  • Split confidence. Fix = unambiguous. Look = heuristic/judgement. Never merge them or present a Look as settled fact.
  • Run the AI-readiness check. Is the content in the served HTML (visible to non-JS AI crawlers)? A CSR-only shell is a build-sensitive finding, not "meta missing."
  • Surface the AI-crawler decision. The robots.txt policy — block training (GPTBot, Google-Extended, ClaudeBot) while staying eligible for citation (OAI-SearchBot, Claude-SearchBot, PerplexityBot) — is a gated decision, not a routine finding. Present the tradeoff from current-facts.md; never auto-set it.

Phase 2 — Confirm business facts

Walk the facts table with the user. Rows arrive pre-filled from what the site renders, each with a source; the user confirms or corrects; confirmed values go into the business block of seo.config.json and the table stays quiet next run. Never invent a value for a missing row.

Phase 3 — Judgement layer

Read references/ai-search-reference.md (how AI search works + the judgement rubric) and assess the fetched page text for content quality, front-loaded answers, passage-level retrievability, information gain, and entity clarity. Every judgement names the page and quotes what you actually read — never "fix" a content truth by inventing something plausible.

Phase 4 — Plan (show it before editing)

List the fixes, each tied to its template and the check it will clear. Separate:

  • Safe to implement — titles, descriptions, missing alt text, OG/Twitter tags, heading structure, valid schema from confirmed facts, internal-link fixes.
  • GATED — never auto-applied. Canonicals, robots.txt, redirects, indexability (noindex/nofollow), sitemaps, hostname normalization. A wrong canonical or a stray noindex can deindex the whole site. Propose the change, state its blast radius, and require an explicit human yes before touching it.

Phase 5 — Implement

Fix at the template/source (one file, N routes), matching the surrounding code, using only confirmed or observed values. If a schema/meta field needs a value that isn't confirmed, stop and ask — never fabricate a fact, author, statistic, review, or credential to fill a field.

Phase 6 — Verify

Re-run the exact checks that failed: each targeted finding must now pass (evidence it cleared), and re-run the full set to catch regressions (a fix that broke another page fails here). Verify build-sensitive findings on the production build.

Phase 7 — Loop

Repeat 4–6 until only gated / human-decision or deploy-day items remain. No fixed round count. The exit is a clean re-audit, or the user stopping.

Phase 8 — Production gate + deploy-day checklist

Run a final audit against a production build. Report host/CDN items — status codes, redirect chains, response headers, CWV field data, and crawler access (does the edge actually let each citation bot in, or does bot-management 403/challenge it — checks.md Access) — as launch-day checks, naming who sets each (host/CDN, not something you settle now).

Phase 9 — Report

What was fixed (with before → after evidence), what's still gated and awaiting your decision, what's deploy-day, and what judgement you added (each with page + quote).

Rules you do not break

  • No finding, and no fix, without observed evidence. Missing data → say what's missing and what would settle it.
  • Every fix re-verified by the check that flagged it. A fix nobody re-checked isn't done.
  • Never invent business facts, authors, statistics, reviews, or credentials. Missing value → stop and ask.
  • Never claim a change improves rankings, traffic, or indexing, or that a page will be cited by any AI-search product. Report readiness, defects, and what you changed.
  • No black-hat: keyword stuffing, hidden text, doorway/bulk-generated pages, schema that doesn't match visible content, llms.txt as a ranking device.
  • Gated changes (canonicals, robots, redirects, indexability, sitemaps, hostname) are never auto-applied — propose, explain the blast radius, require explicit human ok.
  • Structured data only from values that are confirmed and match visible content.
  • Judge AI-readiness from the served HTML, not the rendered DOM — AI crawlers don't run JS, so client-only content doesn't exist to them.
  • Judge AI access from the live origin, fetching as the crawler — not from robots.txt alone. A stated allow doesn't mean the CDN/WAF lets the bot through; the edge can 403 or challenge an allowed bot. CDN/WAF bot-management is GATED — never toggle it silently.
  • llms.txt is not a ranking/citation lever (no major engine uses it) — don't recommend it as one; its only real use is dev-doc tooling.
  • Fix at the template, never per-route.

Using it with other agents

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

Where things live

  • seo.config.json — the business block + thresholds; copy seo.config.example.json.
  • references/checks.md — the deterministic checks (how to run, pass criteria, confidence, gated/build/deploy).
  • references/seo-reference.md — the durable traditional-SEO knowledge base (crawling/indexing, on-page, schema, CWV, international, local, authority).
  • references/ai-search-reference.md — AI/generative optimization (how AI search works, crawler taxonomy, the JS-rendering gap, GEO levers, judgement rubric).
  • references/current-facts.md — the dated volatile layer (crawler tokens, CWV thresholds, deprecated rich results, llms.txt) — re-verify each run.

Checks assert against rendered HTML, never a framework API, so framework upgrades don't reach them.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.