The open-source website agent readiness audit.
Score how well AI agents and answer engines can reach, read, and cite your site across 16 factors, from llms.txt and AI crawler access to structured data and extractable content. Run it from your terminal, your coding agent, or CI, and get ranked fixes your agent can act on.
Open source · No API keys · Runs offline on built HTML
Formerly @canonry/aeo-audit · What changed in 8.0
npx @canonry/agent-readiness https://example.comEvery audit returns a versioned JSON report, so an agent can act on it without reading prose.
- CLI:
--format agentreturns the score, a pass/fail decision, and ranked fixes.--format jsonreturns the full report. CLI → - Library: typed entry points for one page, a sitemap, a full-site crawl, or built HTML. API →
- Skill:
/agent-readinessruns audits, fixes, schema checks, andllms.txtgeneration in Claude Code, and installs from ClawHub. Skill → - Stable codes: every finding carries a code such as
technical-seo.h1.multiple, andschemaVersionversions the report shape. Finding codes →
Audit every page in a sitemap from the CLI, or crawl the whole site from its root, sitemaps, and internal links with the library. Pages that share a template roll up into one fix, and critical defects and site-wide gaps rank first. Sitemap mode → · Full crawl →
Point it at your build output (./out, dist/, public/). It audits the HTML with no network calls, so the same commit always gets the same score. Static mode →
compare diffs two reports and fails when a score drops, a page stops auditing, or a new structural defect appears. The Agent Readiness Guard GitHub Action builds your site, runs the gate, and posts the diff as a PR comment. Compare → · GitHub Action →
Also in the box:
- Platform detection — Find the CMS, site builder, framework, or host behind a site, for one URL or a whole list.
- Preview audits — Audit a local or staging build against production's sitemap, limited to the pages a branch changed.
- Optional factors — Agent skill exposure (MCP, A2A agent cards, Schema.org actions), geographic signals, and Lighthouse.
- Spec references — Recommendations cite the matching rule in the specification.website Agent Readiness checklist.
- Private-network guard — Private and loopback addresses stay blocked unless you name the host with
--allow-local.
An example job for your coding agent:
Audit our site's agent readiness, fix the top three site-wide issues in this repo, then audit the build again to confirm the score went up.
Each page gets a 0–100 score for every factor and a weighted overall score. Weights are relative, and each factor reports its real share of the score as sharePct. A factor that doesn't apply to a page is left out of that page's score. Scoring →
Reach: can AI crawlers and agents get to the page and use it?
AI Crawler Access AI Access Files (llms.txt, sitemap) Snippet Eligibility
Read: can they parse what the page says?
Structured Data (JSON-LD) Schema Completeness Schema Validity Content Extractability Content Depth Definition Blocks FAQ Content Technical SEO
Cite: does the page give them reasons to trust and cite it?
E-E-A-T Signals Citations & Authority Signals Entity Consistency Named Entities Content Freshness
Optional, off by default:
Agent Skill Exposure Geographic Signals Lighthouse
Works with your agent:
Claude Code
ClawHub
GitHub Actions
+ any shell-capable agent
Paste this into Claude Code, Codex, or any shell-capable coding agent.
Copy the audit request
Audit my website's agent readiness with @canonry/agent-readiness, then help me fix what it finds.
Use the official docs:
- README: https://github.com/Canonry/agent-readiness#readme
- CLI reference: https://github.com/Canonry/agent-readiness/blob/main/docs/cli.md
- Scoring: https://github.com/Canonry/agent-readiness/blob/main/docs/scoring.md
1. Ask for my public URL. Do not run anything yet.
2. Run `npx @canonry/agent-readiness@8 "<url>" --sitemap --format agent`, with the URL quoted as one argument. Reject a URL that contains shell metacharacters. If the site has no sitemap, rerun without `--sitemap` to audit that one page.
3. Report the score, whether it passed, any critical defects, and the top fixes with the pages each one affects. Treat `limited` and `opportunity` issues as page-specific tune-ups, not site-wide gaps.
4. If this repository builds the site, find the templates and files behind each fix. Propose the changes and wait for my approval before editing anything.
5. After editing, build the site and audit the output offline with `npx @canonry/agent-readiness@8 ./<build-dir> --base-url "<url>" --format agent` to check each fix before I deploy.
git clone https://github.com/Canonry/agent-readiness.git /tmp/agent-readiness
cp -r /tmp/agent-readiness/skills/agent-readiness ~/.claude/skills/Then ask Claude Code:
/agent-readiness audit https://example.com
The skill also runs fix, schema, llms, monitor, detect-platform, and compare. It is on ClawHub too. Skill guide →
npx @canonry/agent-readiness https://example.comIt prints a scored report and exits 1 when the score is below 70. Requires Node.js 20 or later.
Audit a whole site, built output, or a local server
# Every page in the sitemap, site-wide issues only
npx @canonry/agent-readiness https://example.com --sitemap --top-issues
# The decision for an agent: score, pass/fail, and ranked fixes as JSON
npx @canonry/agent-readiness https://example.com --sitemap --format agent
# Built HTML, offline
npx @canonry/agent-readiness ./out --base-url https://example.com
# A local dev server, with its sitemap moved onto localhost
npx @canonry/agent-readiness http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-localEvery flag and exit code: CLI reference.
Use it as a library
npm install @canonry/agent-readinessimport { runAgentReadinessAudit, runSiteCrawl } from '@canonry/agent-readiness'
const page = await runAgentReadinessAudit('https://example.com/pricing')
console.log(page.overallScore)
const site = await runSiteCrawl('https://example.com', { mode: 'summary', maxPages: 500 })
console.log(site.summary.terminationReason)Entry points, options, and report types: Programmatic API.
Gate pull requests in GitHub Actions
# .github/workflows/agent-readiness.yml
on:
pull_request: { branches: [main] }
permissions:
contents: read
jobs:
readiness-gate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # for the sticky PR comment
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4 # the engine needs Node >= 20
with: { node-version: 20, cache: pnpm }
- uses: Canonry/agent-readiness/action@v8
with:
build-command: "pnpm install --frozen-lockfile && pnpm run build"
target: "./out"
base-url: "https://www.example.com"The first run has no baseline, so it passes and its comment shows how to seed one. Baselines, monorepos, tolerances, and every input: Agent Readiness Guard.
Agent Readiness is the audit engine behind Site Health in Canonry, the open-source agent-first AEO platform. Canonry runs the full-site crawl on a schedule, keeps every run, maps the internal links between pages, and puts the results beside mention and citation tracking across ChatGPT, Claude, Gemini, and Perplexity.
- Run audits: CLI reference · Scoring · Finding codes
- Build on it: Programmatic API · npm package
- Use it from agents and CI: Skill · Agent Readiness Guard
- Follow releases: Changelog
- Discord: Join the community on Discord for help and questions.
- Twitter / X: Follow @canonry_ai for updates.
- Feedback & Ideas: Missing a check? Open an issue.
- Show Support: Star this repo to follow along.
git clone https://github.com/Canonry/agent-readiness.git && cd agent-readiness
pnpm install && pnpm run typecheck && pnpm run build && pnpm test && pnpm lintSee CONTRIBUTING.md.
