DEV Community

guardlabs_team
guardlabs_team

Posted on • Originally published at github.com

I built an open-source CLI that scores any site for AI-agent readiness (0-100)

#ai #opensource #python #seo

I built an open-source CLI that scores any site for AI-agent readiness (0-100)

TL;DR — agent-readiness-cli checks how well your site talks to ChatGPT, Claude, Perplexity and other AI agents. Single-file Python, standard library only, MIT.
Repo: github.com/sspoisk/agent-readiness-cli
Install: pip install agent-readiness-cli

The problem

Every "AI SEO" article in the last six months tells you the same three things:

  1. Add llms.txt
  2. Add JSON-LD with the right @type
  3. Decide what to do about GPTBot, ClaudeBot, PerplexityBot in robots.txt

What none of them give you is a tool that opens your site, looks at it the way a crawler would, and tells you what's actually missing right now.

So I built one.

What it does 

$ agent-ready https://example.com
✓ llms.txt               10/15  present, 4.2 KB, 12 URLs
✓ json-ld                23/25  3 block(s), types: Article, Organization, BreadcrumbList
✗ ai-bots-robots.txt      0/20  ClaudeBot, GPTBot disallowed at root
✓ canonical+hreflang     12/15  canonical=set, hreflang langs=['en','ru']
✗ mcp-card                0/10  no /.well-known/mcp.json (optional)
✓ meta                   10/10  10/10 of common signals
✓ sitemap                 5/5   valid, 1250 URLs

  Score: 60 / 100
  Tier: C  (middling — focus on ai-bots-robots.txt, mcp-card)
Enter fullscreen mode Exit fullscreen mode

One number for the whole site, plus seven sub-scores so you know what to fix first.

What gets checked, with weights

Section Weight What it looks for
llms.txt 15 presence, leading H1, at least 3 canonical URLs listed
json-ld 25 parseable, recognised @type, multiple distinct types
ai-bots-robots.txt 20 rules for GPTBot / ClaudeBot / Claude-Web / PerplexityBot / Google-Extended / CCBot / Applebot-Extended / Bytespider
canonical+hreflang 15 self-canonical, reciprocity, x-default for multi-lang
mcp-card 10 /.well-known/mcp.json valid JSON with name + description
meta 10 description, og:title, og:description, twitter:card, <html lang>
sitemap 5 /sitemap.xml exists, valid <urlset> or <sitemapindex>

Bands: A ≥ 90 · B ≥ 75 · C ≥ 55 · D ≥ 35 · F < 35.

I picked these weights based on what I see most often missing in the wild — JSON-LD is heaviest because it's the highest-leverage signal an LLM uses to understand your page kind. Disagree? All weights are in agent_ready/cli.py and contributors are welcome to challenge any of them.

Output formats for different jobs 

agent-ready https://example.com           # human summary (default)
agent-ready --full https://example.com    # human summary + every finding
agent-ready --json https://example.com    # machine-readable
agent-ready --csv https://example.com     # one row, append to your monitoring
agent-ready --quiet https://example.com   # just the score; exit code = band
Enter fullscreen mode Exit fullscreen mode

CI gate example

If you want your build to fail when the site drifts below a threshold:

- name: Audit AI-agent readiness
  run: |
    pip install agent-readiness-cli
    SCORE=$(agent-ready --quiet https://your-site.example)
    echo "AI-readiness score: $SCORE"
    [ "$SCORE" -ge 75 ] || { echo "below threshold"; exit 1; }
Enter fullscreen mode Exit fullscreen mode

That single integer-on-stdout is why --quiet exists.

What it does NOT do

  • It does not crawl your whole site — one URL at a time. If you want the whole site, drive it from a sitemap loop.
  • It does not fix anything. It tells you what to fix; the fix is on you.
  • It does not check for vulnerabilities — use OWASP ZAP for that.
  • It does not validate JSON-LD against the full Schema.org grammar. It checks that types are recognised; for Schema-strict validation, use Google's Rich Results Test.
  • It does not score Core Web Vitals or accessibility.

If any of those is what you actually need, this is not the right tool.

Why a single file

The whole tool is one Python file plus tests. No third-party dependencies. Standard library only.

A few reasons this matters:

  • Auditable. You can read every check in one go. No layer of abstraction hides what gets weighted.
  • Portable. It runs on any box with Python 3.10+. No pip install-and-pray.
  • No telemetry. It hits your URL only. Nothing else leaves the machine.
  • Forkable. If you want to add a check or change a weight, fork it. The whole thing is shorter than most config files.

I think the future of small dev tools is a return to this — one file, one job, no surprise dependencies.

Where it sits in the landscape

There are excellent generators (e.g. firecrawl/llmstxt-generator) that produce llms.txt files for you. There are validators for JSON-LD (Google's web tool, schema linters). There are MCP doc tools like langchain-ai/mcpdoc for exposing llms-txt to IDEs.

What didn't exist was the audit slice — a single CLI that opens your URL, looks at the agent-readiness surface end-to-end, and says "score 62, weakest links are X and Y." So I wrote that.

How to try it now 

pip install agent-readiness-cli
agent-ready https://your.site
Enter fullscreen mode Exit fullscreen mode

Available on PyPI and GitHub.

If you want continuous monitoring instead of one-off audits, I built it on top of Web-Audit Guardian — the same logic running every 30 min for a domain. The CLI is the audit slice as OSS; the continuous variant is the paid tier. Either way, the methodology is now public.

What's next

  • A --all mode that follows your sitemap and rolls up to a site-wide score
  • Optional check for ai.txt (Spawning's draft)
  • More AI bots if reasonable consensus emerges

Issues, PRs and disagreements with the weights all welcome. The repo is small enough that the bar to contribute is low.

Repo: github.com/sspoisk/agent-readiness-cli
License: MIT
Author: maintained by GuardLabs.

If you run it, let me know what your number is. Always interested to hear which check most surprised people.

Top comments (0)