browser-compatibility-review

Browser Compatibility Review

Purpose

"Works on my browser" is not a compatibility strategy. This skill checks used web-platform features against the org's actual declared supported-browser matrix (Browserslist config or an explicit browser-version list) using Baseline/caniuse status, and verifies that any feature outside "widely available" has a real feature-detection or polyfill fallback rather than a silent failure.

When to use

Use this skill when the user asks to:

• review a PR using a new JS API, CSS feature, or HTML element for cross-browser risk,
• audit the overall Baseline-status distribution of features used in a codebase,
• decide whether a feature needs a polyfill, feature-detection gate, or is safe to use unguarded,
• propose narrowing or widening the org's supported-browser matrix,
• triage a browser-specific bug report.

Context7 Documentation Protocol

Baseline status, caniuse support tables, and Browserslist/tooling behavior change on their own release cadences, independent of this skill's version — never assert a feature's Baseline tier, a browser's support version, or a config-syntax detail from memory.

1. Call ToolSearch with query "context7" (or "select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs") to load the Context7 tools if not already loaded in this session.
2. Call mcp__Context7__resolve-library-id for web-features (prefer /web-platform-dx/web-features) when grounding a Baseline-status claim (widely/newly/limited availability, baseline_low_date/baseline_high_date semantics) — do not paraphrase Baseline's tiering from memory.
3. Call mcp__Context7__query-docs for the specific feature or mechanism in question — e.g. "compute Baseline status for a compat key", "getStatus for a web-features id" — before stating a feature's tier as fact. Do this per review, not once from a prior session's memory.
4. For the exact per-feature per-browser support matrix (which browser version added support), prefer live lookups against https://caniuse.com/ and MDN's browser-compatibility tables in official_docs over Context7 paraphrase — Context7's web-features package computes Baseline tiers from that same underlying data but is not the source of truth for a single browser-version cell.
5. Browserslist's own config syntax and query semantics are not consistently resolvable in Context7 (verified: no dedicated browserslist library was found when this skill was authored) — treat any Browserslist query-syntax claim as documentation-based (Context7 unavailable for this library) and confirm it against the project's actual .browserslistrc / package.json browserslist key and the official browserslist/browserslist GitHub README rather than inventing query syntax.
6. If Context7 returns no relevant match for a claim, fall back to the official_docs URLs and mark the claim documentation-based (Context7 unavailable) instead of presenting it as freshly verified.
7. Never invent a Baseline tier, a caniuse support percentage, or a Browserslist query keyword that no queried source confirms.

Lean operating rules

• Always check the feature against the project's actual declared Browserslist config or explicit browser-version list — never approve based on the reviewer's own current browser, and never assume a default matrix (e.g. > 0.5%, last 2 versions, Firefox ESR, not dead) applies without reading the project's own config.
• Distinguish Baseline "Newly available" (recently reached cross-engine support, but by definition still excludes older browsers within the ~2.5-year newly-to-widely window) from "Widely available" (safe to use unguarded for most matrices) from "Limited availability" (requires a fallback). Treat these as the three tiers computed from baseline_low_date / baseline_high_date, not as marketing labels.
• For any Limited-Availability feature, or a Newly-Available feature whose window excludes a browser/version actually in the project's matrix, verify a real @supports/feature-detection/polyfill exists and correctly gates the risky code path — do not accept an assertion that a fallback "exists" without reading the code that implements it.
• Weigh polyfill bundle-size cost against the actual percentage of affected users (from real analytics/RUM data if available) rather than blanket-recommending every polyfill; a polyfill added for a browser with near-zero real traffic is often a worse tradeoff than accepting the gap.
• Treat any hard failure (thrown exception, blank render, broken checkout) as strictly higher severity than cosmetic degradation (missing rounded corners, no animation), and prioritize findings accordingly.
• Recommend supported-browser-matrix changes only as data-backed proposals to product/analytics owners — this skill does not unilaterally decide the org's matrix, it surfaces the gap and the tradeoff.
• Never recommend disabling a security-relevant browser default (mixed-content blocking, SameSite cookie defaults, CSP enforcement, Permissions Policy) as a "compatibility workaround" — that is a security regression, not a fix, and must be flagged as such if proposed by the user.
• Load reference files only for the review question actually in scope (single-feature triage vs full-codebase Baseline sweep vs matrix-change proposal); do not preload the full feature catalog for a one-feature check.

References

Load these only when needed:

• Baseline status model — use when determining or explaining the exact Baseline tier (widely/newly/limited) of a specific feature and what that tier does and does not guarantee for the project's matrix.
• Fallback verification patterns — use when a finding requires checking whether an actual feature-detection gate or polyfill exists and correctly covers the risky code path, across JS, CSS, and HTML.
• Browserslist matrix interpretation — use when reading, interpreting, or proposing a change to the project's .browserslistrc/browserslist config, or reconciling it with build-tool (Autoprefixer/Babel/postcss-preset-env) targets.

Response minimum

Return, at minimum:

• the feature(s) in scope and their exact Baseline status (widely / newly / limited, with the underlying date window if newly available),
• the specific browsers in the org's declared matrix that lack support, if any, cited against the project's actual Browserslist/matrix config,
• current fallback status (none / feature-detected / polyfilled) with the actual code shown, not an assertion,
• severity distinction between hard failure and cosmetic degradation,
• polyfill cost-vs-affected-user tradeoff note if a polyfill is recommended,
• evidence label for every claim (live evidence from project config/code, documentation-based, or inference), and an explicit note when Context7 was unavailable for a cited claim.