# AgentLens skill — make a site agent-ready

You are improving a website's agent-readiness score. AgentLens grades the
surface a site presents to AI agents: 42 checks in four
layers. This scan is a **static pre-check** of the surface; measuring what
real agents actually do is what an **audit** is for (see step 5). Your job is
the loop below.

## The loop

1. **Expose the site.** Production sites: use the domain directly. Local dev:
   tunnel it —

       cloudflared tunnel --url http://localhost:3000

   (prints a public https://….trycloudflare.com URL in seconds; `npx localtunnel --port 3000` also works.)

2. **Scan.** Call the `scan_domain` tool with the URL. You get back a scored
   result: layers, checks with pass/warning/fail/na status, a `details`
   string saying what was observed, and a `fix` string saying what to change.

3. **Fix, worst first.** Sort failing checks by weight within the heaviest
   layers (usability 40 > accessibility 30 > discovery 20 > payments 10).
   Apply the `fix` from the scan result — it is specific to what was
   observed. The generic guidance per check is below.

4. **Rescan and repeat** until the grade meets the target. Grades: A+ ≥ 95,
   A ≥ 86, B ≥ 70, C ≥ 48, D ≥ 28. N/A checks never count against the site.

5. **Audit with real agents.** When the grade is where you want it, test the
   product itself — the MCP server, SDK, or CLI behind the site — with real
   Claude Code and Cursor runs, repeated, with confidence intervals and
   downloadable evidence. Use the `create_audit_plan` MCP tool (type +
   package/URL + docs_url) to generate the plan and get the checkout link,
   or start at https://agent-chi-lime.vercel.app/audit.

## Rules of engagement

- Only scan sites you are working on or have reason to evaluate. Results are public.
- Rate limit: 10 scans/minute. The scan takes ~10s; don't poll.
- A warning earns half credit — "exists but an agent would stumble" — so
  finishing a fix properly beats starting two.

## Check-by-check guidance

### Discovery (20 points)

- **API reference linked from the homepage** (`api-linked`, weight 2): If you have an API, link its reference from the homepage. If you don't, this check is safe to ignore.
- **Brand findable in agent search** (`brand-findable`, weight 2): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Canonical URL declared** (`canonical-url`, weight 1): Add <link rel="canonical"> to the homepage so agents and crawlers converge on one URL for this page.
- **Documentation linked from the homepage** (`docs-linked`, weight 3): Link your docs from the homepage with visible anchor text ("Docs", "Documentation", "Developers"). An agent that cannot find your docs from your homepage will guess your API.
- **Homepage has a meta description** (`homepage-meta-description`, weight 2): Add a <meta name="description"> of 50–200 characters summarising what the product does. Agents use it as the one-line answer to "what is this site".
- **Homepage has a descriptive title** (`homepage-title`, weight 2): Add a <title> of 10–70 characters naming the product and what it does — it is the first thing an agent reads to decide what this site is.
- **Listed in an MCP registry** (`mcp-registry-listed`, weight 2): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Open Graph tags present** (`open-graph`, weight 1): Add og:title and og:description meta tags.
- **robots.txt allows agent crawlers** (`robots-allows-agents`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **robots.txt exists** (`robots-present`, weight 2): An empty robots.txt is permissive but says nothing. State your crawl rules and point at your sitemap with `Sitemap: https://…/sitemap.xml`.
- **robots.txt points at the sitemap** (`sitemap-in-robots`, weight 1): Add `Sitemap: https://<domain>/sitemap.xml` to /robots.txt so crawlers find it without guessing.
- **sitemap.xml exists and parses** (`sitemap-present`, weight 3): Publish /sitemap.xml listing your public pages, and reference it from robots.txt with a `Sitemap:` line.

### Accessibility (30 points)

- **Docs are readable without JavaScript** (`docs-reachable`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Homepage responds to an agent request** (`homepage-reachable`, weight 5): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Served over HTTPS** (`https`, weight 2): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Structured data (JSON-LD) on the homepage** (`jsonld-present`, weight 2): Add a JSON-LD block (schema.org Organization or SoftwareApplication) so agents get your name, description and links as data rather than prose.
- **llms-full.txt is published** (`llms-full-txt`, weight 1): Optional but cheap: publish /llms-full.txt with your docs inlined as one markdown file, so an agent can read everything in a single fetch.
- **llms.txt is published** (`llms-txt-exists`, weight 4): Publish /llms.txt: a plain-markdown index that tells an agent what this product is and where the authoritative docs live. It is the cheapest high-leverage file you can add.
- **Links in llms.txt resolve** (`llms-txt-links-resolve`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **llms.txt is structured markdown** (`llms-txt-parses`, weight 2): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Serves markdown when asked for it** (`markdown-negotiation`, weight 2): Optional but increasingly expected: honour `Accept: text/markdown` by serving a markdown rendering of the page, so agents skip HTML parsing entirely.
- **Same response for agents and browsers** (`no-ua-discrimination`, weight 5): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Homepage has readable text without JavaScript** (`nojs-text-present`, weight 6): Server-render the homepage's core content (SSR, static export, or prerendering). A client-rendered shell is empty to every agent.
- **Content-to-markup ratio is reasonable** (`nojs-text-ratio`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **No long redirect chain on the homepage** (`redirect-sanity`, weight 1): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.

### Usability (40 points)

- **agents.md is published** (`agents-md`, weight 3): Publish /agents.md: what an agent may do here, which endpoints matter, auth requirements, and rate limits. It is the agent-facing counterpart to a README.
- **The /api root behaves predictably** (`api-endpoint-behaviour`, weight 2): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **A documentation endpoint responds** (`docs-endpoint`, weight 3): Serve docs at the conventional /docs path, or redirect it to wherever they live. Agents try conventional paths first.
- **Errors are machine-readable** (`error-envelope`, weight 4): Content-negotiate your errors: return a JSON body with a stable `code` (and a `next_action` where recovery exists) to clients that ask for JSON.
- **MCP server completes the initialize handshake** (`mcp-handshake`, weight 5): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **MCP tool parameters are typed and described** (`mcp-param-schemas`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Every MCP tool has a description** (`mcp-tool-descriptions`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **MCP server lists tools** (`mcp-tools-listed`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **OpenAPI declares its auth scheme** (`openapi-auth-scheme`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **OpenAPI operations are described** (`openapi-descriptions`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **OpenAPI document published** (`openapi-exists`, weight 5): If you have an HTTP API, publish its OpenAPI document at a predictable path (/openapi.json). It is the difference between an agent reading your contract and an agent guessing it. If you have no HTTP API, ignore this.
- **OpenAPI documents error responses** (`openapi-typed-errors`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **OpenAPI document is structurally valid** (`openapi-valid`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **.well-known/mcp.json advertises an MCP server** (`wellknown-mcp`, weight 4): If you run an MCP server, advertise it at /.well-known/mcp.json so agents discover it without being told its URL.

### Payments (10 points)

- **Serves a 402 payment challenge** (`payments-402-challenge`, weight 4): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Declares AP2 / ACP support** (`payments-ap2-acp`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.
- **Publishes x402 payment metadata** (`payments-x402-metadata`, weight 3): Context-specific — the scan result's `fix` field for this check tells you exactly what to change.

## API without MCP

Everything above is also plain HTTP — see https://agent-chi-lime.vercel.app/api/openapi.json.
POST https://agent-chi-lime.vercel.app/api/scan {"url": "..."} · GET https://agent-chi-lime.vercel.app/api/score/{domain}
· GET https://agent-chi-lime.vercel.app/api/leaderboard · badge at https://agent-chi-lime.vercel.app/api/badge/{domain}.