Update to 8gnc — Brand Growth Diagnostic

{
  "name": "ai-agent-readiness",
  "description": "Execute the AI Agent-Readiness audit and sprint playbook (PLAY-004). Use when making a site usable by agentic browsers, AI shopping assistants, or chat-led SERPs. Triggers on \"agent readiness,\" \"agentic browser,\" \"selector contract,\" \"structured data parity,\" \"feed completeness,\" \"task URLs,\" \"Playwright testing,\" \"INP,\" \"TBT,\" \"modal friction,\" \"agent readiness score,\" or when a client needs their site to work with AI-powered browsing agents. Includes audit checklists, 15-day sprint plan, selector contract specs, test harnesses, and scoring rubric.",
  "included_files": [],
  "skill_md_contents": "---\nname: ai-agent-readiness\ndescription: Execute the AI Agent-Readiness audit and sprint playbook (PLAY-004). Use when making a site usable by agentic browsers, AI shopping assistants, or chat-led SERPs. Triggers on \"agent readiness,\" \"agentic browser,\" \"selector contract,\" \"structured data parity,\" \"feed completeness,\" \"task URLs,\" \"Playwright testing,\" \"INP,\" \"TBT,\" \"modal friction,\" \"agent readiness score,\" or when a client needs their site to work with AI-powered browsing agents. Includes audit checklists, 15-day sprint plan, selector contract specs, test harnesses, and scoring rubric.\n---\n\n# AI Agent-Readiness (PLAY-004)\n\nMake sites usable by agentic browsers and chat-led SERPs. Browsers with embedded agents now navigate, click, and buy. Your site must be fast, scriptable, and machine-verifiable.\n\n## Thesis\n\nWinning shifts from discovery to action. Sites must be fast, scriptable, and machine-verifiable for agent task completion.\n\n## When NOT to Use\n\n- The site is mostly static and already crawlable with minimal JS. Agents can already read it — the audit will find little to fix.\n- There are no transactional flows for agents to execute. No cart, booking, or forms means selector contracts and task URLs have nothing to point at.\n- Traffic has no agent or AI-referral component yet AND the team can't act on the audit. A readiness report nobody implements is shelf-ware — wait until one of those changes.\n\n## Offer Structure\n\n### Starter Audit (72 hours)\n- Agentability scan (CWV, JS cost, INP/TBT hotspots)\n- DOM accessibility and selector stability review\n- Structured data parity check vs feed\n- Risk register and prioritized backlog\n\n### 15-Day Agent Sprint\n- Implement selector contract, schema, and deep links\n- Kill top JS and modal blockers\n- Ship Playwright tasks and Lighthouse CI\n- Publish \"Agent Readiness Report\" with before/after\n\n### Ongoing (Monthly)\n- RUM (Real User Monitoring — field data from actual visitors, vs. synthetic lab tests) monitoring of LCP/INP/CLS and funnel KPIs\n- Schema/Feed parity watchlist and Merchant Center QA\n- Governance reviews and regression tests\n\n## Audit Checklist (72 Hours)\n\n### Performance & JS Cost\n- INP under threshold sitewide\n- TBT on PDP and cart under 200ms in lab\n- Long tasks identified and split\n- Third parties deferred or removed\n\n### DOM, Accessibility, and Selectors\n- All controls have role + accessible name\n- No randomized IDs or hash-classes on key controls\n- Stable `data-qa` attributes on critical elements\n- Consent and promo modals dismissible via keyboard and labeled buttons\n\n### Structured Data Sanity\n- `WebSite` → `SearchAction` with `EntryPoint.urlTemplate`\n- `Product` with `Offer` or `AggregateOffer`\n- `OfferShippingDetails` with `ShippingDeliveryTime` where relevant\n- Variant modeling verified\n\n### Marketplace Parity\n- Feed vs page vs JSON-LD values match for price, availability, condition\n- Automatic Item Updates policy documented\n- Shipping settings mirrored in both Merchant Center and JSON-LD\n\n### Flow Reliability\n- Steps to checkout minimized\n- Task URLs documented for common intents\n- Prefilled cart links available for top 3 bundles\n\n## Implementation Sprint (15 Days)\n\n**Days 1–3: Instrument and expose** — Ship JSON-LD on PDPs and list pages. Add `WebSite` → `SearchAction`. Add accessible names to top 20 controls. Turn on RUM for CWV + custom funnel events.\n\n**Days 4–7: Kill the blockers** — Split bundles, defer third parties, remove dead widgets. Make consent and promo modals visible and dismissible. Stabilize selectors.\n\n**Days 8–10: Task paths and deep links** — Publish \"task URLs\" to filtered results (in-stock, price caps, sizes). Create prefilled cart links for top configurations. Document in a private Agent Notes page.\n\n**Days 11–15: Trials and proof** — Run 10 Playwright tasks that mimic agents. Record success rate and time-to-cart. Repeat in Atlas and AI-Mode browsers. Publish Agent Readiness Report.\n\n## Selector Contract\n\n- Prefer **role** and **name** selectors first.\n- Provide explicit **data-qa** fallbacks on critical elements.\n- Never randomize IDs/class names on key controls.\n- Version the contract and store in `/docs/selector-contract.json`.\n\n```json\n{\n  \"version\": \"2025.10\",\n  \"flows\": {\n    \"pdp_add_to_cart\": [\n      {\"step\": \"choose_size\", \"pref\": \"role\", \"selector\": \"getByRole('combobox', { name: 'Size' })\"},\n      {\"step\": \"add_to_cart\", \"pref\": \"role\", \"selector\": \"getByRole('button', { name: 'Add to cart' })\"}\n    ],\n    \"checkout_start\": [\n      {\"step\": \"open_cart\", \"pref\": \"role\", \"selector\": \"getByRole('link', { name: 'Cart' })\"},\n      {\"step\": \"begin_checkout\", \"pref\": \"role\", \"selector\": \"getByRole('button', { name: 'Checkout' })\"}\n    ]\n  }\n}\n```\n\n### Playwright Task Example\n\nOne test per critical flow. Use the same role/name selectors the contract specifies — if the test breaks, an agent breaks.\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\ntest('agent path: select variant, add to cart, confirm', async ({ page }) => {\n  await page.goto('https://example.com/products/trailrunner-2');\n\n  // Select a variant the way an agent would — role + accessible name\n  await page.getByRole('combobox', { name: 'Size' }).selectOption('10');\n  await page.getByLabel('Color').selectOption('Slate');\n\n  // Add to cart\n  await page.getByRole('button', { name: 'Add to cart' }).click();\n\n  // Assert a machine-verifiable success signal\n  await expect(page.getByRole('status')).toContainText('Added to cart');\n  await expect(page.getByRole('link', { name: 'Cart' })).toContainText('1');\n});\n```\n\n## Structured Data Templates\n\n### WebSite with SearchAction\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"WebSite\",\n  \"url\": \"https://example.com\",\n  \"potentialAction\": {\n    \"@type\": \"SearchAction\",\n    \"target\": {\n      \"@type\": \"EntryPoint\",\n      \"urlTemplate\": \"https://example.com/search?q={search_term_string}\"\n    },\n    \"query-input\": \"required name=search_term_string\"\n  }\n}\n```\n\n### Product with Offer and Delivery Windows\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Product\",\n  \"sku\": \"TR-200\",\n  \"name\": \"TrailRunner 2.0\",\n  \"offers\": {\n    \"@type\": \"Offer\",\n    \"price\": \"129.99\",\n    \"priceCurrency\": \"USD\",\n    \"availability\": \"https://schema.org/InStock\",\n    \"shippingDetails\": {\n      \"@type\": \"OfferShippingDetails\",\n      \"deliveryTime\": {\n        \"@type\": \"ShippingDeliveryTime\",\n        \"handlingTime\": {\"@type\": \"QuantitativeValue\", \"minValue\": 0, \"maxValue\": 1, \"unitCode\": \"d\"},\n        \"transitTime\": {\"@type\": \"QuantitativeValue\", \"minValue\": 2, \"maxValue\": 3, \"unitCode\": \"d\"}\n      }\n    }\n  }\n}\n```\n\n## Agent Readiness Score (0–100)\n\n- 0–20: Crawler-only. Agents fail immediately.\n- 21–50: Agent can browse, fails during filters or modals.\n- 51–75: Agent reaches cart, parity issues remain.\n- 76–90: Agent completes checkout reliably, minor parity issues.\n- 91–100: Task URLs, deep links, and governance in place.\n\n**Scoring inputs:** TBT on PDP/cart, INP p75, selector coverage, schema completeness, feed parity, modal friction rate, task success rate in Playwright suite.\n\n## Data-Density Commerce (ACP Sub-Checklist)\n\n- Feed refresh ≤ 15 minutes for price/stock\n- Required + recommended fields ≥ 95% on top 20% SKUs\n- 5,000-char descriptions structured as knowledge base\n- `delivery_estimate` present on SKUs with fast methods\n- Returns: live URL + explicit `return_window`\n- Payment: ACP endpoints respond, totals math correct, idempotent\n\n**Weekly KPI:** Feed completeness %, Answerability %, Description depth (avg chars).\n\n## Backlog Template (MoSCoW)\n\n**Must-have:** WebSite SearchAction JSON-LD, Product + Offer parity with feed, selector contract on PDP/cart/checkout, remove/defer 2 largest third-party scripts.\n\n**Should-have:** Prefilled cart links for top 3 bundles, OfferShippingDetails with delivery windows, consent modal made accessible and keyboard dismissible.\n\n**Could-have:** ReserveAction/BuyAction hints, task URLs for common filtered states.\n\n**Won't-have (for now):** Full SPA rewrite.\n\n## Governance\n\n- Automatic Item Updates: enabled or disabled by policy with owner and review cadence.\n- Bot friction: allow discovery and cart creation, challenge at payment only.\n- Selector contract ownership: product owner maintains and versions each release.\n- Agent identity: treat automation as first-class users with logging and permissions.\n"
}