Agentic SEO Explained: Addy Osmani's Toolkit + What Your Docs Score

What agentic-seo actually checks

Agentic SEO, in the addyosmani toolkit, grades a site across five categories totalling 100 points. Each category answers one question an AI agent has to resolve before it cites you, recommends you, or silently drops you out of context. The agentic SEO score is structural: every check is a HEAD or GET request away from a verdict.

• Discovery (25 points). Can the agent find your documentation in the first place? Three checks: robots.txt allowance for AI crawlers, presence of an llms.txt index file, and an AGENTS.md (or CLAUDE.md) at repo root.
• Content Structure (25 points). Once it has the page, can it parse what is on it? Checks heading hierarchy, semantic HTML, code examples, and whether you ship raw markdown alongside the rendered page.
• Token Economics (25 points). Does the page fit in the agent's context window? Counts tokens per page using gpt-tokenizer and grades meta tags for AI-friendliness.
• Capability Signaling (15 points). If your product has APIs, does each one carry a skill.md describing what it can DO, and an agent-permissions.json describing what is allowed?
• UX Bridge (10 points). Does the page expose a "Copy for AI" affordance for human-plus-agent workflows?

The framework lands on a clean grade scale: A for 90+, B for 75-89, C for 60-74, D for 40-59, F below 40. A small site that gets robots.txt right, ships an llms.txt, and answers four of the ten checks honestly will land in C territory before it touches the harder structural work.

What makes this useful is that it is not vibes. The CLI runs locally, exits with code 1 if you fail your threshold, outputs JSON, and slots into CI. You can wire it into a pre-deploy gate the same week you discover it.

We ran it on forkoff.xyz

Command: npx agentic-seo --url https://forkoff.xyz --json. Runtime: about 90 seconds. Output:

The flat read is brutal. Every founder we have shown it to has had the same moment of "wait, that bad?" The recovery sits one layer down, in the per-category breakdown.

Six of the ten checks issued warnings rather than failures because the checker needs filesystem access to read the page source, the markdown sibling, the per-page token count, and the meta tags before render. The 19/100 is the conservative read where every unscanned check counts as zero. The honest read on what HTTP-mode actually evaluated is 19 out of 30, or 63%, which is a low C.

That gap matters in two directions. If you ship agentic-seo results in your investor update without the asterisk, you are sandbagging. If you accept the 19 at face value and build a 6-week remediation plan, you are over-engineering. The right move is to read the source, run the local-mode audit on your build output, and fix the real problems.

The 4 wins, the 6 unrunnable, the 2 real gaps

What HTTP-mode actually told us, in order of weight.

Wins (held up clean):

• robots.txt 10/10. Our robots.txt explicitly allows ClaudeBot, Claude-Web, GPTBot, ChatGPT-User, Google-Extended, PerplexityBot, Amazonbot, cohere-ai, and Bytespider. Eighteen verified crawlers in total. No accidental block on the agents we spent six months building toward.
• llms.txt found. Lives at /llms.txt, indexes 37 documentation links across 59 sections, and ships helpful descriptions on each link. The companion /llmfull.txt carries the deep content.
• Allow rules explicit. No reliance on the Allow: * default, which an aggressive firewall rewrite could undo. Each crawler is named.
• llms.txt discovery score 8/10. Two points docked, one for the issue we cover next.

Unrunnable in URL-mode (need filesystem):

• content-structure (15 pts), markdown-availability (10 pts), token-budget (15 pts), meta-tags (10 pts), skill-md (10 pts), copy-for-ai (10 pts).

We will re-run with agentic-seo --output-dir ./build next. URL-mode is the wrong tool for those six.

Real gaps that bit:

• AGENTS.md missing (0/5). The entry-point file AI coding agents look for at repo root before they touch anything else. Our public marketing repo has no AGENTS.md. Easy fix.
• llms.txt is 24,710 tokens (warning). The recommended budget is 5,000. Ours is 4.9× over. The fix is to split into a thin index llms.txt and a fat companion llms-full.txt. Most agents pull the index first to plan their fetches, then pull the deep file only on the routes they need.

Both are config-level, not architecture-level. Together they account for the difference between a 63% C-mode score and an 80%+ B-mode score we expect after the 48-hour sprint.

How agentic engine optimization differs from old-school SEO

Addy's framing post splits hairs that matter, and Lenny's guest interview "The ultimate guide to AEO: How to get ChatGPT to recommend your product" walks the same ground in long-form video. AEO is not "SEO with AI in the name." It is a different consumption pattern that breaks several assumptions classical SEO took for granted.

Single-fetch consumption. Search engine crawlers index by following links over weeks. Agents do not do that. An agent receives a query, decides which one URL to fetch, issues the GET, and either uses the response or moves on. There is no "second page" of your docs. Your canonical content has to land in one fetch.

Token-budget gravity. Humans skim. Agents count. A page over the agent's effective token budget gets truncated mid-paragraph or rejected before it reaches the model. Pages over 25,000 tokens are often silently discarded by frontier-model context managers, even when the model's nominal context is much larger. The functional ceiling is roughly half the marketed one.

Structural-not-stylistic. Agents do not render JS. They do not load fonts. They do not parse CSS. The carefully designed hero section means nothing to them. What the agent reads is your semantic HTML, your code blocks, your tables, and the markdown you ship alongside the rendered output. If your page renders to a

The implication for ranking: you can hold position one in Google's organic results for "agentic seo" and still lose every agent citation to a markdown page on a static site that scored 90. Two ranking systems running side by side, on different rules.

AI agent SEO: what your skill.md should look like

The capability-signaling category is where most marketing sites collapse. A site can ace robots.txt, ship a clean llms.txt, structure content perfectly, and still be illegible to an agent trying to do something with the underlying product.

skill.md answers one question: what can your product DO from an agent's perspective? Not the API surface. Not the sales pitch. The capability list.

A FORKOFF clipping service skill.md looks like this in skeleton form.

```markdown # Clipping Service

Produce vertical short-form clips from podcast episodes.

SEO for AI agents: the 48-hour fix sprint

The fix list, prioritized by leverage and ordered by what we are actually shipping in the next two days.

Hour 0 to 4: Split llms.txt. Cut the existing 24,710-token file into llms.txt (5K, index of routes with one-line descriptions) and llms-full.txt (24K, current content). Add token-count annotations on every link in the index so agents can budget. Expected score lift: +2 on llms-txt (8 → 10).

Hour 4 to 8: Ship AGENTS.md. Create /AGENTS.md and /docs/AGENTS.md covering project structure, key file locations, dev environment setup, and FORKOFF coding conventions. Expected score lift: +5 on agents-md (0 → 5).

Hour 8 to 24: Author three skill.md files. Clipping, Podcast Engine, and the founder-growth playbook. Each follows the three-section anatomy above. Expected score lift: +10 on skill-md (0 → 10) once the local-mode audit runs.

Hour 24 to 32: Add agent-permissions.json. Define rate limits, allowed scopes for each crawler, and human-in-the-loop requirements for any sensitive route. Expected score lift: +4 on agent-permissions (1 → 5).

Hour 32 to 48: Token-budget pass on top 10 pages. Run agentic-seo --output-dir ./build. Trim or split any page over 25K tokens. Add token-count meta tags. Expected score lift: +25 across token-budget and meta-tags once local-mode runs.

Projected post-sprint score: roughly 70-80 on the local-mode run, depending on how the content-structure check evaluates the existing markdown sibling files. We will re-run and publish the delta.

Where addyosmani's framework stops, and outcome measurement begins

agentic-seo is the AEO equivalent of Lighthouse. Necessary, structural, repeatable, and a fine starting point for any team that has been winging it. What it cannot tell you is whether the structural improvements are translating into agent citations, qualified inbound, or revenue.

That is the layer FORKOFF measures. Every published page on forkoff.xyz carries qualified-view tracking. We instrument which agents fetched it, which queries surfaced the page in LLM citations, and which of those citations led to a session, a calendar booking, or a paid engagement. The number we hold ourselves to is $0.003 per qualified view across the AI agency vertical, with the qualified-view definition tied to a behavior signal at least as strong as 30 seconds on page or any conversion event. The same number governs every engagement we run inside the Podcast Engine tier and the founder-growth pillar cluster.

The relationship between the two layers is straightforward. addyosmani's framework is the input gauge. Qualified views are the output. A site can score 90 on agentic-seo and still get cited zero times if the underlying content does not earn the citation. A site can score 50 and rank inside three queries because the one page that exists is the canonical answer to the question.

Both numbers matter. Neither is sufficient alone.

The receipt

This post is the receipt of one repo, one live audit, and one 48-hour fix sprint we are running on the back of it. The framework is fresh, the scoring rubric is moving, and the right move for any team building agent-readable infrastructure right now is to run the audit, read the source, fix the obvious gaps, and ship a re-audit number publicly inside two weeks. The first credible voices on this topic in 2026 will be the ones with their own audit data, not the ones with vendor decks.