modern-web-guidance: web platform skills packaged for coding agents

One npx command installs into whichever agent you already run

The entire quickstart is a single line:

npx modern-web-guidance@latest install

That command fetches the npm package and starts an interactive wizard, which is how the README introduces it. There is no configuration file to hand-edit, no plugin marketplace to browse, and no global install to undo later. For a tool aimed at people who are mid-task, that matters more than it sounds, because the failure mode for agent tooling is usually a fifteen minute detour into documentation before anything runs.

The repository tree explains what the wizard is really doing. Instead of one integration, there is a directory per agent family: `.agents/`, `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/` and `.grok-plugin/`, plus two standalone manifests, `gemini-extension.json` and `kimi.plugin.json`. The shared payload lives in `skills/`, and `package.json` wires the two halves together. It declares a `chatSkills` contribution pointing at `./skills/modern-web-guidance/SKILL.md`, and it exposes a binary named `modern-web-guidance` that resolves to `skills/modern-web-guidance/modern-web.mjs`.

That structure is worth pausing on, because it is the design decision that makes the project portable. There is one skill bundle and a thin adapter per agent, rather than the same guidance rewritten once per tool. The manifest also sets the floors: Node 20 or newer, and VS Code 1.90 or newer, which indicates at least one of the supported paths is editor hosted rather than purely terminal hosted. The package identity is `modern-web-guidance`, display name Modern Web Guidance, publisher GoogleChrome, license Apache-2.0, version 0.0.190.

A small oddity worth flagging for anyone tracing the source: the `repository` field inside `package.json` points at `modern-web-guidance-src`, a different repository from the one publishing the skills. The public skills repo is the output, and the authoring repo is upstream of it.

The problem being solved is legacy code in the training set

The README's Why section is unusually blunt about the diagnosis, and the diagnosis is the whole pitch. Coding agents default to older patterns because the training data contains a great deal of legacy code, which pushes them toward generating bloated JavaScript for tasks the platform now handles natively. A modal, a tooltip, an accordion or a carousel is the classic case: each one has a platform answer now, and each one still gets written as a bundle of event listeners and state variables by a model reaching for the pattern it saw most often.

The second half of the argument is subtler and probably the more useful one. Knowing that an API exists is not the same as knowing how experienced people use it. The project's framing is that a model can recall that Anchor Positioning exists and still write a tooltip the wrong way, because it lacks the density of real world implementation patterns that production code depends on. Recall is what a model has; density is what a guide has to supply.

From there the guidance narrows to three priorities. Modern Browser APIs, aimed at APIs agents frequently misuse rather than APIs they have never heard of. Performance and Accessibility, which the project treats as one category because platform level APIs tend to be both faster and more accessible than the hand rolled equivalent. And Responsible Fallbacks, steering agents toward lightweight fallbacks instead of shipping a large polyfill or a legacy library when the browser may already have what is needed.

There is a fourth idea woven through it: token efficiency. The README says the guides are designed to be token efficient, and that evals exist specifically to prune content models already know well. That reframes what the project is. It is not an attempt to stuff documentation into a context window, it is an attempt to keep only the part of documentation that changes what a model would otherwise do.

Six disciplines and a 113 feature list

Coverage is organised into what the README calls core disciplines, and the grouping is revealing because it tracks how front end work is actually done rather than how the platform is specified. User Experience covers visual states, with View Transitions, entry and exit animations, parallax scroll and the `scrollbar-color` property. CSS Layout covers container queries, `subgrid`, modern color spaces such as `oklch`, text wrap tuning and line height trimming. Performance covers instant preloading, Interaction to Next Paint diagnostics and yielding the main thread with `scheduler.yield`. Forms and UI covers Anchor Positioning for tooltips, the Popover API, dialogs, `:user-invalid` validation and auto-sizing fields. Accessibility covers screen reader and keyboard operability alongside content navigation and discoverability. Built-in AI covers local client models, specifically native translation, summarization and language detection APIs.

Beneath that sits a longer feature list, and the README puts a number on it: 113 modern web features. CSS and Layout alone accounts for 55 of them, and the entries are recognisable: `::backdrop`, `:has()`, `@starting-style`, `field-sizing`, `oklch`, scroll-driven animations, `scrollbar-color`, `scrollbar-width`, `:user-valid and :user-invalid`, `@function` and `image-set()`.

What makes the list useful rather than decorative is the linking. Each feature points into the web features explorer, which is where compatibility data lives. A guide that tells an agent to use `:has()` is only half the answer; the other half is knowing which browser versions support it, and that is exactly the question the explorer answers. The README also links one example guide in full, the `navigation-drawer` guide under overlays, which is the quickest way to see the intended shape of an individual document: a task description, the platform APIs that solve it, and the fallback when they are unavailable.

Search returns guide IDs, retrieve returns the guide

The same package doubles as a query tool, and this is the part that makes it usable before you commit to installing anything. The README offers a try it out path with no setup:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"

Retrieval is a separate, explicit step. The result of a search is an identifier rather than a document, and you ask for the document by that identifier:

npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

The division of labour is the interesting part. Search takes natural language that describes an intent, the way you would describe the problem to a colleague, and resolves it to a stable ID. Retrieve takes that ID and returns the guide. That keeps the matching step fuzzy and the delivery step deterministic, which is the right split when the consumer is a context window: you do not want a search result to smuggle three loosely related documents into a prompt when one precise one was asked for.

The example IDs are also a decent summary of what the project thinks a task looks like. `animate-to-from-top-layer` is a verb phrase describing an effect, not a name for an API. `animate a dialog modal backdrop` is a description a person would type. Neither resembles a documentation heading, which suggests the retrieval layer was built around intent matching rather than keyword lookup.

Both subcommands run straight from the published package, so the fastest way to evaluate the project is to run a search against a real task from your own backlog and read the guide that comes back. If the answer is not useful, you have lost nothing.

The evals exist to delete content, and the release notes publish the numbers

Releases v0.0.188 and v0.0.189, both published in September 2026, carry the same evaluation table rather than a changelog of content changes. Each entry pairs an agent and model with a guided and unguided pass rate across 132 tasks and 1124 assertions. The codex CLI running gpt-5.6-sol moves from 59 percent to 81 percent. Claude Code running claude-sonnet-5 moves from 54 percent to 87 percent. Antigravity running gemini-3.8-flash-medium moves from 65 percent to 91 percent.

Read those figures as what they are: numbers the project publishes about its own evaluation, which is a claim rather than an independent result, and one whose task set is not documented in the repository. What makes them interesting is not the absolute level but the direction and the consistency. All three configurations improve, by 22, 33 and 26 percentage points respectively, and the guided pass rates cluster in a narrow band near the low nineties even though the unguided baselines are spread out. That pattern is what you would expect if the guidance is supplying something a model consistently lacks rather than unlocking capability.

The evals also have a second job, stated plainly in the README. Content that models already know gets pruned, because a skill that restates common knowledge spends tokens to say nothing. That is the pruning mechanism made visible, and it is the reason a skill set like this can stay current without growing without limit.

Release v0.0.190, published 2026-09-21, goes back to content and shows how granular the units are. It adds a guide on out-of-order HTML streaming, which covers perceived performance by streaming initial shell markup and injecting deferred fragments asynchronously. It adds a guide on sanitising untrusted HTML to prevent cross site scripting. It adds a guide on choosing accessible high contrast foreground colours automatically for dynamic backgrounds. And it updates the `ime-safe-enter-submit` guide. Three separate documents in one release, each filed under a specific category path such as guides/performance or guides/security, which tells you the guides are a curated corpus rather than a single prompt file.

A preview release, a separate source repo, and one open issue

The README labels this a preview release and says new content is being added, with contributions and feedback routed to the modern-web-guidance-src repository on GitHub. That is the honest framing and it has a practical consequence: the repository you are reading publishes generated output, so authoring conventions live upstream and the public tree is a snapshot at version 0.0.190.

The health signals are good. The project has 2345 stars and 85 forks, a single open issue, an Apache-2.0 licence, and a last push on 2026-09-21, so the line is moving and there is no sign of a project winding down. Support comes from the Google Chrome team, the Microsoft Edge team and the wider web development community, and the homepage is a short link at goo.gle/modern-web-guidance.

The tree is also worth reading as a description of intent. There is a `policies/` directory that does not appear in the README at all, which suggests the project has editorial rules for what belongs in a guide, and `CONTRIBUTING.md` next to it. For a corpus whose quality depends entirely on what gets left out, having somewhere to write down the exclusion criteria is more significant than the guide count.

The honest limit here is that the README is an advertisement and an index, not a manual. It tells you what is covered and how to fetch it, and it is genuinely good at that. It does not document the CLI's full command set, the retrieval scoring, the evaluation task set, or the authoring conventions. Those are either upstream in modern-web-guidance-src or not published. For a tool you would run through npx on your own machine that is an acceptable trade, since the trial is cheap, but anyone planning to depend on the corpus should expect to read the source repository for the details the front page leaves out.

Editorial conclusion

Modern Web Guidance is at its best when an agent is about to write front end code and would otherwise reach for a library it does not need. The install path is one command, the retrieval model is search then retrieve by guide ID, and the coverage table tells you in advance whether a topic is in scope, with 113 features listed and links out to the web features explorer for compatibility data. Two caveats are worth holding onto. The guides are versioned against the platform as the browser teams ship it, so a pin from six months ago is genuinely older guidance rather than the same advice worded differently, and the repository labels itself a preview with the authoring source kept in modern-web-guidance-src, which means the guide set you get is generated rather than hand maintained in place. Start by running the search subcommand against a real task from your backlog and reading the guide it hands back before you install anything at all.

Frequently asked questions

Official sources

1. GoogleChrome/modern-web-guidance on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases