seo-agentic

Files (8)

• LICENSE.txt
• SKILL.md
• access-policy.md · references/
• agent-friendly-pages.md · references/
• discovery-and-markdown.md · references/
• lighthouse-agentic-category.md · references/
• vendor-matrix.md · references/
• webmcp.md · references/

SKILL.md (first lines)

# Agentic Browsing Readiness

Makes a site usable by AI agents that browse, fill forms and act for people
(ChatGPT's browser, Gemini in Chrome, Claude in Chrome, Comet, Edge), and
explains Google's Lighthouse **Agentic Browsing** result.

**The framing that survives every standards outcome:** agent readiness is
accessibility plus performance plus access policy, with a Markdown and
discovery layer on top. WebMCP is an optional enhancement for sites with forms
or transactions, not a foundation (WebKit opposes it, Mozilla is neutral, and
only ChatGPT desktop calls tools by default).

## Commands

| Command | What it does |
|---|---|
| `/seo agentic <url>` | Full agent-readiness audit (default mode) |
| `/seo agentic lighthouse <url or file.json>` | Explain the Lighthouse Agentic Browsing X/N result |
| `/seo agentic fix <url>` | Draft fixes: robots.txt Content-Signal, llms.txt, ai-catalog.json, WebMCP |
| `/seo agentic refresh` | Re-verify the dated facts in `references/vendor-matrix.md` |

## Audit process

Run the steps in this order and keep every tool's JSON for the report.

1. **Lighthouse fraction.**
   `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run lighthouse_agentic.py <url> --strategy both --json`.
   Uses PSI v5 (`category=AGENTIC_BROWSING`); a Google API key avoids the
   shared anonymous quota. With a saved report use `--from-json <file>`.
   Report the fraction as `X/N` exactly as computed. Never convert it to a
   percentage and never assume N: it is at most 6, and N/A and informative
   audits drop out. Read `references/lighthouse-agentic-category.md` before explaining it.
2. **HTTP and markup checks.**
   `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agentic_check.py <url> --json`.
   Covers server-rendered content, robots.txt groups per AI agent and
   Content-Signal, llms.txt, Markdown delivery, ai-catalog.json, `/.well-known`
   documents, and WebMCP markup.
3. **Accessibility tree.**
   `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agent_ux_check.py <url> --json`.
   A local 0-100 heuristic; present it separately from the Lighthouse fraction.
   Page-level criteria: `references/agent-friendly-pages.md`.
4. **WAF behaviour (only with authorization).** Add `--ua-matrix` to step 2
   only when the user controls the site or confirms they are authorized to
   test it: it sends requests carrying AI agents' user-agent tokens. Treat the
   result as behaviour toward **unverified** traffic, never as proof that the
   real agent is blocked. Access rules: `references/access-policy.md`.
5. **Commerce (e-commerce sites only).** Flag UCP presence from step 2
   (`well-known:ucp`) and
   hand depth to `seo-ecommerce` (`ucp_check.py`).
6. **Optional cross-check.** If the user wants a second opinion, isitagentready.com
   (Cloudflare) runs a similar scan. Treat third-party scanners as one
   operator's method, not a conformance test.

## Priorities

| Priority | Item | Tool check id |
|---|---|---|
| **P0** | Accessible names, valid roles, nothing interactive hidden from the tree | Lighthouse `agent-accessibility-tree`, `agent_ux_check.py` |
| **P0** | CLS at or under 0.1 | Lighthouse `cumulative-layout-shift` |
| **P0** | Primary content present without JavaScript | `server-rendered` |
| **P0** | robots.txt reachable, with deliberate groups per AI purpose | `robots-reachable`, `robots-ai-groups` |
| **P0** | WAF lets verified bots and signed agents through; no CAPTCHA on content | `waf-ua-matrix` plus WAF logs |
| P1 | Private paths protected by authentication, not robots.txt (user-triggered agents may ignore it) | `robots-user-agents` |
| P1 | Content-Signal inside every relevant group (absence is info, a gap is warn) | `content-signal` |
| P1 | llms.txt passing the Lighthouse rules (absence is info) | `llms-txt` |
| P1 | Markdown via `.md` URLs or `Accept: text/markdown` with `Vary: Accept` | `markdown-delivery` |
| P1 | Stable, visible confirmation states; no hover-only menus or focus traps | manual review (no script evidence; say so if not checked) |
| P1 (transactional) / P2 | Imperative WebMCP tools bound to existing handlers | `webmcp-tools`, Lighthouse `webmcp-registered-tools` |
| P1 if tools exist | Tool safety: annotations, confirmation, logging, and no tool description that tells agents to skip confirmation | review the tool list and descriptions from Lighthouse `webmcp-registered-tools` (it sees tools registered by third-party scripts that the page source does not show) against `references/webmcp.md` |
| P2 | WebMCP registered on `document.modelContext`, not only the legacy `navigator` entry point | `webmcp-entry-point` |
| P2 | API Catalog, OAuth metadata (only if you run APIs) | `well-known:api-catalog`, `well-known:oauth-*` |
| P3 | A2A agent card, UCP profile (only if you run them) | `well-known:agent-card.json`, `well-known:ucp` |
| P3 | Declarative WebMCP form attributes (Chrome only) | `webmcp-form-annotations` (static); Lighthouse `webmcp-form-coverage` |
| P3 (P1 when a catalog URL fails, including a catch-all 200 at the well-known path) | ai-catalog.json (only if you have agent resources) | `ard-catalog` |
| P1 | Unknown URLs return a real 404 (a catch-all 200 fails llms-txt and ard-schema in Lighthouse) | `http-404` |

Fix in order P0, then P1. Do not recommend lower priorities while a measured P0
fails. A P0 you could not test (for example the WAF check on a third-party site)
is reported as "not tested" and does not block the rest; the Lighthouse "paths"
are listed as options either way.

## Report structure

1. **Summary**: Lighthouse `X/N` (mobile and desktop), the Agent-UX heuristic,
   and the count of P0 failures. One sentence on what most limits agents today.
2. **Lighthouse Agentic Browsing**: each audit's status (pass, fail,
   informative, N/A) and the "paths" from `lighthouse_agentic.py` that add a
   counted audit, stated as options, not goals.
3. **Findings by priority** with evidence (status codes, headers, rule ids,
   selectors) and the fix.
4. **Access policy**: one line each for training, search and user-triggered
   agents. Never merge them.
5. **Standards status**: every WebMCP, Content-Signal, ARD, MCP Server Card and
   Web Bot Auth item labelled draft or proposal, with the date checked.
6. **Recommendations**, each carrying the evidence it rests on, what it
   unblocks, and how to confirm it worked (rerun the named check).

## Fix mode

Drafts go to stdout for review; nothing is deployed and no file is overwritten.

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agentic_fix.py robots <url> --signal "search=yes, ai-input=yes, ai-train=no"
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agentic_fix.py llms <url>
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agentic_fix.py ai-catalog --publisher example.com --entry "Name|media type|url"
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run agentic_fix.py webmcp <url> --json
```

- `robots` adds Content-Signal to each group and never changes Allow or
  Disallow. Ask the user for their training policy before choosing
  `ai-train=yes` or `no`; do not decide it for them.
- `webmcp` drafts one tool per real form, submitting through the form so the
  UI's own handler runs. Mark sends, purchases and deletes consequential and
  keep a human confirmation step. Read `references/webmcp.md` first.
- Markdown negotiation for nginx, with a tested config, is in
  `references/discovery-and-markdown.md`.

## Honest-reporting rules

From AgriciDaniel/claude-seo, MIT.

More from AgriciDaniel/claude-seo