Agent web audit

Agent web audit

This skill audits a web project for how well AI agents and LLMs can read, navigate, and act on it, then applies the fixes. It covers three overlapping concerns that share one root cause:

1. Agent readiness: can an autonomous agent perceive and operate the interface (screenshots, DOM, accessibility tree).
2. Accessibility: the same signals a screen reader needs. Agent-readiness is accessibility restated for a new visitor class, so fixing one fixes both.
3. AI-search legibility: can crawlers reach the content and is it worth citing (GEO/AEO).

The standard this is built on is Google's web.dev "Build agent-friendly websites" guidance (April 2026), the Lighthouse 13.3 "Agentic Browsing" audit (May 2026), and Google's Search Central generative-AI optimization guide (May 2026). The whole point: there is no separate AI layer. Clean, semantic, accessible, crawlable HTML is the entire game.

What this skill does

Given a web project (whole repo by default, or a folder/file if the user points at one):

1. Size up: detect the stack (plain HTML, React, Next.js, Vue, server templates) and whether Tailwind is in use, since one of the highest-hit issues is Tailwind-version-specific.
2. Scan: run scripts/scan.sh to grep for the common machine-readability problems across the whole project.
3. Deep read: open the files the scan flags and confirm each finding against references/agent-rules.md.
4. Report: write a findings report grouped by impact, with file:line references and a concrete fix for each.
5. Fix: apply the mechanical, low-risk fixes directly (with the user's go-ahead), and flag the judgment calls for manual review.

The aim is the same as any good audit: a short list of real problems that get fixed, not a wall of nits.

Workflow

1. Size up the project

First action: understand what you are auditing.

ls <repo>
# stack + tailwind signals
grep -rl -E "tailwindcss" <repo>/package.json <repo>/*.config.* 2>/dev/null
cat <repo>/package.json 2>/dev/null | grep -E "\"(react|next|vue|nuxt|svelte|@angular|tailwindcss)\""
find <repo> -maxdepth 3 -type f \( -name "*.html" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \) \
  -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/build/*" | wc -l

Note the stack and whether it is plain markup, a JS framework, or server-rendered templates. This changes how selectors look (for vs htmlFor, class vs className) and which fixes apply. If Tailwind v4 is present, the cursor:pointer base rule is almost always missing, so check that first (see references/agent-rules.md, rule 5).

If the user pointed at a specific folder or file, scope everything below to that.

2. Load the rules

Read references/agent-rules.md before hunting. It has the seven agent-friendliness rules, the accessibility-tree explanation, and the exact fix for each, including code. Read references/ai-search.md if the user cares about being crawled and cited by AI search (most do), not only about on-page agent actions.

3. Scan

Run the scan script across the project. It is grep-based, needs no browser, and surfaces the hotspots fast:

bash scripts/scan.sh <repo>

It flags: non-semantic interactive elements (div/span with click handlers but no role), missing or unlinked labels, images without alt text, hover-only reveal patterns, missing cursor:pointer signals, the Tailwind v4 button regression, layout-shift risks, and whether robots.txt / llms.txt / sitemap exist and whether AI crawlers are blocked. Read the output and let it drive step 4. Every hit is a candidate, so open those files.

4. Deep read and confirm

Open the flagged files and confirm each candidate is real. For interactive elements, the question is: does this element expose a role and name to the accessibility tree, or is it an invisible-to-agents div. For a quick manual check on a running page, the accessibility tree is viewable in Chrome DevTools under the Accessibility tab; note this to the user if they can run the site.

Before writing up a finding, ask:

• Is this actually reachable and used, or dead markup.
• Can I point to a file and line.
• Do I have the concrete fix from references/agent-rules.md.

5. Report

Save the report to agent-readiness-report.md in the working directory (or /mnt/user-data/outputs/ if it exists) and present it. Use this structure:

# Agent Readiness Report

**Project:** <name>
**Scope:** <full repo | folder>
**Date:** <today>
**Stack:** <e.g. Next.js 15 + Tailwind v4>

## Summary
<2-4 sentences. Overall state, and the single highest-leverage fix.>

**Counts:** High: N | Medium: N | Low: N

## High impact
### H1. <title>
**File:** `path:line`
**Rule:** <which of the seven, or "AI-search">
**Problem:** <what an agent or crawler cannot do because of this>
**Fix:** <concrete, with code>

## Medium impact
<M1, M2, ...>

## Low impact
<L1, L2, ... terse>

## AI-search / crawlability
<robots.txt, sitemap, llms.txt status, content reachability in initial HTML, note the Google position that llms.txt does not affect Google ranking but may help other AI systems>

## What I did not check
<Runtime behavior, real accessibility-tree output, anything needing the site running.>

## Suggested order of fixes
<2-4 bullets, highest leverage first.>

Severity here is about machine impact, not security:

• High: agents cannot complete a core journey, or crawlers cannot reach main content. Non-semantic primary buttons, content only in client-rendered JS with no server HTML, blocking modal/cookie wall with no accessible control, main nav hover-only.
• Medium: degrades agent success or citation odds but has a workaround. Missing labels, missing alt on meaningful images, unstable layout on key pages, tiny hit targets.
• Low: hardening and best practice. Decorative-image alt, minor cursor signals, missing llms.txt for non-Google systems.

If a section has no findings, write "None found." so the reader knows you looked.

6. Fix

After the report, apply fixes in two tiers.

Apply directly (mechanical, low risk), on the user's go-ahead:

• The Tailwind v4 cursor:pointer base rule (three lines, exact snippet in references/agent-rules.md).
• Linking existing labels to inputs with for / htmlFor.
• Swapping styled div/span click handlers to <button> / <a>, or adding role + tabindex where a swap would break styling.
• Adding cursor: pointer to custom interactive elements.
• Creating a starter robots.txt and llms.txt if absent and the user wants them (see references/ai-search.md for templates).

Flag for manual review, do not guess:

• Alt text content. You can add the alt attribute and mark it alt="" for decorative, but real descriptions need human or context input. List each image and propose text, let the user confirm.
• Layout-shift fixes that require reserving space or restructuring components.
• Removing or redesigning cookie walls and modals, since these have legal and product implications.

For each applied fix, make the smallest change that works and keep the visual result identical for humans. Re-run scripts/scan.sh at the end to show the before/after hit count.

Calibration

A typical audit of a real site surfaces 5 to 20 findings, most Medium and Low, with one or two High. Zero High is common and correct for a well-built accessible site. If you are producing 60 findings, you are counting noise (every decorative image is not a High). If you find two things on a site you have not audited before, look harder, especially at the accessibility tree and at whether main content exists in the initial server HTML.

Best findings are specific and fixable. Compare:

Weak: "The buttons are not accessible." Strong: "src/components/Cart.tsx:34 uses <div onClick={checkout} className='btn'> with no role, so it does not appear as an actionable control in the accessibility tree and an agent cannot find the checkout action. Fix: change to <button type='button' onClick={checkout} className='btn'>, or if the div styling must stay, add role='button' tabIndex={0} and an onKeyDown handler for Enter/Space."

Honesty about limits

This is a static audit. It cannot see the real accessibility tree, real layout shift, or how content renders after JavaScript runs. Say so in the report. If a finding depends on runtime behavior, mark it as needing a live check rather than overclaiming. Never invent file paths or line numbers.

On llms.txt specifically, be accurate: Google Search ignores it and it does not affect Google ranking or AI Overviews, but it is a named check in the Lighthouse Agentic Browsing audit and may help other AI systems. Present it as optional low-cost insurance, not a ranking lever.