Modern Web Guidance 1.0: Claude Code, Codex, and Cursor Setup

Install Modern Web Guidance 1.0 as a project skill, then verify one guide-backed frontend task before using it across your repository. Use legacy-scan for reviewed modernization proposals, not unattended rewrites. Set DISABLE_TELEMETRY=1 before the first command when you do not want Modern Web Guidance usage telemetry sent.

What Modern Web Guidance 1.0 changes

Modern Web Guidance gives your existing coding agent targeted browser-platform instructions before it writes code. The 1.0 release, published on November 10, 2026, includes 203 use-case guides covering 250 web-platform features. Chrome, Edge, Firefox, and MDN steward the project with community contributors.

The skill directs the agent to search for relevant guidance, retrieve it, and apply its implementation rules and fallbacks. Search combines a local embedding model with BM25, a keyword-ranking method. The matching operation needs neither an external model API nor an API key, according to the official project README.

This is useful when an agent knows that a browser API exists but misses details such as transition behavior or compatibility fallbacks. It does not remove your responsibility to define supported browsers, review changes, and run application tests.

Install it in Claude Code, Codex, or Cursor

Use the same project-scoped CLI installation for all three agents. The installation wrapper invokes Vercel Skills. As of 2026-11-13, use Node.js 22.20 or later to satisfy the current Skills installer requirement. You also need npm/npx and permission to download the required packages.

Open Bash in your project root. Disable Modern Web Guidance telemetry before starting the official installation command:

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

The interactive installer lets you choose the target agents. Select Claude Code, Codex, Cursor, or the subset you use. Keep the project scope for a repository-specific trial; the underlying installer uses project scope by default.

For this CLI installation route, check these project files and invocation methods:

Agent	Project skill file	Explicit invocation
Claude Code	.claude/skills/modern-web-guidance/SKILL.md	Enter /modern-web-guidance.
Codex	.agents/skills/modern-web-guidance/SKILL.md	Use /skills, or mention $modern-web-guidance.
Cursor	.agents/skills/modern-web-guidance/SKILL.md	Type / in Agent chat and select the skill.

The directories reflect the current installer’s agent mapping. They are not plugin-cache paths or global installation paths.

Start a fresh agent session in the same repository and invoke the skill explicitly for the first check. If it is missing, confirm the selected agent, installation scope, and file location before reinstalling.

Update a CLI-installed skill from the project directory with:

npx modern-web-guidance@latest update

Review changed skill files and repeat the retrieval check below after updating. These commands use @latest; do not assume a future update will remain on version 1.0.

Marketplace installation is a separate route. Keep its update process separate from this CLI procedure. For Claude Code plugin packaging and lifecycle checks, see how to install, verify, and remove Claude Code plugins.

Verify search, retrieval, and actual agent use

Verify both the CLI and the agent’s use of its output. A successful terminal command alone does not show that the agent loaded the skill.

Run the documented dialog example in Bash:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

Search returns JSON containing guide IDs and descriptions. Retrieval returns the selected guide’s content. For large output, the CLI can print a saved file path instead; have the agent read that file in full.

Then invoke the installed skill and give the agent a bounded task:

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

Check the tool trace for an actual search and retrieval. The final report should identify the guide and explain which implementation decisions it affected. A statement that the agent “used best practices” is insufficient evidence.

The released dialog animation guide provides a concrete review point. When code uses the transition shorthand, transition-behavior: allow-discrete must follow it to avoid being reset. Test entry and exit behavior, reduced-motion behavior, and your existing dialog interactions.

If the first command fails before returning search results, check Node.js and package-download permissions first. The released skill instructions explicitly distinguish package fetching from offline operation. Approve the required package command rather than allowing arbitrary npx execution.

If search results are irrelevant, try a concrete browser behavior such as “confirmation modal dialog.” Do not retrieve an unrelated guide just to make the workflow appear successful.

Use legacy-scan for a review, not an automatic rewrite

Use legacy-scan to identify candidates for modernization across a repository or directory. For a specific component change, use search and retrieval instead, as the modernization workflow documentation explains.

Run a readable scan from the project root:

npx modern-web-guidance@latest legacy-scan .

For structured output that an agent can review, use:

npx modern-web-guidance@latest legacy-scan . --json

Expect candidate findings mapped to relevant guides, not rewritten source files. The static scanner makes no LLM calls. The agent’s subsequent analysis and edits still use its normal model access.

Ask the agent to follow the documented four-stage workflow:

1. Scan the chosen directory and collect candidate findings.
2. Verify each finding against surrounding code and its keepWhen/dropWhen rules. Drop false positives rather than treating every match as a required change.
3. Report the verified findings and proposed edits. Require approval before modernization begins.
4. Modernize approved findings using the corresponding retrieved guides. Run existing tests and scan the changed scope again.

Pay particular attention to intentional fallbacks and guarded compatibility code. A legacy-looking implementation can remain necessary under your browser support policy.

Version 1.0’s scanner covers roughly 20% of guides: those with deterministic legacy-detection rules. That figure is a share of the guide catalog, not a percentage of your codebase. Zero findings therefore do not establish that the project is fully modern, accessible, or correct.

Set browser policy and .mwgrc before modernization

Keep compatibility requirements explicit, and leave experimental guidance disabled unless the project needs it. By default, the skill treats Baseline Widely available features as usable without fallbacks.

The Baseline configuration instructions explain how to record a project target in AGENTS.md or CLAUDE.md. Use your actual support policy rather than changing it solely to accept a suggested replacement.

An optional .mwgrc JSON file in the project root controls experimental guidance. To record a conservative policy, merge these fields into any existing configuration:

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

Volatile guidance covers single-engine features shipped within the last 3 months or still stabilizing. Such guides remain searchable, but retrieval requires explicit permission. Origin Trial guidance has a separate gate.

To allow volatile-feature guidance, run this in your own interactive Bash terminal:

npx modern-web-guidance@latest set-allow-volatile-features

For Origin Trial guidance, use the separate command only when needed:

npx modern-web-guidance@latest set-allow-origin-trials

The commands request confirmation and set the corresponding Boolean to true. Check the printed configuration path and changed key, then retry retrieval.

A refusal inside an agent or non-interactive shell is deliberate. The opt-in implementation requires a human-controlled interactive terminal. Do not ask the agent to bypass that check.

These switches unlock guidance. They do not enable a browser feature, enroll your site in an Origin Trial, or expand your supported-browser policy.

Control telemetry and context costs

Disable telemetry in the environment that actually launches Modern Web Guidance, not only in an unrelated terminal. The project privacy section says collected information includes installation counts, agent names, retrieved guide IDs, and agent-generated search queries. It says raw user prompts are not collected.

Search queries can still reveal task details. Add export DISABLE_TELEMETRY=1 to your Bash startup configuration, such as .bashrc, and ensure the agent’s command environment inherits it. Restart an already-running agent or IDE with the updated environment when necessary.

In the Bash environment used for tool calls, this check confirms the value without printing it:

test "${DISABLE_TELEMETRY:-}" = 1

Exit status 0 confirms that the variable is set to 1 there. It is not a network-traffic audit. This check does not establish your agent provider’s or other tools’ telemetry settings.

Offline search also does not mean the entire workflow is offline. Package fetching needs network access, and Modern Web Guidance telemetry is enabled unless disabled.

For context budgeting, the README advertises approximately 205 tokens for modern-web-guidance and 175 tokens for chrome-extensions. Those figures are not an upper bound on a complete agent task. Retrieved guides add content to the context window, while verification and edits require further agent work.

Measure actual usage on representative tasks. Do not calculate savings from the skill’s advertised size alone.

Read the evaluation gains as a reason to run your own trial

Google’s results support trying the skill, but they do not establish a universal success rate or token-saving guarantee. The official README snapshot dated 2026-11-08 reports:

Agent and model label	Tasks / assertions	Without guidance	With guidance	Increase
claude_code / opus-5-5	215 / 1801	57%	88%	31 percentage points
codex_cli / gpt-6.1-sol	215 / 1795	54%	82%	28 percentage points
antigravity_cli / gemini-4-argon	214 / 1673	58%	94%	36 percentage points

These are assertion pass rates, not percentages of production projects completed successfully. The task and assertion counts also differ between rows. Do not treat this table as a controlled ranking of the models against one identical workload.

The evaluation dashboard methodology defines pass rate as passed checks divided by executed checks. Runs that crash or time out before grading are excluded together with their paired run.

Google developed the evaluation around its guidance. Its explanation of common agent failures describes checking outputs against guide-defined expectations. Treat these as vendor-run results, not independent validation of your application’s quality.

For a rollout decision, compare one representative component task with and without guidance. Keep the model, prompt, and browser policy fixed. Review relevant browser behavior, regression tests, elapsed effort, and actual usage.

For the spending side of that decision, use cost per completed coding task rather than token price alone. Keep Modern Web Guidance when it improves the checks that matter in your repository without adding unacceptable review or usage costs.