agentic-seo: auditing your docs for AI coding agents

The problem agentic-seo targets: agents read docs differently

The README makes a specific claim about behaviour: AI coding agents such as Claude Code, Cursor, Cline and Aider issue single HTTP requests, strip HTML, count tokens, and then either keep your content as context or discard it silently. That last word matters. A human who hits a JavaScript-dependent docs page waits for hydration and reads the rendered result. An agent that fetches the same URL and gets an empty shell has no fallback and no error message.

So the failure mode this tool is built around is invisible. Nothing in your analytics necessarily tells you an agent tried and gave up. The project's answer is a structural audit: ten checks, five categories, scored out of 100, aimed at whether the artefacts agents look for exist and whether the pages they fetch are small enough and clean enough to be worth the context window.

The intended audience is narrow and identifiable. It is people who maintain developer documentation, API references and marketing sites for technical products, and who already accept that agent traffic is a channel worth preparing for. If your site is a brochure for non-technical buyers, the checks here will mostly return noise.

What the ten checks actually measure

The scoring is split into five weighted categories. Discovery carries 25 points across three checks: robots-txt (10) looks for AI crawlers that are not blocked and for explicit allow rules; llms-txt (10) looks for a structured index with descriptions and token counts; agents-md (5) looks for an AGENTS.md or CLAUDE.md file carrying project context.

Content Structure is another 25 points. content-structure (15) inspects heading hierarchy, semantic HTML, code examples and tables. markdown-availability (10) asks whether a Markdown source is reachable, whether the HTML is noisy, and whether rendering depends on JavaScript.

Token Economics is the third 25-point block: token-budget (15) measures per-page token counts and flags oversized pages, while meta-tags (10) looks for AI-friendly meta tags, descriptions and token-count metadata. Capability Signaling adds 15 points through skill-md (10), which wants capability descriptions, inputs and constraints, and agent-permissions (5), which wants access rules and rate limits. The final 10 points come from UX Bridge: copy-for-ai looks for copy-for-AI buttons, copy-to-clipboard controls and raw view links.

The weighting is a design statement. A site with perfect meta tags and no llms.txt cannot reach an A. Conversely, the 10 points for a copy button sit in the same table as the 10 points for not blocking ClaudeBot, which is a strange pairing: one is a human convenience feature, the other is a hard gate on whether an agent reaches you at all.

Installing agentic-seo and running a first audit

The README documents two install paths: a global npm install, or npx with no install at all. The package declares Node >=18.0.0 in its engines field, so check that first. The global route is:

npm install -g agentic-seo

After that, the binary is agentic-seo. The zero-install route is what most people will use for a first look, and it audits the current directory while auto-detecting the framework:

npx agentic-seo

You should see a score out of 100 and a letter grade. The README defines the bands: A is 90-100, B is 75-89, C is 60-74, D is 40-59, F is 0-39. If the auto-detection picks the wrong directory, point it at a path or name the build output explicitly:

agentic-seo ./my-project
agentic-seo --output-dir ./my-project/build

The README lists Next.js, Docusaurus, Eleventy, Astro, Hugo, Jekyll, Gatsby, VitePress, MkDocs, Sphinx and Vite as supported frameworks. For a live site rather than a local build, the URL flag runs the HTTP-based checks:

agentic-seo --url https://docs.example.com

When you want to see why a check failed rather than just the score, --verbose shows all findings including info-level messages. To narrow the run while iterating, --checks takes a comma-separated list of checker IDs:

agentic-seo --verbose
agentic-seo --checks robots-txt,llms-txt,token-budget

The README's own suggested order of work is to fix robots.txt first (it calls this preventing silent agent lockout, estimated at 10 minutes), then add llms.txt, then measure token counts, then write skill.md, then add copy-for-AI buttons, and only then set up AI traffic monitoring. That ordering is worth taking seriously because it front-loads the checks that gate everything else.

Configuration and CI gating

Project settings live in .aeorc.json at the project root, or under an "aeo" key in package.json. The README gives this shape, which sets the output directory, per-check options, an ignore list and a threshold:

{
  "outputDir": "_site",
  "checks": {
    "token-budget": { "maxTokensPerPage": 25000 },
    "robots-txt": { "requiredAgents": ["ClaudeBot", "GPTBot"] }
  },
  "ignore": ["**/node_modules/**", "**/vendor/**"],
  "threshold": 60
}

The threshold key is the CI lever. Combined with --json, the CLI exits with code 1 when the score falls below the threshold, which is the standard way to make a documentation budget enforceable in a pipeline:

agentic-seo --json --threshold 60

There is also a score subcommand for when you only want the number, and a scaffolding command that creates the missing AEO files:

agentic-seo score --json
agentic-seo init

According to the README, init creates llms.txt, AGENTS.md, skill.md and agent-permissions.json. Treat those as templates to fill in, not finished artefacts. A generated llms.txt with placeholder descriptions will not score well on the llms-txt check's own criteria, which ask for descriptions and token counts.

How the audit runs, and where the heuristics end

The mechanism is deliberately dependency-light. The README states the tool requires no API key, and describes five stages: framework detection to find the build output; file analysis for robots.txt, llms.txt, AGENTS.md, skill.md and agent-permissions.json; content analysis that parses HTML with Cheerio and Markdown with Remark; token counting through gpt-tokenizer; and an agent simulation step that evaluates what an agent would actually see when fetching a page.

The package.json confirms the shape of that pipeline. Cheerio, unified and remark-parse are runtime dependencies, as are gpt-tokenizer, glob, gray-matter for front matter, yargs for the CLI, chalk and ora for output, and serve-handler for the --serve mode that spins up a local server so the HTTP checks can run against a build directory.

That last detail is the honest boundary of the tool. Everything is structural or heuristic, computed from files on disk or from responses to a single fetch. The README is explicit that scores are directional guidance rather than guarantees of any outcome. Nothing here measures whether an agent actually cited you, how much agent traffic you receive, or whether a model's retrieval changed after your edits. The token counts are real measurements from a tokenizer, but the mapping from token count to whether an agent keeps your page is a heuristic the project chose. If you need outcome data rather than structural readiness, this tool will not produce it, and the README's own step six, setting up AI traffic monitoring, points outside the package.

Where agentic-seo is the wrong tool

Three cases stand out.

The first is a site whose content is genuinely behind authentication, a paywall or a client-side app with no static output. The checks assume there is a fetchable artefact. If your docs only exist after a login, robots.txt and llms.txt advice is largely inapplicable, and markdown-availability will fail for reasons you cannot fix without changing how the product serves content.

The second is a team that wants ranking or visibility outcomes. agentic-seo audits readiness signals. It does not connect to Search Console, does not measure impressions, and does not tell you whether adding llms.txt changed anything. The README's disclaimer is unusually direct on this: the concepts and recommendations are described as a best-effort community offering based on publicly available research and emerging practices, and the project states it is not an official Google project and is not endorsed by Google or Google Search.

The third is a project that cannot justify maintaining new files. The scoring rewards llms.txt, AGENTS.md, skill.md and agent-permissions.json. Each is another artefact that can drift out of sync with the actual API. A stale skill.md that describes an endpoint you removed is worse for an agent than no skill.md at all, and nothing in the check set appears to verify that the described capabilities match the shipped code. That is a maintenance cost the score does not show you.

Alternatives and how the approach differs

The closest conventional comparison is a general SEO auditing tool: it crawls your site and reports on titles, meta descriptions, canonical tags, sitemaps, link structure and Core Web Vitals, all aimed at search engine ranking. agentic-seo overlaps on meta tags and robots.txt but scores against a different consumer. Its token-budget check has no analogue in a classic SEO crawler, because a search engine does not pay a context-window cost for your page. Conversely, agentic-seo does not evaluate backlinks, page speed or indexing status, so it is not a replacement for that class of tool.

A second comparison is a general-purpose site linter or accessibility checker. Those enforce standards with defined pass and fail semantics. agentic-seo's checks are heuristics with point values, so a failure tells you a signal is missing, not that a specification was violated. That is a weaker guarantee, and it is the honest trade for covering a practice area where no settled specification exists yet.

A third option is doing nothing and relying on your existing Markdown sources. If your docs are already authored in Markdown and published with a static generator, you have solved the largest part of markdown-availability without any tooling. What agentic-seo adds in that situation is the measurement layer: per-page token counts and a repeatable score you can gate in CI, which is a real but narrower benefit than the category name suggests.

Editorial conclusion

Adopt agentic-seo if your documentation site is the product surface AI coding agents read, and you want a repeatable score in CI rather than a one-off manual review. Skip it if you need measured agent traffic, ranking outcomes or a hosted dashboard; the README offers none of those, and the tool explicitly calls its scores directional guidance. Before trusting a number, run agentic-seo --verbose on your own build output and read the individual findings, because a passing grade depends on files like llms.txt and skill.md that you have to write yourself.

Frequently asked questions

Official sources

1. addyosmani/agentic-seo on GitHub
2. Issues
3. License: MIT
4. README