Tech Teardown 046 | modern-web-guidance: a Manual for Coding Agents

Background: One day after v1.0.0 release, 3,000 stars and a theoretical debate

On November 10, 2026, the GitHub repository GoogleChrome/modern-web-guidance released v1.0.0 under an Apache-2.0 license. As of November 11, it had exceeded 3,000★ (3,109). On the same day, it appeared on Show HN with a score of 209 and 58 comments.

What stands out most about this project is not the number of stars, but the attribution: The README document is maintained by four teams—Google Chrome, Microsoft Edge, Mozilla Firefox, and MDN—along with the Web development community. It’s rare in Web standard history for these four major browser brands to endorse the same “agent manual.”

The problem it aims to solve can be summarized in one sentence: LLM training data is filled with legacy code, and agents defaultly generate bulky JS, even when high-performance native solutions already exist for tasks. Even if the model knows about the existence of APIs, there’s a lack of density in production-level implementation patterns. Paulirish from the Chrome team gave an example on HN: browsers can now handle things that used to require 50 lines of JS or one dependency; CSS.highlights handles text highlighting, dialog adds showModal() with its own backdrop and focus management, and field-sizing automatically increases the size of textarea as input is entered. The model knows the names of these APIs, but it doesn’t use them by default.

The approach is to package Web platform expertise, best practices, and browser compatibility data into skills, which are directly embedded in the coding agent’s workflow. Category signals are hidden in the installation list: Vercel Skills CLI, gh skill install, and each agent’s plugin market. A single README covers eight distribution channels, indicating that “providing agents with external knowledge” is becoming infrastructure, and browser manufacturers are joining forces as content providers for the first time. Also note the repository division of labor: this repository serves as a distribution and packaging hub, with source code in GoogleChrome/modern-web-guidance-src. In the shallow clone, there’s only one commit for Release v1.0.0; all project development history is on the -src side.

Architecture and Principles: Documentation is the product, retrieval is the pipeline

Local statistics (excluding .git): 265 files, of which 236 are markdown files. There are no traditional source codes; it is essentially a “document-is-product” repository. The main content consists of 209 guides under skills/modern-web-guidance, categorized into 17 fields: css, js, html, forms, accessibility, performance, security, privacy, pwa, wasm, webmcp, built-in-ai, ui-components, ui-atoms, ui-behaviors, visual-design, user-experience, etc. There is also a second skill package called chrome-extensions (Manifest V3, background workers, extension APIs, and Chrome Web Store publishing). The README covers 250 modern Web features, all linked to the feature pages of the Baseline project (web-platform-dx), with compatibility aligned to support four browsers.

The workflow is divided into three steps: the agent triggers the skill based on tasks; local search is performed. The README uses an offline, zero-dependency embedding model and BM25 for retrieval, without sending network requests or requiring API keys. After a match is found, retrieve injects the full content of the guide into the context. Two engineering details are worth noting: first, the search command must include the —skill-version 2026_11_09-5bcc021b parameter, ensuring that the guide content is fixed to the skill version to prevent drift; second, experimental Origin Trial APIs and “volatile features” (single-engine, released within 3 months or still being stabilized) are visible in search, but retrieve is restricted. Developers must explicitly run set-allow-origin-trials or set-allow-volatile-features to unlock them, as the agent cannot use unstable APIs without permission.

There is also a self-pruning mechanism at the content level. The README guides are “designed to save tokens,” and the accompanying eval process is important: opportunity (100% minus the passing rate without guidance) and uplift (the difference in passing rates between guided and unguided guidance). Content that can be correctly processed without looking at the guide is directly cut out, while areas where the agent faces challenges are enriched. The SKILL.md itself contains about 205 tokens, and the chrome-extensions package contains about 175 tokens. During installation, —choose can be used to select only the necessary packages. The field coverage also shows ambition: the webmcp directory teaches agents how to use WebMCP to expose web form fields and client-side JS functions as AI tools, while the built-in-ai directory explains native APIs for local translation, summarization, and language detection in browsers—all still cutting-edge capabilities.

Detailed Read of Key Mechanisms: “Triggering” is written as a mandatory clause

SKILL.md has only 90 lines, and its design is quite radical: The description states “MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip.” This is because web APIs evolve rapidly, and training weights contain outdated patterns. It then lists a long list of trigger scenarios (modal, popover, container queries, view transitions, scroll-driven animations, autofill, passkeys, CWV, built-in AI, WASM, etc.) as well as scenarios where triggers should not be used: backend SQL/ORM, CI/CD, Docker, Python/Go, build tools, testing. The boundaries are clearer than most human teams’ standards.

The four-step workflow is also specific. Search requires 2-5-word action-oriented queries, focusing on one capability at a time, avoiding framework names and application nouns. If “delete before confirmation” is requested, it should be translated as “confirmation modal dialog” before searching. If no results are found, try a specific noun again, and then downgrade to a list. Retrieve supports multiple items separated by commas, automatically saves output in temporary files larger than 9.5KB to prevent truncation, and requires the agent to use file-reading tools instead of cat/head. In the third step, check implementation against the guide, explicitly stating that legacy-scan is not used in this step. In the fourth step, include “### Modern Web Guidance” at the end, detailing which ID was applied and what pitfalls were avoided, with a brief reference to the guide’s original text. Remembering quotes by memory is prohibited.

The quality of the guide itself can be seen in the navigation-drawer article: The drawer is implemented using top-layer elements (modal dialog or popover in manual mode), with the sliding gesture handled by a horizontal scrolling container with two scroll-snap stops. Momentum, speed, and interruption tracking are all handled by the browser’s native mechanisms, with no JS pointer-event code. The backdrop transparency is tied to the scroll position using scroll-driven animations, and an IntersectionObserver is used to determine the opening and closing states. This is the density of filling in where “the model knows the API names but doesn’t know how to combine them.”

Legacy-scan is a separate entry: It scans existing code for legacy patterns, but only covers about 20% of the guide’s subset (the part with definite rules). The results need to be manually verified against keepWhen/dropWhen rules to remove false positives.

The pitfalls in the execution environment have also been addressed in advance. SKILL.md requires a permission whitelist that is precise to npx -y modern-web-guidance@latest *, explicitly prohibiting the release of bare npx *. In sandbox or approval-based environments (Codex, Claude Code), you must actively request network access authorization before the first execution to avoid timeouts. When ~/.npm is read-only, set NPM_CONFIG_CACHE to refer to /tmp. If the internet is disconnected and the process hangs, return to npx —offline and retry. Use pnpm over pnpx when available. There’s also a bottom line in the Guidelines: Always search first; no reliance on memory-based assumptions for guide content. The guide is the preferred local standard for user projects.

Distribution and Evaluation: One set of content for eight agent ecosystems

Distribution is divided into three layers. CLI layer: npx modern-web-guidance@latest plus 7 sub-commands (install/search/retrieve/legacy-scan/update/set-allow-origin-trials/set-allow-volatile-features), starting from Node 22. Installation layer: README provides eight methods: interactive wizard, Vercel Skills CLI (npx skills add), gh skill install, Google Antigravity, GitHub Copilot CLI, Claude Code plugin, Grok Build CLI, Kimi Code, OpenAI Codex—each with their own command. Listing layer: The repository stores three manifests: plugin.json (agent-plugins.org schema 1.0.0), gemini-extension.json, kimi-plugin.json. The same set of skills is packaged for general agents, Gemini, and Kimi. There’s also policies/modern-web-guidance.toml, which sets modern-web commands to ask_user in plan mode.

All performance numbers are from the README. Evaluation on November 8th: antigravity_cli (gemini-4-argon) improved from 58% to 94% (+36pp), claude_code (opus-5-5) from 57% to 88% (+31pp), codex_cli (gpt-6.1-sol) from 54% to 82% (+28pp). There were approximately 215 tasks and about 1800 assertions. The way questions were posed in the evaluation is noteworthy: prompts simulating real developers were used across two complete benchmark applications (daily-grind, devtools-times), such as “Make my images load faster.” No specific APIs were named, testing whether the agents could naturally discover and use the guides. The scoring system used the golden solutions of three agents—Claude, Codex, and AGY—to determine if they met 100% of the target criteria, with an unmodified baseline application serving as a control (0% pass). The performance metrics in the README were updated every two days starting from November 2nd, with detailed results for each agent displayed on the public Eval Dashboard. These are official figures, not reviewed by third parties, but the approach of reporting both “unguided baselines” is more honest than only high scores.

Truthfully disclosed telemetry: Anonymous collection of installation counts, agent names used, guide IDs, and search terms, without including original prompts. The code locations were listed in the README. Someone on HN provided indirect evidence: it was installed several months ago, and Claude Doctor never removed it, indicating it is still active.

Controversy and Risks: Who has the right to define “modern”

There are both positive and negative opinions on HN’s hot discussion section. On the demand side, the feedback is straightforward: some say it was long overdue, as there have been too many PRs that “can be replaced with two lines of modern features but are written in a messy manner,” and one even created a half-finished tool. There are three main criticisms. First, “best practices are dead in the AI era; soon no one will read AI-generated code.” Paulirish responded that maintainability is the next frontier—a one-line CSS solution is better than 60 lines of business code withResizeObserver and setTimeout. Another added: Best practices to improve user experience are not dead; it’s just that the focus has shifted away from developer efficiency. Second, “modern web primitives” may not equal best practices. Browser implementation differences take ten years to resolve, and manual testing across devices and browsers is unavoidable. Some treat agents as random machines, believing they can still be ineffective after going through a guide and taking an average. The third and most serious issue is governance. Chrome has become too powerful in the standard world, forcing all LLMs to follow its guidance, leading to a situation where “please use this browser to access our site.” Responders pointed out that Firefox and Edge are also contributors, and only recommending practices supported by all four browsers (Baseline) is advised. Another comment suggested publishing opinions on a neutral repository would be better. This concern has a long history: In early 2026, Adrian Roselli criticized the project’s early form in his post “Maybe Don’t Rely on Google’s Modern Web Guidance.” Version 1.0 was jointly maintained by three companies to align with Baseline, which can be seen as a response to this criticism. However, the actual contribution of Mozilla/Edge has not been independently verified this time.

There are also two risks. The evaluation is conducted by the official team itself, and although the terminology for opportunity/uplift is transparent, the task set favors scenarios with native solutions. It’s not surprising that uplift scores high; however, one should discount potential bias in judgment. Regarding distribution, simonw offered a simple suggestion on HN: Besides npm packages, use GitHub Pages to publish a markdown index page (currently 404), linking to pure md versions of all documents designed for grep search, without installing anything. The Chrome team responded by pointing to the guides page on developer.chrome.com. In other words, those who don’t want agents to run npx currently lack an official official path.

Conclusion and Outlook

The value of modern-web-guidance lies not in the 209 documents themselves, but in its setting a precedent for “agent knowledge supply”: knowledge is not stuffed into weights; instead, it becomes an external plugin for on-demand retrieval. It stores pointers rather than content, with fixed versions, experimental feature gates, and mandatory disclosure of usage. Some people say that this is the true holy grail of agents: minimizing built-in knowledge, with real-time retrieval and caching added later. I agree with this direction. Three things worth keeping an eye on: whether Mozilla/Edge’s contributions are just signatures or substantial, as can be seen from the distribution of commits in the -src repository; whether third-party reproductions of eval will occur; and whether the official pure md index page will add more content. For developers, front-end projects can be installed now at low cost (a single npx command), and in the worst case, the agent may query the documents multiple times. For those working on agent infrastructure, the wording of SKILL.md’s trigger conditions, the content pruning methods for opportunity/uplift, and the 9.5KB file size to prevent truncation can all be directly adopted into their own skill systems. When browser manufacturers make “don’t write era code” into machine-executable standards, the symbolic significance of this may be even greater than 3000 stars.

Information Source

• Repository: github.com/GoogleChrome/modern-web-guidance (Apache-2.0; over 3,000★ as of 11-11, snapshot 3,109; v1.0.0 released on 11-10, git log format; source code can be found in GoogleChrome/modern-web-guidance-src)
• 11-11 local clone statistics (read-only, /tmp/mwg-1111): 265 files (excluding .git), 236 markdown documents; 209 guides, 17 domain directories; SKILL.md has 90 lines, README.md has 636 lines; three distribution lists for plugin.json/gemini-extension.json/kimi-plugin.json; policies/modern-web-guidance.toml
• README.md (maintained jointly by four teams as official documentation; 250 features and Baseline links; offline embedding+BM25, —skill-version 2026_11_09-5bcc021b, Origin Trial/volatile feature gate, eight installation methods, 7 CLI subcommands, Node≥22, telemetry disclosure all in README format; three lines of the eval table Nov 8 +36/+31/+28pp are from the README documentation, not reviewed by third parties; number of tokens in the skill package ~205/~175 as documented)
• SKILL.md (MANDATORY trigger clause original text, four-step workflow, 9.5KB size, disclosure section format, legacy-scan covers ~20%); guides/ui-components/navigation-drawer.md (drawer implementation case)
• HN story 50443812 (209▲/58💬, Algolia search): paulirish’s top comments and responses, halflife, phyzix5761, sublinear, advisedwang, philipwalton, 0o777, simonw and kinlan, nico, fumar, cyanydeez; both positive and negative views, not uniformly praised
• adrianroselli.com 2026/05 “Maybe Don’t Rely on Google’s ‘Modern Web Guidance’” (HN 12▲); depth of actual contribution to Mozilla/Edge not independently verified

Author: Yongliang