# Modern Web Guidance: current web platform patterns for coding agents (GoogleChrome/modern-web-guidance) — skill card for AI agents

> AgentGid skill card. Checked on 2026-11-14 against commit 4dd9683 (version 1.0.0).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/googlechrome/modern-web-guidance/

## Explain it to a non-programmer
Your AI coding assistant looks up a short, current guide before it writes web pages, styles or browser code. It then uses what browsers can do today (built-in dialogs, modern layout, passkeys, faster loading) instead of old tricks and extra libraries. A second skill helps it build Chrome extensions and get them ready for the Chrome Web Store.

## Who it is for
- You build websites or web apps with an AI coding assistant and want up-to-date front-end code
- You ask for things like pop-ups, forms, dark mode, animations, accessibility or faster pages
- You want to check an older site for outdated patterns and modernise it
- You are building a Chrome extension and plan to publish it
- Not for: Your work is server code, databases, build setup or scripts: the skill says not to trigger for those
- Not for: You want nothing downloaded from the internet while your assistant works

## What it is
- Kind: knowledge
- License: Apache-2.0
- Repository: https://github.com/GoogleChrome/modern-web-guidance

## What it does
- Search: the assistant turns your request into a 2 to 5 word query (for example "light dismiss dialog") and searches the guide index
- Retrieve: it reads the matching guide plus the broader topic guide (CSS, forms, accessibility, performance, security)
- Verify: it checks its code against the guide, including the fallbacks the guide asks for
- Disclose: it ends the answer with a short section naming each guide that shaped the code
- Modernise (only when asked for a broad scan): legacy-scan finds old patterns, the assistant drops false positives, reports, and fixes only if you asked it to
- Browser support: features that are Baseline widely available are used without fallbacks; newer ones get the guide's fallback unless you set your own policy
- Never cuts: fallbacks the guide requires for features that are not yet Baseline widely available, unless you set a different browser support policy

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| modern-web-guidance | Starts by itself on web UI, CSS or browser JavaScript tasks; or ask ("Audit this project for modern web best practices") | yes | Looks up a current guide before writing web code and follows it |
| chrome-extensions | Starts by itself when you mention a Chrome extension, manifest.json, content script, side panel or publishing to the Chrome Web Store | yes | Builds Chrome extensions the current way and prepares them for the store |

### modern-web-guidance
- Asks for: The web feature or fix you want (a dialog, a form, dark mode, faster images)
- Asks for: Optional: your browser support policy (for example Safari 17.4+, or no polyfills)
- Asks for: For a modernisation: the folder to scan, and whether to fix or only report
- Gives: Code that follows the retrieved guide, with its fallbacks
- Gives: A closing Modern Web Guidance section: one bullet per guide used, with a short quote of the rule
- Gives: For a scan: a report of verified old patterns and a modernisation plan
- Say: "Add a settings dialog that closes when I click outside it"

### chrome-extensions
- Asks for: What the extension should do
- Asks for: For publishing: your manifest.json and project, and any review rejection you received
- Gives: Manifest V3 extension code checked against the skill's output checklist
- Gives: CHROMEWEBSTORE.md in the project root: store listing, graphics notes, permission reasons, privacy and data use, privacy policy, version history, review notes
- Gives: A pre-publish checklist run before you submit
- Say: "Build a Chrome extension that highlights search terms on any page, and prepare it for the Chrome Web Store"

## Know before installing
- The guides are read through a separate npm tool that your assistant downloads with npx at its latest version on each call; the code of that tool is not in this repository.
- Google collects anonymous usage data by default: install counts, the calling agent name, guide IDs and the search queries your assistant writes. Raw prompts are not collected. Set DISABLE_TELEMETRY=1 to opt out.
- It switches on by itself for nearly all HTML, CSS and browser JavaScript tasks; its description calls the lookup mandatory.
- Experimental Origin Trial and volatile features are held back until you opt in with a .mwgrc file in your project or home folder.
- The guide texts themselves are plain markdown in skills/modern-web-guidance/guides/, so you can read them in the repository.
- This repository is a publish target; changes and issues go to GoogleChrome/modern-web-guidance-src.

## Install (official commands)
- Any agent (wizard): `npx modern-web-guidance@latest install` — Interactive wizard. Add --choose to pick the skill packs. Update with npx modern-web-guidance@latest update.
- Claude Code: `/plugin marketplace add GoogleChrome/modern-web-guidance` && `/plugin install modern-web-guidance@googlechrome` && `/reload-plugins` — The README also suggests enabling auto-update for the marketplace in /plugin.
- Codex: `codex plugin marketplace add GoogleChrome/modern-web-guidance` && `codex plugin add modern-web-guidance@googlechrome`
- GitHub Copilot CLI: `/plugin marketplace add GoogleChrome/modern-web-guidance` && `/plugin install modern-web-guidance@googlechrome`
- Any agent (skills CLI): `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`
- Grok Build CLI: `grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust` — The --trust flag is part of the documented command.
- Kimi Code: `/plugins install https://github.com/GoogleChrome/modern-web-guidance`

## What runs on the user's machine
- Code on the machine: rules-only (The repository holds markdown only; the skill tells the assistant to download and run the separate modern-web-guidance npm package)
- Network: yes
- Install: Two skill folders of markdown (SKILL.md, guides and references) and plugin manifests. No hooks and no scripts ship in this repository.
- Every web UI: The assistant runs npx -y modern-web-guidance@latest search and retrieve. npx fetches the latest package from npm; large results are saved to a temporary file. The README says search is local and the package has no extra dependencies.
- Telemetry: The npm tool sends anonymous usage data to Google (install counts, agent name, guide IDs, search queries) unless DISABLE_TELEMETRY=1 is set.
- Broad modernisation request: legacy-scan reads your project folder; the assistant edits files only when you asked to modernise.
- Chrome extension work: The assistant creates or updates CHROMEWEBSTORE.md in your project root.
- Gemini CLI plan mode: A policy file makes shell commands that match modern-web ask you first.

## Settings
- `DISABLE_TELEMETRY`: 1 turns off the usage data the npm tool sends to Google
- `.mwgrc allowOriginTrials`: true unlocks guides for Origin Trial APIs (project root or ~/.mwgrc)
- `.mwgrc allowVolatileFeatures`: true unlocks guides for volatile single-engine features
- `NPM_CONFIG_CACHE`: The skill suggests /tmp/npm-cache when ~/.npm is read-only

## Examples (from the pack's own files)
- The closing Modern Web Guidance section: output format defined in skills/modern-web-guidance/SKILL.md
- A guide the assistant reads (navigation drawer): output format defined in skills/modern-web-guidance/guides/ui-components/navigation-drawer.md

## Author's numbers (as reported, not run by AgentGid)
- 250 modern web features covered. Source: GoogleChrome/modern-web-guidance/README.md
- claude_code (opus-5-5), Nov 8: 57% of checks passed without guidance, 88% with it (+31pp), 215 tasks (Google's eval harness: developer tasks on sample web apps, Playwright graders, guided vs unguided runs). Source: GoogleChrome/modern-web-guidance/README.md
- codex_cli (gpt-6.1-sol), Nov 8: 54% without guidance, 82% with it (+28pp). Source: GoogleChrome/modern-web-guidance/README.md
- legacy-scan covers about 20% of the guides. Source: GoogleChrome/modern-web-guidance/skills/modern-web-guidance/SKILL.md

## Steps only the person can do
- Approve network access for npx modern-web-guidance in sandboxed agents (for example Codex or Claude Code) (skills/modern-web-guidance/SKILL.md (Using npx / pnpx)) Then: The assistant can run search and retrieve without timeouts
- Decide on telemetry: set DISABLE_TELEMETRY=1 in your shell profile to opt out (README.md (Telemetry & Privacy)) Then: The npm tool stops sending usage data
- Publish the extension yourself in the Chrome Developer Dashboard, using CHROMEWEBSTORE.md (skills/chrome-extensions/SKILL.md (Part 2)) Then: The assistant keeps CHROMEWEBSTORE.md updated after later changes

## Mistakes to avoid
- Not: Run legacy-scan for a request about one feature or component. Instead: Use search and retrieve for a named feature; keep legacy-scan for broad, open-ended modernisation. Why: The skill limits legacy-scan to broad scans with no named target
- Not: Treat a clean legacy-scan as proof the code is modern. Instead: Also search the guides for the features the site uses. Why: legacy-scan checks only the guides that have fixed rules
- Not: Allowlist bare npx in a sandbox so the lookups stop asking. Instead: Allowlist only the modern-web-guidance command. Why: The skill itself says to allow the specific command, never npx in general
- Not: Search with framework or app names ("close React settings modal on outside click"). Instead: Search the platform capability in 2 to 5 words ("light dismiss dialog"). Why: The skill says to omit framework and app nouns and split compound searches
- Not: Expect experimental browser APIs in the answers by default. Instead: Opt in with .mwgrc (allowOriginTrials or allowVolatileFeatures) if you want them. Why: Retrieve holds those guides back without explicit consent

## What leaves the machine
- Install counts, the calling agent name, guide IDs and the search queries the assistant writes (not your raw prompts) → Google, When the npm tool runs, by default. Opt out: Set DISABLE_TELEMETRY=1
- A package download request for modern-web-guidance@latest → The npm registry, Each npx call that is not served from the npm cache. Opt out: Use npx --offline (works only with a cached copy)

## Lines in the pack aimed at agents (ask the person first)
- "MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip" (skills/modern-web-guidance/SKILL.md): Wide self-trigger: it fires on nearly any front-end task; the person may prefer to call it only when wanted
- "npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_11_09-5bcc021b" (skills/modern-web-guidance/SKILL.md): Runs the latest npm release with -y (no prompt) on every lookup; ask the person before allowing it, or pin a version
- "proactively request approval/allowlisting with network access BEFORE the first execution" (skills/modern-web-guidance/SKILL.md): Network allowlisting is the person's decision; explain what the command downloads and that it sends telemetry
- "Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project." (skills/modern-web-guidance/SKILL.md): The project's own rules and the person's instructions still come first
- "Every time you touch a Chrome extension project in a way that affects its store presence," (skills/chrome-extensions/SKILL.md): Creates or edits CHROMEWEBSTORE.md in the project root without being asked; tell the person

## May I use it like this?
- commercial-app: yes (Apache 2.0 for code; guide content CC BY 4.0. Code you write with its help is yours)
- redistribute-files: conditions (Keep the Apache 2.0 license; credit the guides (CC BY 4.0); parts derive from MDN and W3C, WHATWG and IETF specs)
- client-work: yes (Apache 2.0 and CC BY 4.0 allow it)

## Which one to pick
- If You want current browser APIs, layout, forms, security and accessibility guidance looked up per task, plus Chrome extension help: skill:GoogleChrome/modern-web-guidance
- If You want skills focused on Lighthouse scores and Core Web Vitals: skill:addyosmani/web-quality-skills
- If You want ready JavaScript snippets your agent runs to measure and debug page speed: skill:nucliweb/webperf-snippets
- If You want a design review of UI code for accessibility and visual issues: skill:rams-design/rams-plugin

## Works well with
- tool:lighthouse: Measures the page speed, accessibility and best-practice results the guides aim to improve
- tool:baseline-browser-mapping: Maps browser versions to Baseline, the support level the skill uses to decide on fallbacks
- agent:claude-code: Installs as a Claude Code plugin from the repository's marketplace
- agent:openai-codex: Installs as a Codex plugin with the same skills

## Works in and needs
- Works in Claude Code: plugin
- Works in Codex: plugin
- Works in GitHub Copilot CLI: plugin
- Works in Cursor: plugin
- Works in Gemini CLI: extension with a shell policy
- Works in Google Antigravity: plugin
- Works in Grok Build CLI: plugin
- Works in Kimi Code: plugin
- Works in VS Code: extension (chat skills)
- Works in Any agent with a skills folder: skills CLI
- Needs Node.js 22+ with npx (or pnpx): Every search and retrieve runs the modern-web-guidance npm package
- Needs Network access to npm: npx fetches the package; sandboxes need network allowlisting

## How to tell it works
Install it, then ask your assistant for a pop-up dialog that closes when you click outside it. Before writing code it runs a modern-web-guidance search, and its answer ends with a "Modern Web Guidance" section naming the guide it used. That section is how you know the skill is on.

## Related
- GoogleChrome/modern-web-guidance-src

## Safety
The skill runs the latest npm release of modern-web-guidance on every lookup, so the code that runs can change without a change in this repository. The tool's source lives in GoogleChrome/modern-web-guidance-src.
