# a14y **Agent readability for the web.** Agents (ChatGPT, Claude, Copilot, Cursor) now read most of the web before humans do. `a14y` (shorthand for *agentreadability*) is an open spec for making any website discoverable, parseable, and comprehensible to those agents, a versioned scorecard that operationalizes the spec, and a CLI plus Chrome extension that score any site against it. Documentation sites are a common high-value target, but the scorecard works for marketing sites, product pages, help centers, and anything else agents might read. > 📖 **Full documentation & source:** > 🌐 **Docs site:** ## Install ```bash # Recommended: install a14y globally and set up the agent skill in one step npx a14y install # One-shot audit, no install npx a14y https://example.com # Install globally by hand npm install -g a14y a14y https://example.com ``` `npx a14y install` runs `npm install -g a14y` and then `a14y skill install`, so the CLI lands on your `PATH` and your coding agents pick up the a14y skill. The CLI also ships under two alias names for discoverability: `agentready` and `agentreadability`. All three run the same binary. ## Usage ```bash a14y # audit a single page a14y --mode site # crawl the whole site a14y --output json # machine-readable scorecard a14y --output agent-prompt # Markdown fix-list for a coding agent a14y scorecards # list available scorecard versions ``` `check` is the default command: `a14y ` is exactly the same as `a14y check `. For full flag documentation run `a14y --help` (summary) or `a14y help check` (detail). ## Use from a coding agent a14y ships an [agent skill](https://agentskills.io/specification) that any spec-compliant coding agent (Claude Code, Codex, Cursor, OpenCode, and 50+ others) can install with one command: ```bash npx skills add timothyjordan/a14y ``` The a14y CLI can also install, update, and uninstall the skill itself, which is handy if you already have a14y on your `PATH`. It is idempotent (installs if missing, updates if present), auto-detects which coding agents you have configured, and shows a checklist before writing: ```bash npx -y a14y skill # install/update for detected agents (~/.claude/skills, ...) npx -y a14y skill --link # one shared copy in .agents/skills, symlinked from each agent npx -y a14y skill --project # guided install into the current project, so collaborators share it npx -y a14y skill --check # report whether your copy is out of date npx -y a14y skill uninstall # remove it from every agent and the shared dir ``` Run `a14y skill --project` from inside a repository to commit the skill alongside your code, so everyone working in that repo gets it. The skill detects a running local dev server (or falls back to your live URL), runs the audit, proposes a prioritized fix plan, and tracks score deltas across runs in `AGENTS.md`. Source: [`skills/a14y/SKILL.md`](./skills/a14y/SKILL.md). The live site at also advertises this skill via `` and `/.well-known/agent-skills/index.json` per the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc), so agents that respect those signals can pick it up automatically. ## Command reference The sections below are generated from the CLI's own `--help` output, so they stay in sync with the code. ### `a14y --help` ```text Usage: a14y [options] [command] Agent readability scorer — audits any website against the versioned a14y scorecard Options: -V, --version output the version number --no-telemetry disable anonymous usage telemetry for this run -h, --help display help for command Commands: check [options] Audit a URL or whole site against the a14y scorecard scorecards [options] List every shipped scorecard version and the checks each one pins skill [options] [action] Install, update, or uninstall the a14y agent skill for your coding agents (idempotent) install [options] Install a14y globally (npm i -g a14y), then install the agent skill help [command] display help for command Commands in detail: check Audit a URL or a whole site -m, --mode page|site default: page -s, --scorecard scorecard version, or "draft" for the in-progress one. Repeat to score the same scan against multiple scorecards in one invocation, e.g. -s 0.2.0 -s draft --max-pages default: 500 --concurrency default: 8 --page-check-concurrency default: 4 --polite-delay default: 250 -o, --output text | json | agent-prompt (multi-scorecard runs require text or json) --fail-under exit 1 if first scorecard's final score < threshold --no-share omit the shareable score block (single scorecard only) -v, --verbose stream progress events to stderr scorecards List shipped scorecard versions -o, --output text | json install Install a14y globally, then install the agent skill (accepts the same flags as 'skill' below — e.g. --project, --link, -y) skill [install|update|uninstall] Manage the a14y agent skill (idempotent; default: install) --global act on the home dir (default) --local act on the current project instead --project guided project install (for collaborators) --link symlink mode: shared copy in .agents/skills --copy copy mode: a SKILL.md per agent (default) --target write to /a14y/SKILL.md, skip auto-detect --agent restrict to one agent (repeatable) --check, --dry-run report drift without writing (exit 1 on drift) --force overwrite a user-modified target or symlink -y, --yes act on all detected agents (no checklist) -o, --output text | json Run 'a14y help ' (or 'a14y --help') for full details. Tip: 'check' is the default — 'a14y ' works the same as 'a14y check '. ``` ### `a14y help check` ```text Usage: a14y check [options] Audit a URL or whole site against the a14y scorecard Options: -m, --mode page or site (default: "page") -s, --scorecard scorecard version to evaluate against, or "draft" for the in-progress scorecard. Repeat the flag to score the same scan against multiple scorecards in one invocation. Defaults to "0.2.0". --max-pages maximum pages to crawl in site mode (default: 500) --concurrency parallel fetches during crawling (default: 8) --page-check-concurrency parallel page-check evaluations (lower bounds peak memory on huge sites) (default: 4) --polite-delay minimum delay between request starts (default: 250) -o, --output text, json, or agent-prompt (default: "text") --fail-under exit 1 if the final score is below this threshold --no-share omit the shareable score block from text output -v, --verbose stream progress events to stderr -h, --help display help for command ``` ### `a14y help scorecards` ```text Usage: a14y scorecards [options] List every shipped scorecard version and the checks each one pins Options: -o, --output text or json (default: "text") -h, --help display help for command ``` ## Repository layout This repo is an npm workspace: - `packages/apps/cli` — the `a14y` binary (this CLI). - `packages/core` — `@a14y/core`, the library that implements scoring, crawling, and report generation. Consumed by the CLI and by the Chrome extension. - `packages/apps/extension` — Chrome extension. Released as a `.zip` attached to each `extension-v` GitHub Release (not on npm); see [RELEASING.md](./RELEASING.md). - `packages/apps/docs` — Astro site published at . - `packages/aliases/*` — thin wrapper packages that re-export the CLI under `agentready` and `agentreadability`. ## Contributing ```bash npm install npm run build npm test npm run docs # regenerate every README from docs/ ``` All user-facing READMEs in this repo (this one, `packages/apps/cli/README.md`, `packages/core/README.md`, and the alias READMEs) are generated from `docs/templates/` + `docs/fragments/`. Edit the source files and run `npm run docs` — never hand-edit a generated README. For contribution conventions (branching, tests, PR flow) see [CONTRIBUTING.md](./CONTRIBUTING.md). For the release flow (npm packages, Chrome extension, docs site) see [RELEASING.md](./RELEASING.md). For the people behind a14y see [CONTRIBUTORS.md](./CONTRIBUTORS.md). ## Origins & Attribution The `a14y` project is the independent implementation of the **Agent Readability Specification** created at Vercel and released here: * [The Agent Readability Spec](https://vercel.com/kb/guide/agent-readability-spec) * [Making Documentation Readable by AI Agents](https://vercel.com/kb/guide/make-your-documentation-readable-by-ai-agents) We are grateful to the Vercel team for sharing this knowledge and for their commitment to an open, agent-readable web. ## License Apache-2.0 © Timothy Jordan