Never interpolate user input directly into shell commands. Always:
Validate that the target is either a URL matching https:// / http:// or a local filesystem path (static-output mode), and that it contains no shell metacharacters.
Quote every argument individually (e.g., npx @canonry/agent-readiness@8 "https://example.com" --format json).
Pass flags as separate, literal tokens — never construct command strings from raw user text.
Reject arguments containing characters like ;, |, &, $, `, (, ), {, }, <, >, or newlines.
Pass --entities only the file you wrote, entities.json, never a path taken from user text.
Modes
audit: score and diagnose a site
fix: apply code changes after an audit
schema: validate JSON-LD and entity consistency
llms: create or improve llms.txt and llms-full.txt
monitor: compare changes over time, compare a branch preview against production, or benchmark competitors
detect-platform: identify the CMS, site builder, framework, or hosting stack a site uses
compare: diff two saved --format json reports into a regression verdict + exit code (CI gate)
If no mode is provided, default to audit.
Examples
audit https://example.com
audit https://example.com --sitemap
audit https://example.com --sitemap --limit 10
audit https://example.com --sitemap --top-issues
audit https://example.com --sitemap --format agent (slim decision for agents)
Metadata such as fetch time and auxiliary file availability
--require-meta (CI gate)
Pass --require-meta (single or sitemap mode) to force exit 1 whenever any audited page is missing <meta name="description">, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.
--entities (pages that name another property or location)
Use when the site has one page per property, location or brand and the user asks whether pages mention the wrong one, or audits such a portfolio. Copied FAQ answers and titles often keep another property's name.
Read entities.example.json in this skill's folder: a property portfolio with aliases, a property with a site of its own, and a competitor with no pages. Build the same structure from what the user gives you (each entity's names and the URL path of its pages) and write it with Write(entities.json). Names need two real words ("Northwind Harbor", not "Harbor"). Leave urlMatchers out for an entity with no pages on the site.
In static-output mode also pass --base-url with the site's origin.
Report each names-another-entity page from criticalDefects: the entity it belongs to (in detail) and, from evidence, the FAQ question or field, the entity it names and the snippet. The fix is the page's own entity's details in place of the other name.
An invalid entities.json exits 1 with an error naming the field to correct. The check never changes scores or the exit code.
Sitemap Mode
Read siteIssues as well as the score-ranked fixes. Duplicate titles and descriptions carry stable codes and affected URLs, including when the overall score passes. Review shared templates and canonical relationships before editing. A title shorter than 15 characters is an advisory check, not a mandatory rewrite. On partial audits, the reported groups cover only observed pages.
Use --sitemap to audit all pages discovered from the site's sitemap:
--sitemap [url] — auto-discover the sitemap (tries /sitemap.xml, then /sitemap-index.xml, then Sitemap: directives in /robots.txt) or provide an explicit URL
--limit <n> — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; <priority> orders instances within a template)
--top-issues — skip per-page output, show cross-cutting patterns, cross-page metadata issues and critical defects
--rewrite-sitemap-origin — rewrite every <loc>'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.
--changed — filter sitemap URLs to static routes changed since --base; use for PR work
--base <ref> — git base for --changed (default main)
--include-critical — add critical paths to the changed-page set
--critical-paths <list> — comma-separated critical paths for --include-critical; defaults to /
--require-meta — force exit 1 if any audited page is missing <meta name="description">, regardless of overall score (useful as a CI gate)
--include-geo / --include-agent-skills — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). --lighthouse is not available with --sitemap.
Pages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.
Returns:
Per-page scores
Critical defects — binary, one-line-fix structural defects (an <h1> count other than one, a missing <title>, a missing meta description, and with --entities a page that names another entity) surfaced regardless of how few pages they affect, with the offending pages named (homepage and high sitemap-priority pages first). These would otherwise be averaged into a passing factor score; the JSON field is criticalDefects and critical-severity ones are also promoted to the top of prioritizedFixes. Shown even with --top-issues.
Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (bestScore/bestPageUrl) and a status: sitewide (a real coverage gap) vs. limited/opportunity for page-specific factors (FAQ, definitions) that legitimately apply to only some page types
Aggregate score
Prioritized fixes (critical defects first, then site-wide gaps; page-specific limited/opportunity factors demoted below them, scoped to the page(s) that carry them), each costed as templateCount templates over instanceCount pages
Templates — pages that share a URL shape and score alike, collapsed into the template that produced them, with the page to fix on. "194 property pages missing schema" is one template edit, not 194
Coverage — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a confidence of full / representative / indicative. A sample that missed whole templates is labelled indicative and does not speak for the sections it never saw
Preview / PR Audit Workflow
Use this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.
For a local preview server whose sitemap emits production canonicals:
Use --allow-local only when the user explicitly wants to audit localhost/private IPs.
Use --rewrite-sitemap-origin when a local or staging sitemap emits production canonicals.
Use --changed --base <ref> for PR work so unrelated site sections do not dominate the result.
Use --include-critical --critical-paths /,/pricing,/contact when important pages should always be checked.
If --changed finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with --critical-paths or audit explicit URLs separately.
Prefer --format agent for agent action, --format json for saved compare baselines, and --format markdown for human summaries.
For branch-vs-production regression review, produce comparable reports first, then run compare:
Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out
Machine-readable output (for agents)
Use --format json for the full report, or --format agent for just the decision: { schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }, where issues is the ranked prioritizedFixes and the per-factor/per-page detail is omitted. Prefer --format agent when you only need to decide and act. Key fields for acting on the result without parsing prose:
schemaVersion (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.
prioritizedFixes is a ranked array of objects, each with a stable id, kind, optional severity, the complete affectedPages list (never truncated), affectsHomepage, prevalencePct, and a human summary. Cross-cutting fixes also carry avgScore, bestScore/bestPageUrl, and a status (sitewide | limited | opportunity) — treat limited/opportunity as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.
Stable identifiers everywhere — criticalDefects[].id, prioritizedFixes[].id, and every factor finding's code (e.g. technical-seo.h1.multiple) — let integrations key on codes rather than message strings.
Auxiliary File Diagnostics
When the audit fetches /llms.txt, /llms-full.txt, /robots.txt, and /sitemap.xml, it probes once with Accept: text/markdown to detect a content-negotiation trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect .txt → non-existent .md for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the AI Access Files (llms.txt, sitemap) factor.
Local Dev / Staging Targets
By default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit their own dev or staging server, pass --allow-local (alias --allow-private):
Pass the explicit http:// scheme for local dev servers — a bare host defaults to https://.
The relaxation is scoped to the single host named on the CLI, evaluated per hop. A redirect or sitemap <loc> pointing at any other private host (e.g. 169.254.169.254) stays blocked.
To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:
When the user wants to audit built HTML offline (CI on a next export / dist / out directory, or before deploying), pass a filesystem path instead of a URL:
bash
# A directory of built HTML (aggregated like sitemap mode)
npx @canonry/agent-readiness@8 "./out" --base-url https://example.com --format json
# A single built file
npx @canonry/agent-readiness@8 "./dist/index.html" --format json
# Gate CI on missing meta descriptions across the build
npx @canonry/agent-readiness@8 "./out" --require-meta --format json
A .html/.htm file → single-page report; a directory → aggregated report (--limit, --top-issues, --factors, --include-geo, --include-agent-skills, --require-meta apply).
--base-url <url> maps files to page URLs (out/about/index.html → <base>/about/; default https://localhost). index.html collapses to its directory URL; other files drop the .html extension.
llms.txt, llms-full.txt, robots.txt, and sitemap.xml are read from the directory root when present.
Partial coverage: server-only signals (redirects, X-Robots-Tag, Last-Modified, Link headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.
Compare / Regression Mode
When the user wants to fail CI on a readiness regression (a PR dropped the score, broke a page, or introduced a structural defect), use the compare subcommand. It diffs two saved --format json reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.
bash
# 1. Produce the current report (any mode's --format json output works)
npx @canonry/agent-readiness@8 "./out" --base-url https://example.com --format json > current.json
# 2. Diff against a stored baseline — exit 1 if it regressed
npx @canonry/agent-readiness@8 compare --baseline baseline.json --current current.json
# Write a Markdown summary (for a PR comment) and tighten the overall gate
npx @canonry/agent-readiness@8 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md
# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ
npx @canonry/agent-readiness@8 compare --baseline baseline.json --current current.json --strict-comparability
A regression is any of: overall/aggregate drop > --overall-tolerance (default 2); a single page drop > --page-tolerance (default 5); a single factor drop > --factor-tolerance (default 8); a page that was auditing successfully now erroring; a new severity:critical defect (--fail-on-new-critical, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are comparable (same factor set, no major engine change) — otherwise they're warnings, not failures.
missing-meta-description is severity:warning, so it does not trip --fail-on-new-critical; use --require-meta on the audit or --fail-on warnings here. Removed pages and new warnings are report-only unless promoted with --fail-on removed-pages,warnings.
Exit codes:0 = no regression / improvement / first run (no baseline); 1 = regression; 2 = misconfiguration (mode mismatch, unreadable report, missing --current, or incomparable factor-set/engine under --strict-comparability). --report-only always exits 0 (soak mode).
Both reports must be the same mode (two single, or two multi-page). stdout carries only the CompareReport JSON (or Markdown with --format markdown); diagnostics go to stderr.
Lighthouse Mode
Use --lighthouse when the user wants page speed, accessibility, or best-practices scoring alongside the readiness factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).
On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a timeout or unreachable finding rather than throwing — the rest of the audit still runs.
Detect Platform Mode
Use --detect-platform when the user wants to know what stack a site is built on (e.g., "is this WordPress?", "what framework does competitor X use?", "is this site custom-built?"). This is much faster than a full audit because it skips analyzer scoring.
--detect-platform — switch to detection mode instead of auditing
--min-confidence <lvl> — filter to low (default), medium, or high confidence
--urls <src> — run on multiple URLs at once (file path, comma-separated list, or - for stdin)
--concurrency <n> — max in-flight fetches in batch mode (default 5)
The report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's isCustom flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is 0 when at least one platform is detected, 1 otherwise.
Batch detection
When the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass --urls:
The batch report contains a results array; each entry has status: 'success' or 'error', plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is 0 when at least one URL succeeded, 1 otherwise.
Fix
Use when the user wants code changes applied after the audit.
agent-readiness signals: per-page Markdown source endpoints, robots.txtContent-Signal directives (the audit scores the values — set ai-input=yes/search=yes to permit AI answers and search indexing; ai-input=no opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)
Re-run the audit and report the score delta.
Rules:
Always explain proposed changes and get user confirmation before editing files.
Do not remove existing schema or content unless the user asks.
Preserve existing code style and patterns.
If a fix is ambiguous or high-risk, explain the tradeoff before editing.
Schema
Use when the request is specifically about JSON-LD or schema quality.
Validity issues like duplicate singleton @types and JSON parse errors are per page, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests ("audit my schema", "are my FAQ blocks valid?"); use single-URL mode only when the user names one specific page.
