Modern Web Guidance

Modern Web Guidance

A skill to search for specific web development use cases and retrieve their corresponding best practice guides.

When to use

Must use this skill:

• At the start of implementing any web feature.
• Before creating a new component, to check if a standardized pattern already exists.
• To avoid implementing ad-hoc solutions or loading large dependencies unnecessarily.

Usage Instructions

Step 1. Search Use Cases

Search with an action-oriented query summarizing what you want to achieve using the search command. Run modern-web-guidance directly with npx.

shCopy code
npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_09_04-7de96777

Example Output:

jsonCopy code
[
  {
    "id": "optimize-image-priority",
    "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.",
    "category": "performance",
    "featuresUsed": [ "Fetch priority" ],
    "tokenCount": 985,
    "similarity": 0.7289
  },
  {
    "id": "defer-rendering-heavy-content",
    "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.",
    "category": "performance",
    "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ],
    "tokenCount": 1250,
    "similarity": 0.6961
  }
]

Note: If search results are vague, return no matches, or show low similarity scores, run the list command to browse all guides:

shCopy code
npx -y modern-web-guidance@latest list

Step 2. Retrieve Best Practices

Once you have a relevant id from the search results, call this script using the retrieve command to get the full guide. You can pass multiple IDs separated by commas.

shCopy code
npx -y modern-web-guidance@latest retrieve "<id>"

If the output is truncated, you must repeat the command but redirect to a file and read that file.

Example Output: The markdown content of the guide describing implementation steps...

Step 3. Verify Guidance Compliance

When generating or modifying code, cross-check the implementation against the retrieved guide before concluding:

• Applicable Guidance & Fallbacks: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly applied, without forcing unrequested features.
• Task Fulfillment: Confirm that the implementation fully satisfies the user's request.

Using npx / pnpx

• Prefer pnpx over npx if pnpm is available (note: pnpx does not use the -y flag).
• When requesting tool permissions, allowlist npx -y modern-web-guidance@latest * specifically (or pnpx modern-web-guidance@latest *), never bare npx * or pnpx *.
• IMPORTANT: on Windows, using npx may fail. Use npx.cmd ... instead.
• Fetching and running modern-web-guidance requires outbound network access. If running in a sandboxed, permission-gated, or approval-based environment (e.g., Codex, Claude Code), proactively request approval/allowlisting for the command with network access BEFORE executing it the first time, avoiding sandbox network timeouts.
• In sandboxed environments where ~/.npm is read-only or restricted, set NPM_CONFIG_CACHE=/tmp/npm-cache.
• If the command hangs due to being offline, try running again in offline mode: npx --offline ….
• The --skill-version flag is used to determine if this SKILL.md is out of date. If it is, a warning message is logged to stderr.

Guidelines

• Always search first to find the most relevant guides.
• These guides are usually framework-agnostic; adapt them correctly to your setup.
• Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.

Interpreting Browser Support & Fallbacks

• Default Behavior: All guides assume Baseline Widely available features are safe to use without fallbacks. For features that are not Baseline widely available, you MUST follow the fallback recommendations in the guide, unless the user has specified a custom browser support policy.

• Custom Policies: If the user has already defined explicit browser support requirements, use the browser compatibility data in the guide to determine if a fallback can be safely ignored.

  • For Baseline YYYY targets, a feature satisfies this target if its "Baseline since" date is <= YYYY.
  • Policy Examples:
    • "Do not implement feature fallbacks." (for exploratory prototypes of the cutting-edge web)
    • "Safari 17.4+" (for internal tools targeting macOS or Tauri-based desktop apps)
    • "Never recommend or implement polyfills; if a Baseline Newly Available feature is required for core functionality, provide a lightweight custom fallback or redesign the approach." (to minimize bundle size and avoid technical debt)
    • "Assume a modern execution environment where Baseline Newly Available features can be used natively, provided they are strictly feature-detected and degrade gracefully." (for progressive enhancement strategies)

• Reactive Policy Discovery: Watch for environmental cues to suggest documenting a policy in CLAUDE.md or AGENTS.md. Suggest this if the developer:

  • Mentions building for a restricted runtime (e.g., Electron or Tauri).
  • Explicitly excludes specific targets (e.g., "we don't support Desktop Chrome").
  • Expresses hesitation about polyfill complexity, bundle size, or performance cost.
  • Questions if a feature is safe to use without fallbacks.

  No defined policy format. This is an example: **Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.