Modern Web Guidance (Source)

This repo is the source repository for GoogleChrome/modern-web-guidance and includes the code and documentation for authoring, calibrating, and evaluating its contents.

Modern Web Guidance is a set of skills that embed web platform expertise, best practices, and browser compatibility data directly into your coding agents. It helps to steer your coding agents away from legacy patterns, and instead toward solutions that harness the power and capabilities of the modern web platform.

[!NOTE] This is a preview release of Modern Web Guidance. We're actively adding new content and we welcome contributions or feedback on GitHub.

See CONTRIBUTING.md for how we work on the project and orientation of the codebase. We're open to contributions to guidance, eval cases, eval infra and more. :)

Supported by the Google Chrome team, the Microsoft Edge team, and the web development community.

Quickstart

npx modern-web-guidance@latest install

This command runs an interactive wizard to install Modern Web Guidance. See Alternative Installation Methods below.

Try it out (without installing)

# Search for relevant guides
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

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

Why?

Coding agents often default to older patterns because LLM training data contains vast amounts of legacy code. This often leads them to generate bloated JavaScript for tasks that now have native, high-performance web platform solutions.

Even if a model knows an API exists, it often lacks the density of real-world, modern implementation patterns required for production-ready code.

Modern Web Guidance bridges this gap. Our skill's CLI returns targeted, expert-curated guidelines directly into your agent's context window, focusing on: * Modern Browser APIs: Helping models correctly structure APIs they frequently misuse. * Performance & Accessibility: Preferring platform-level APIs that can be optimized by the browser and include built-in accessibility affordances. * Responsible Fallbacks: Guiding models to use sensible, lightweight fallbacks instead of heavy polyfills or legacy libraries.

What's Included?

We cover the past several years of the web platform's new features, all the way up to the cutting edge. The guides are designed to be token-efficient; we run evals enabling us to prune lowest-common-denominator content that models already know.

Core Disciplines

View an example: the navigation-drawer guide.

Safe Adoption of Modern Features

• Progressive Enhancement & Nuanced Fallbacks: We distinguish between purely additive enhancements (like speculative preloading) which are safe to let older browsers silently ignore, and critical behaviors (like dialog controls or network beacons) where we write highly considered, low-overhead fallbacks.
• Responsible Fallbacks: We prioritize lightweight, case-specific custom fallbacks (<50 LOC) or conditionally-loaded polyfills instead of heavy third-party bundles.
• Gotchas & Quirks: We document hidden platform limitations, such as the 64KB payload quota for fetchLater() or macOS-specific scrollbar behaviors.
• Baseline-Aware Integration: We leverage real-time compatibility data from the Baseline project so agents can dynamically adapt to current browser support and any browser support preferences.

How It Works

1. Activation: The coding agent activates the modern-web-guidance skill because of a relevant task. The agent is instructed to use the modern-web-guidance CLI for web platform queries.
2. Local Semantic Search: The agent runs modern-web-guidance search "<query>". The tool matches the query to the best guide using an offline, CPU-efficient TensorFlow.js model (no network calls, no API keys).
3. Guide Fetch: The agent retrieves the guide via modern-web-guidance retrieve <guide-id>, inserting targeted code patterns, gotchas, and fallbacks directly into its context window.

[!TIP] Note: We use npx to ensure the content doesn't go stale, but the CLI works offline, completely private and local. The npm package is self-contained, with no extra dependencies to ensure both low-latency and supply-chain security.

Alternative Installation Methods

Vercel Skills CLI (aka npx skills)

npx skills add GoogleChrome/modern-web-guidance

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

Google Antigravity

agy plugin install https://github.com/GoogleChrome/modern-web-guidance

GitHub Copilot CLI

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome

Claude Code Plugin

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin  # Select GoogleChrome marketplace, press enter, enable AutoUpdate
/reload-plugins

Updating

If you installed the skill using npx modern-web-guidance@latest install, you can update with: npx modern-web-guidance@latest update.

Otherwise, consult your agent's documentation for updating plugins and skills.

Evals to prove this works well ;)

We developed a robust eval harness to ensure that the content is empirically proven and continuously calibrated to ensure AI agents write better code. We run automated evaluations using a closed-loop validation pipeline:

  [ Expert-authored guidance and demo ]
            │
            ▼
  [ Generated assets ] ──> Playwright Grader (.spec.ts) & Negative Demo (.html)
            │
            ▼
  [ Calibration loop ] ───────> Runs Grader on Gold-Standard Demo (Must Pass 100%)
            │                   Runs Grader on Negative Demo (Must Fail 100%)
            ▼
  [ E2E agent evals ] ────────> Runs coding agents in guided vs. unguided modes
                                Compares accuracy w/ and w/o the skill

1. Simulated Developer Tasks: We define realistic, developer prompts that mimic real-world requests (e.g., "make my images load faster"). The prompts avoid naming APIs or features, testing whether the agent can successfully discover the relevant guides naturally.
2. Browser-based Assertions: We write browser automation scripts that verify the guide was followed correctly: exact runtime behaviors, computed styles, accessibility states, etc.
3. Self-Healing Calibration: Graders are calibrated against both a reference implementation (100% pass target) and a control page (0% pass target). The agent automatically refines tests on failure.
4. E2E Testing: We measure coding agent performance on real tasks with and without guidance. The opportunity (100% - unguided pass rate) and uplift (guided - unguided pass rate) are key. If there's little opportunity, then models already do a great job and our guidance isn't providing much value. Based on the results, we revise guides to maximize the uplift, optimizing their effectiveness.

Recent eval results snapshot

Available Skill Packs

You can customize which skill packs are installed using the --choose flag:

npx modern-web-guidance@latest install --choose

• modern-web-guidance (~234 tokens): Comprehensive guidance on modern browser APIs, layouts, and performance.
• chrome-extensions (~181 tokens): Guidance on Manifest V3, background workers, extension APIs, and Chrome Web Store publishing.

Telemetry & Privacy

Google collects anonymous usage statistics (such as search queries, guide retrievals, and installation) to improve the reliability, relevance, and performance of the tool. You can inspect what is collected in modern-web.ts.

[!TIP] To Opt-Out: set the DISABLE_TELEMETRY=1 env variable in your shell profile (e.g., .bashrc or .zshrc): bash export DISABLE_TELEMETRY=1

Google handles this data in accordance with the Google Privacy Policy.

Contributors

If you'd like to contribute to modern-web-guidance, please see the source repo's CONTRIBUTING.md. The modern-web-guidance repo is purely a publish target for clean skills installation.

Huge thanks to everyone who has contributed!

<img src="https://github.com/GoogleChrome/modern-web-guidance/raw/main/.github/img/file-text.svg" width="24" height="24" style="vertical-align: middle; margin-right: