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.

By Beau Johnson·
The Short this guide goes with: Modern Web Guidance: Stop Your AI Agent Writing Old Web Code

Quick answer

Modern Web Guidance is a free, open-source set of skills, stewarded by the Google Chrome, Microsoft Edge, Mozilla Firefox and MDN teams, that gives your AI coding agent current web guides before it writes front-end code. The agent searches the guides on your own computer, pulls the one that fits into its context, and uses the browser's built-in features instead of hand-building them. Install it with npx modern-web-guidance@latest install, or as a plugin in Claude Code or Codex.

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. 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 install
  2. 2.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@googlechrome
  3. 3.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@googlechrome
  4. 4.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 dialog
  5. 5.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. 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

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 Skool

More free guides