跪拜 Guibai
← Back to the summary

Chrome's Modern Web Guidance Shoves Curated Best Practices Into AI Coding Agents

Introduction

"Keep your coding agent up to date with the latest web best practices."

This is the 259th article in the "One Open Source Project a Day" series. Today's project is GoogleChrome's Modern Web Guidance.

When you ask AI to write frontend code, a common awkward thing happens: what it produces runs, but feels "old." For popups, it computes positions using JavaScript when browsers already have native solutions; for animations and accessibility, it leans on a pile of libraries when the platform itself already supports them. The reason is straightforward: training data contains far more old code than new patterns.

This project's approach: instead of modifying the model, feed the agent curated modern Web guidance into its context while it works. More interestingly, it doesn't just provide content—it ships a built-in evaluation pipeline with data showing whether "feeding the guidance" actually helps. This article is based on the README and repository docs; I have not installed and run these commands myself.

What you'll learn

Prerequisites


Project Background

Project Overview

Modern Web Guidance is a set of Skills that feed Web platform knowledge, best practices, and browser compatibility data into AI coding agents. The README says it is maintained by the Chrome, Edge, Firefox, and MDN teams along with the broader Web community.

Note the repository division: the modern-web-guidance-src linked here is the source repository, containing guide drafts, scripts, evaluation framework, sample base apps, and CLI tooling. All issues and PRs go here. The other, GoogleChrome/modern-web-guidance, is a read-only release repository holding compiled Skills and plugin configuration. Merged changes are published weekly to the release repository and the npm package modern-web-guidance.

Project Data


Main Features

The Problem It Solves

Without guidance:
  Agent codes from training data → biases toward older patterns, heavy JavaScript, unnecessary libraries
  ↑ Even if it knows an API exists, it lacks enough modern, real-world examples

With guidance:
  Agent hits a Web platform problem → calls CLI retrieval → gets curated guides
  ↓ Guides contain code patterns, pitfalls, fallback approaches
  ↑ Output is closer to modern, production-ready code

Quick Start

Interactive install:

npx modern-web-guidance@latest install

Try the three subcommands without installing:

# Search for the best-matching guide by description
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# Retrieve full guide by ID
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

# Scan current project for legacy patterns
npx modern-web-guidance@latest legacy-scan .

After installation, the agent activates the modern-web-guidance Skill for relevant tasks and is instructed to use the CLI when hitting Web platform problems. Update with npx modern-web-guidance@latest update.

Other Installation Methods

The README gives install entry points for several tools:

Tool Command or method
Vercel Skills CLI npx skills add GoogleChrome/modern-web-guidance
GitHub CLI gh skill install GoogleChrome/modern-web-guidance
OpenAI Codex codex plugin marketplace add GoogleChrome/modern-web-guidance, then codex plugin add modern-web-guidance@googlechrome
Claude Code Via plugin marketplace, then enable auto-update in /plugin and /reload-plugins
GitHub Copilot CLI /plugin marketplace add, then /plugin install modern-web-guidance@googlechrome
Google Antigravity agy plugin install <repo URL>
Grok Build CLI grok plugin install <repo URL> --trust
Kimi Code /plugins install <repo URL>

Additionally, two optional Skill packages can be chosen with install --choose: modern-web-guidance (browser APIs, layout, performance) and chrome-extensions (Manifest V3, Workers, extension APIs, store publishing).

Content Coverage

The README lists the scale: 250 modern Web features (140 CSS & layout, 36 HTML & DOM, 74 JavaScript & API) and 203 real-world development scenarios. Guides are organized by category: accessibility, built-in-ai, css, forms, html, js, performance, privacy, pwa, security, ui-atoms, ui-behaviors, ui-components, user-experience, visual-design, wasm, webmcp. Guides in the release repository follow paths like skills/modern-web-guidance/guides/ui-components/navigation-drawer.md.


Detailed Analysis

Two-Step Retrieval: First search, then retrieve

  1. Activation: The agent enables the Skill for relevant tasks and is told to use the CLI to answer Web platform questions.
  2. search: Uses an offline, zero-dependency embedding model plus BM25 to match natural language queries to the most relevant guides. No network, no API key needed.
  3. retrieve: Pulls the guide's code patterns, pitfalls, and fallbacks into the agent's context by guide ID.

The npm package is self-contained with no extra dependencies, which the README says is for low latency and supply-chain security. Using npx ensures content doesn't go stale while the CLI itself can operate offline.

Principles for Safely Adopting New Features

The biggest risk with new APIs is compatibility. The project codifies "how to use them safely" into rules:

Consent can be written to a project-root .mwgrc (or user-level ~/.mwgrc):

# Allow Origin Trial guides
npx modern-web-guidance@latest set-allow-origin-trials
# Allow unstable single-engine feature guides
npx modern-web-guidance@latest set-allow-volatile-features

This file can be committed to the repo, letting the whole team share the same settings.

Built-in Closed-Loop Evaluation

This is the part I found most valuable. Most Skill projects just deliver content; this one turns "is the content useful" into a pipeline:

  1. Experts write guides
  2. Automatically generate eval targets: tasks, golden solutions, Playwright scoring scripts
  3. Self-calibration: scoring scripts must pass 100% on the golden solution and fail 100% on the unmodified base app, or they're rejected
  4. End-to-end run: Agents complete tasks in "with guidance" and "without guidance" modes, using two base apps (daily-grind and devtools-times), with prompts that don't name specific APIs
  5. Iterate on metrics:
Metric Meaning
opportunity 100% minus the no-guidance pass rate; represents remaining headroom for improvement
uplift With-guidance pass rate minus no-guidance pass rate

Guides agents already handle correctly get trimmed; weak guides get improved. Scoring scripts check source patterns, computed styles, runtime DOM behavior, and accessibility states.

How to Read the Official Results

The README has a date-updated results table; the batch I saw was from November 8:

Agent No guidance → With guidance Uplift
antigravity_cli 58% → 94% +36 points
claude_code 57% → 88% +31 points
codex_cli 54% → 82% +28 points

The README itself summarizes as roughly +27 to +36 percentage points. Keep in mind when reading these numbers:

Telemetry

The README explicitly says anonymous data is collected: installation counts, agent name, retrieved guide IDs, and search queries generated by agents. Raw user prompts are not collected. To disable, set the environment variable DISABLE_TELEMETRY=1. Before using in a company project, it's worth confirming this meets your compliance requirements.

Want to Contribute Content?

Key points from CONTRIBUTING.md:

Limitations and Caveats

  1. Evaluation data comes from the project itself and is continuously updated; numbers will change.
  2. However large the guide coverage, it's still ~250 features and 203 scenarios; problems not in the list still fall back to the model.
  3. Gating of new features relies on developer judgment; enabling them means you take on compatibility risk.
  4. Telemetry is on by default and must be manually turned off.
  5. The README describes the project as active but doesn't mark it beta or stable; assess maturity yourself before using.

Project Links and Resources


Summary and Outlook

Key Points Recap

  1. Problem identification is accurate: AI frontend code skews old because of training data, so the fix is to supplement via context.
  2. Two-step retrieval: Offline search plus retrieve, no network or keys required.
  3. Safe adoption of new features: Progressive enhancement, lightweight fallbacks, Baseline data, plus gating for unstable features.
  4. Content and evals integrated: Whether guides work is validated by with/without-guidance controlled experiments to trim and improve.
  5. Read numbers with a grain of salt: +27 to +36 points is the project's own evaluation, not a third-party conclusion.

Who It's For

Learning Suggestions

Before installing, try search with a few common requirements from your work, like "modal" or "scroll-driven animations," and see the quality of returned guides. Then run legacy-scan . on your own project to see which patterns it calls old. Finally, read docs/EVALS.md—that's the most distinctive part of the project.


Visit PrimeSkills — a curated marketplace for AI agents and skills, with everything validated by real enterprise-grade workflows. No gimmicks, only what actually works.

For more practical knowledge and interesting products, visit my personal homepage