SEO for AI AgentsOpen-source · MIT · 26 skills
A drop-in skill pack for AI coding agents.
Build sites that search engines rank and AI assistants are eligible to name.
Six agents, one per system. Meet the department$ claude "audit my site's SEO"
Analyzing built output from /dist...
✓ Access rung 1: Reach (HTML serves content)
✓ Access rung 2: Read (metadata & Core Web Vitals)
✗ Access rung 3: Understand (missing JSON-LD)
Fixing rung 3...
↳ Injected SoftwareApplication schema into index.html
↳ Added Organization schema to /about
Ready for review. Run `git diff` to see changes.
Sound familiar?
You vibe-coded a new app over a weekend. It looks great, the design is clean, the demo works. You ship it, and weeks later: nothing. No search traffic, no AI tools mentioning it.
The build is quietly full of SEO problems you can't see in a browser: an empty HTML shell that crawlers receive, missing titles and metadata, no structured data, pages wired to nothing. The site exists for a human with a browser, and barely exists for a search engine. That's the gap this closes.
Start where you actually are
Which of these are you saying right now?
Nobody arrives asking for "the Access system". They arrive because the site dropped, or they are about to launch, or they want ChatGPT to mention them. Each situation is a job: it decides which system leads, what order to work in, and how much the agent may do on its own.
“I have an idea and I am about to build it”
The only time you can get it all right first. Read the demand before writing code, and find out early if nobody is searching for this.
“We are going live this week”
Triage with a deadline. Blockers that make you invisible, checked on the real production URL, then everything else next week.
“Something is wrong and I do not know why”
Find what changed and when, before touching anything. Guessing wastes the one advantage you have: a before and an after both exist.
“It works, and I want more of it”
Nothing is broken, so a technical audit will find nothing that matters. Work out whether the constraint is demand, substance or authority.
“The URLs are changing”
The highest-stakes job there is. Inventory everything before you change anything, because you cannot enumerate a site that is already gone.
“I need a lot of pages”
Mostly a quality gate. The work is deciding which pages deserve to exist, and the honest answer is usually far fewer than you asked for.
“I want AI assistants to recommend me”
There is no lever here. Identity leads, eligibility is the ceiling, and anyone promising a citation is overselling.
“I need to audit a site I do not control”
Observe only, and the report is the product. Find the constraint and prove it, rather than listing ninety imperfections.
“Keep it from breaking”
Visibility decays. Re-verify what was fixed, catch the regression a deploy introduced, and report even when nothing happened.
Each job is written out in the pack, with its order of work and the things it must never do. Read the nine jobs.
What's going wrong → what the pack does
My AI-built site isn't showing up in Google
Finds why crawlers can't see it, and fixes it
I edited the code but search didn't change
Verifies on the served HTML, not the source
I want to rank, not just look good
Works all five systems, because ranking is what they produce
My site is slow or clunky on mobile
Diagnoses Core Web Vitals and mobile, fixes the causes
Engines don't understand my pages
Adds valid, honest structured data they can read
I can't risk breaking what already ranks
Audits safely, preserving URLs, canonicals and what works
Fixes keep silently breaking on deploys
Re-audits and catches regressions, even in CI
I'd also like AI answers to name me
Works the eligibility an assistant surface rewards
Tuned to your site
What are you building?
The method is the same for every site; where sites fail is not. Pick your kind of site to see the failures the audit hunts first. Each has a full guide, and a profile in the pack that tunes the audit automatically.
SaaS & product marketing
The classic failure: The marketing site is an SPA that serves crawlers an empty shell.
- Marketing pages client-rendered, invisible in the served HTML
- Vague 'platform that empowers teams' copy matching no real query
- Pricing hidden inside a JavaScript-only widget
- Thin 'alternatives' pages that add no real value
Priority tilt
Check Access first and hard, because rendering is usually the floor. Then Substance (intent-matched clarity) and Identity (one provable company entity), which is what makes you eligible on assistant surfaces too.
Or browse all seven use-case guides.
Why doesn't it rank?
AI-built sites often look perfect in a browser but are nearly invisible to crawlers. Coding agents frequently edit JSX and declare "meta tags added" without verifying what's actually served in the built HTML. If a crawler receives a blank <div id="root">, your site can't rank, because to a search engine it isn't there.
Ranking is the goal, and it is not a single step you can take. It is the outcome of five things being true at once: you have read what people actually ask, an engine can tell who you are, the page is worth choosing, a machine can reach and read it, and something credible points at you. The same five decide whether an AI assistant like AI Overviews, ChatGPT or Perplexity is even eligible to name you. An assistant is another surface, not a layer bolted above the basics.
Most AI-built sites fail on the first of those a machine meets: they are unreachable or unreadable, which caps everything else. This skill pack fixes that first, then works the rest.
See it on the served HTML
A site built as a single-page app looks perfect in your browser, and serves crawlers an empty shell. The pack checks what's actually served, and fixes it.
<body>
<div id="root"></div>
<script src="/app.js"></script>
</body>
# curl returns an empty shell.
# No headings, no copy. Invisible.<main>
<h1>Web design that converts</h1>
<p>Award-winning studio in Leeds…</p>
</main>
# curl now returns real content.
# Crawlable. Indexable. Citable.<head>
<meta charset="utf-8">
<meta name="viewport" ...>
</head>
# No title, no description.
# Nothing to show in the results.<head>
<title>Web design that converts | Studio</title>
<meta name="description" content="…">
<link rel="canonical" href="…">
</head>
# A real title and snippet.
# A reason to click.<!-- nothing here -->
# Engines can't identify what
# this page actually is.<script type="application/ld+json">
{ "@type": "Product",
"name": "…", "offers": {…} }
</script>
# A real entity, honestly marked up.
# Eligible for rich results.Verified by re-fetching the page, not by trusting that a source edit worked.
The Visibility Model
Five systems, one loop
Visibility is not a climb. It is five systems held true at once, separated by how much control you actually have: you observe Demand, you build Identity, Substance and Access, and you earn Distribution. Click any system to see what it checks.
Operations
The loop around all fiveMeasure, verify on the served output, catch regressions, report, repeat. Visibility decays: a fix verified in March is undone by a deploy in April, so every finding that was fixed stays watched, and a regression reopens itself.
Inside Access
The Visibility Ladder, four rungs
Dependency runs one way here and nowhere else in the model: the lowest broken rung quietly caps everything above it. So the pack diagnoses top to bottom and fixes bottom to top, and verifies each rung on the served output rather than the source.
Rank is not a rung you climb to. It is the outcome all five systems produce together, on a surface you have chosen, kept true by the loop. An AI assistant is one of those surfaces rather than a layer above them: being named draws on all five systems at once, and it can only be sampled, never measured the way a ranking is. So eligibility is the only outcome anyone should ever claim.
Six agents, six sets of fences
It is a department, not a button
Each system has a role that owns it, and each role has its own fences: what it may do on its own, what it has to ask you about, and what it will not do at any level. "Let the agent do SEO" is not a decision anyone can make safely. This is.
Demand Analyst
Demand
Observed
What are people and machines actually asking, and which of it is worth having?
Reads the demand instead of inventing it, and says which of it you could realistically hold. Reading this wrongly points every other system at the wrong target, perfectly executed.
Rung 1. Observe only
Invents a search volume or a difficulty score. A fabricated number is worse than none, because somebody will plan around it.
Identity Steward
Identity
Built
Who are you, provably, everywhere you appear?
Establishes the name, the places, the people, the credentials and the proof, and labels every fact established, inferred or unknown. An engine that cannot work out who you are has nothing to recommend.
Rung 3. Proposes, you approve
Fabricates an author, a credential, a review or an address. No approval path, at any level.
Content Editor
Substance
Built
Is what you offer and say actually worth choosing?
Judges a page against the real intent and against what already ranks, then improves what exists. Where something genuinely needs writing, it briefs a human instead of filling the gap.
Rung 2. Recommends, edits what exists
Generates filler, invents a statistic, or bumps a date to simulate freshness.
Technical Engineer
Access
Built
Can a machine reach it, read it, understand it and move through it?
Works the Visibility Ladder, diagnosing top to bottom and fixing bottom to top, and verifies every fix on the served output rather than the diff. Also guards the gates that stop it regressing.
Rung 3. Proposes, you approve
Changes a canonical, a redirect or robots rules unasked. A wrong one is a self-inflicted outage.
Distribution Strategist
Distribution
Earned
Does anything outside your control point at you or stock you?
Quantifies the authority gap against named competitors, says honestly whether authority is even the constraint, and writes the angle. Then hands all of it to a person.
Rung 2. Advises, never acts
Sends outreach, posts anywhere, or buys a link. The only role that cannot act at any level, by design.
Account Reporter
Operations
The loop
What does a human actually need to decide?
The only one that writes for you rather than for a machine. Turns findings into something you can act on, and carries each one's confidence through instead of flattening it into an assertion.
Rung 2. Writes, you decide
Publishes a forecast, invents a metric, or reports a fix without evidence from the served page.
And the seat none of them sits in
What should we actually do, and is this good enough to publish?
The agents have no taste, no strategy and no accountability. Someone still has to decide what the site should say, judge whether a draft is any good, and own the call when a change goes wrong. That part has not been automated, and this pack does not pretend otherwise. Why human judgement wins.
It's an audit that remembers
Not a one-shot fix. The pack writes a .seo/ folder into your project, so every run builds on the last, and catches regressions before they cost you.
First run
Audits all five systems, fixes the safe wins, and records a baseline, a readable report, an issue tracker, and a history.
Every re-run
Re-verifies past fixes on the served HTML, catches regressions (a fix that quietly broke in a deploy), finds what's new, and advances.
In CI, automatically
Wire it into a deploy/PR check so a change that makes your site uncrawlable fails the build, not weeks later in lost traffic.
.seo/
├── audit.md # readable scorecard
├── state.json # every issue + status
└── log.md # dated run historyA skill for every part of SEO
Twenty-six skills, grouped by the system each one serves. The orchestrator routes broad requests; reach for a specialist when you already know the job. Hover any skill for the technical detail.
Start here
Demand: what is actually being asked
Identity: who you provably are
Substance: whether it is worth choosing
Access: the Visibility Ladder, and its specialists
Distribution: what points at you (earned, advisory)
Operations: keeping it true
Surfaces: where visibility is judged
Use it well
Powerful, and only as good as your judgement
The agent verifies, executes and remembers; you decide, review and own. The guide is the honest manual: why human judgement always wins, the six habits that make this pack compound, and the short list of things you should never let an agent do.
How do I install SEO for AI Agents?
Fastest start, paste this into your agent
No setup. Drop this prompt into Claude Code, Cursor, or any AI coding agent and it audits your site and reports back. It won't change anything until you ask it to.
Use the seo-for-ai-agents skill pack (https://github.com/manibharij/seo-for-ai-agents): audit my site against the Visibility Model (Demand, Identity, Substance, Access, Distribution), checking on the served HTML. Do not change any code or files yet. Report anything blocking Access first, since nothing else counts if a machine cannot reach the page, then a prioritised list of issues with the recommended fix for each in plain English. Never fabricate authors, reviews, or trust signals.
More prompts you can paste straight away
Once the pack is installed, reach for the right job. Each one is read-only: it analyses and reports, so nothing changes until you decide. Swap the bracketed parts for your own details.
Using seo-for-ai-agents, analyse why [paste URL] isn't ranking. Work top-to-bottom through the Visibility Ladder inside Access on the served HTML, identify the lowest failing rung, then check Substance and Identity, and explain the root cause. Report your findings only, don't change any code or files.
Using seo-for-ai-agents, run a read-only SEO audit of my site. Diagnose each of the five systems on the served HTML and give me a prioritised list of issues with the recommended fix and the risk of each. Don't edit any files, just report.
Using seo-for-ai-agents, review the structured data on my pages. Check what's present in the served HTML, flag anything missing, invalid, or not matching the page, and recommend honest schema to add. Report only, don't change anything.
Using seo-for-ai-agents, I'm about to change my URLs / redesign / move domains. Inventory the current URLs and give me a recommended 1:1 301 redirect map plus a pre-launch checklist. Just produce the plan, don't apply any changes.
Using seo-for-ai-agents, analyse my Core Web Vitals and mobile experience on the served pages. Identify the build-time causes (images, fonts, JavaScript, layout shift) and tell me which to address first. Diagnosis only, don't change code yet.
Using seo-for-ai-agents, assess whether my pages are eligible to be named by AI answer engines. Review only, don't change anything: check answer formatting, entity consistency and attribution on the served HTML, and tell me what to improve. Report eligibility only, and don't claim or estimate citations.
Install into your agent
Drop the skills folder into your agent's config directory or copy-paste a mini. No complex setup.
Ask it to audit your site
Tell your agent: 'Audit my SEO'. It detects your stack, finds what's failing across the five systems, and dispatches fixes.
Review and approve
The agent explains every change in plain English. You decide what to publish. All fixes are reversible.
Supported Environments
Claude Code
~/.claude/skills/
Cursor
.cursor/rules/
AGENTS.md
For Codex, Zed, Gemini CLI
Copy-paste Minis
Zero config needed
Is SEO for AI Agents right for you?
For
- Developers and marketers who vibe-code with AI agents
- Anyone building a new site with Claude Code, Cursor, or Codex
- Developers whose AI-built site isn't showing up in Google
- Agencies and consultants who audit client sites
- Existing sites that need SEO health maintained over time
Not For
- Anyone expecting guaranteed rankings or citations
- People without an AI coding agent
- Those wanting live rank-tracking or backlink tools
- Black-hat or spam SEO
What doesn't SEO for AI Agents do?
Key distinctions
- Builds your owned media; analyses and advises on earned media, never executes it
- Verifies on served HTML, not just source code edits
- Strictly white-hat, never fabricates authors, experience signals, or reviews
- Works for existing sites too (protects URLs and canonicals that already rank)
- Reports eligibility on assistant surfaces, never a guaranteed citation
The honest question
Can AI agents replace SEO professionals?
No, and anyone promising otherwise is overselling. Strategy, judgement and hard-won experience don't come in a skill pack. But that was never the point. This puts a rigorous, white-hat SEO method in your agent's hands and runs it like continuous testing: a tireless audit that checks the fundamentals on every build, shows you what's wrong, and waits for you to decide. A force-multiplier for an SEO professional, and a safety net for everyone building without one.
It assists, it doesn't replace
The method is rigorous, but it has no taste, no strategy and no accountability. A human still owns the calls that matter. Treat its output as a well-argued draft from a fast junior, not a verdict, and keep evaluating it as the professional you are (or hire one).
A considered bet on where this is heading
Using it now is a wager that coding agents keep getting better at SEO, and that the people who learn to direct them well compound an edge. It is built to grow more capable as the models do, so you are testing and learning early, not late.
It changes nothing unless you say so
By design it audits and reports first, and makes no edits to your code until you have reviewed the findings and told it to proceed. Continuous testing on your terms, with nothing touched behind your back.
It is at its best on new or recent builds that aren't ranking yet, laying clean foundations from the start, and as a constant second pair of eyes for an SEO professional on an established site. It cannot guarantee rankings or citations; those depend on factors no tool controls. Built on a fifteen-year, white-hat SEO mindset, to do the right things well and leave the decisions to you.
Frequently asked questions
What is the Visibility Model?
It's the method behind the pack: five systems that produce visibility, separated by how much control you actually have. You observe Demand, you build Identity, Substance and Access, and you earn Distribution. An Operations loop keeps all of it true as the site changes. Rank is not one of the five; it's the outcome they produce together.
Where did the Visibility Ladder go?
It is now the Access system, and inside Access it works exactly as before: four rungs, Reach, Read, Understand and Connect, diagnosed top to bottom and fixed bottom to top. Rank is no longer a rung, because it was never a step you could climb to. Search intent and quality moved to Substance, and real experience, expertise and authorship moved to Identity, which is where that work actually happens.
Does it guarantee rankings or AI citations?
No, and anything that promises guaranteed rankings is misleading. It fixes build-time, owned-media SEO and improves your eligibility to rank and to be named by an assistant. Whether a search engine ranks you, or an AI engine cites you, depends on competition, demand, and authority outside any tool's control.
Does it work on existing sites, or only new ones?
Both. On an existing site it audits without regressing what already ranks: it preserves URLs (adding redirects if any must change), respects intentional canonicals and noindex rules, and flags bigger changes for you to approve first.
What about WordPress, Shopify, or Webflow?
The diagnosis works on any site, because it reads the served HTML. On hosted platforms the fixes often live in the platform's settings or theme rather than code, so the agent tells you exactly what to change, rather than editing code it doesn't control.
Is it free? Do I need paid data tools or API keys?
It's free and open-source (MIT), and needs no paid data to work. You can optionally connect your own Search Console, DataForSEO, or Ahrefs keys to sharpen the audit, but nothing is paywalled or required.
Will it change my code without asking?
It applies safe, clearly-correct fixes and explains each one in plain English. Risky changes like restructuring URLs, removing content, or authorship and trust decisions are flagged for you to approve. You review before publishing, and everything stays in version control.
Which AI coding agents does it work with?
Claude Code, Cursor, and AGENTS.md hosts (Codex, Gemini CLI, Zed) via the skills, or a copy-paste mini in any chat. It's a skill pack the agent reads, not a separate app to run.
Does it work for my kind of site: a shop, a blog, a SaaS, a local business?
Yes. The pack ships eleven site-type profiles that tune the audit: e-commerce, SaaS marketing, local business, blogs and content sites, documentation, news publishers, marketplaces and directories, affiliate and comparison sites, and portfolios, plus two modifiers you combine with those: international, and YMYL for health, legal, finance and safety. The orchestrator detects your site type itself and applies the right profile, weighting the checks that matter most for it.