Free guide
Modern Web Guidance: Stop Your AI Agent Writing Old Web Code
A free skill from the Chrome, Edge, Firefox and MDN teams that hands your coding agent up-to-date web guides before it writes. What it is, how it works, how to set it up, and the fine print.

The short version
- AI coding agents learned from mountains of older web code, so they often hand-build things the browser now does natively. In Chrome's words, they'll "happily write 100 lines of custom JavaScript for something modern HTML and CSS can do natively in a few lines."
- Modern Web Guidance 1.0 (released November 10, 2026) gives the agent 203 use-case guides covering 250 web platform features. It is free and open source (Apache-2.0 code, CC BY 4.0 guides).
- In the project's own tests on November 8, Claude Code with Opus 5.5 went from 57% to 88% with the guidance on, Codex from 54% to 82%, and Antigravity from 58% to 94%.
How it actually works
Hand-washing next to a washing machine
Ask an agent for a delete-confirmation popup and the old pattern is a fake window: a div overlay, plus your own code for focus, the Escape key and scroll locking. The browser has a built-in <dialog> element that does that work. The project's dialog guide says the native dialog provides "the accessibility semantics, focus handling, top-layer rendering and Esc handling that custom overlays have to rebuild by hand." The agent isn't lazy. Its training data is simply full of the old way.
Step 1: the skill wakes up on web tasks
When the agent gets a task about HTML, CSS or client-side JavaScript, the modern-web-guidance skill tells it to check the guides first. Backend, CI and tooling tasks are out of scope.
Step 2: it searches on your own computer
The agent runs modern-web-guidance search with a short query, for a delete popup something like confirmation modal dialog. The README says the search uses an offline, zero-dependency embedding model plus BM25, with no network calls and no API keys. In our sandbox run, with the network switched off, that exact search returned 10 guides, with the dialog guide first.
Step 3: it pulls the guide into its context, then writes
modern-web-guidance retrieve <id> puts the guide's code patterns, gotchas and fallbacks straight into the agent's context window. For the dialog example, the guide says to use <dialog> opened with showModal() or a declarative command attribute, and not to add a dialog role, a focus trap or an Esc handler, because the browser already provides them.
How to set it up
1.Install it with the wizard
One command starts an interactive installer that adds the skill to your coding agent. You need Node.js 22 or later.
npx modern-web-guidance@latest install2.Or add it as a Claude Code plugin
Inside Claude Code. Then open /plugin, pick the GoogleChrome marketplace and turn on auto-update, and run /reload-plugins.
/plugin marketplace add GoogleChrome/modern-web-guidance /plugin install modern-web-guidance@googlechrome3.Or add it to Codex
The README also lists installs for Copilot CLI, Google Antigravity, Grok Build, Kimi Code, npx skills and gh skill.
codex plugin marketplace add GoogleChrome/modern-web-guidance codex plugin add modern-web-guidance@googlechrome4.Try the search before you install anything
See which guides your agent would get for a task.
npx modern-web-guidance@latest search "confirmation modal dialog" npx modern-web-guidance@latest retrieve dialog5.Optional: scan an existing project for old patterns
legacy-scan looks for known legacy patterns and points each finding at the guide with the modern replacement. It only covers about 20% of the guides (33 in version 1.0.0), so a clean scan doesn't mean the code is modern: on our small demo page it found nothing.
npx modern-web-guidance@latest legacy-scan .6.Optional: turn off the usage data
Add this to your shell profile (.zshrc or .bashrc).
export DISABLE_TELEMETRY=1
The fine print
- Telemetry: Google collects anonymous usage information, including install counts, the calling agent's name, the guide IDs it retrieves and the search queries the agent writes. Raw prompts aren't collected. Set DISABLE_TELEMETRY=1 to opt out.
- License: the code is Apache-2.0 and the guide content is CC BY 4.0. It's free and needs no account or API key.
- The eval numbers are the project's own tests, run on its own sample apps with Playwright graders. They're useful, but they aren't an independent benchmark.
- It steers the agent; it doesn't guarantee the result. Review what your agent writes, and check browser support for anything new.
- Guides for experimental Origin Trial features and brand-new single-browser features can be found with search but won't be retrieved until you opt in with a .mwgrc file.
- The repo was created in March 2026; version 1.0 shipped on November 10, 2026.
FAQ
What is Modern Web Guidance?
A free, open-source set of skills for AI coding agents that embeds web platform best practices and browser compatibility data. It's stewarded by the Google Chrome, Microsoft Edge, Mozilla Firefox and MDN teams, and version 1.0 has 203 use-case guides covering 250 web platform features.
Does Modern Web Guidance work with Claude Code?
Yes. Install it with npx modern-web-guidance@latest install, or as a Claude Code plugin with /plugin marketplace add GoogleChrome/modern-web-guidance and /plugin install modern-web-guidance@googlechrome. It also works with Codex, GitHub Copilot, Google Antigravity, Cursor, Kimi, Grok and more.
Is Modern Web Guidance free?
Yes. The code is Apache-2.0, the guides are CC BY 4.0, and it runs with npx. There's no account or API key.
Does it send my code to Google?
The search runs offline on your computer. Google does collect anonymous usage data, such as install counts, the agent's name, retrieved guide IDs and the search queries the agent writes, but not your raw prompts. Set DISABLE_TELEMETRY=1 to turn that off.
Does it actually make AI-written code better?
In the project's own tests on November 8, Claude Code with Opus 5.5 scored 57% without the guidance and 88% with it, Codex 54% to 82%, and Antigravity 58% to 94%. Those are the project's own evals on its own sample apps, not an independent benchmark.
Sources
- Modern Web Guidance on GitHub
- Chrome for Developers docs
- Eval dashboard
- Source repo (issues, contributing)
- Version 1.0 announcement on X (@ChromiumDev)
Facts checked 2026-11-16 against the Modern Web Guidance README and v1.0.0 release notes, the Chrome for Developers docs page, npm (modern-web-guidance 1.0.0), the GitHub API (18,598 stars, Apache-2.0, created 2026-03-23) and @ChromiumDev's launch posts. We ran the 1.0.0 CLI ourselves in a sandbox with the network switched off (search, retrieve and legacy-scan).
Want help building with tools like this?
Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.
Join Shipping SkoolMore free guides
How Claude Code's Advisor Works (and How to Turn It On)
The trick going around X is a real Claude Code feature: a cheaper model does the work and asks a stronger model for advice only at the hard moments. Here's how the handoff works and how to set it up.
Qwen4-Max: Why Alibaba's New Model Costs a Third as Much per Job
Alibaba's full Qwen4-Max release scores higher than the model before it and, in Artificial Analysis' test, costs about a third as much per task. Here's where the savings come from, how to try it today, and where it still trails.
How ChatGPT Wallet Pays Without Seeing Your Card (and How to Set It Up)
OpenAI's new ChatGPT Wallet lets your dot pay for things on your behalf, and neither the agent nor the store ever sees your real card number. Here's how the stand-in card works and how to set it up.