While Modern Web Guidance aims to move your development toward a "correct-by-default" approach, you may occasionally encounter issues with agent activation, implementation accuracy, or feature discovery. This section provides diagnostic steps to help you resolve common challenges, such as ensuring the Modern Web skill is properly triggered by your prompts or verifying that code fallbacks align with your project's established Baseline status. If you encounter persistent technical hurdles or identify outdated guidance, we encourage you to file an issue to help us keep these resources accurate and effective.
Diagnose Modern Web Skill not being picked up by agent
Any prompt that has installed the skill extension should be able to activate it by including using "modern web guidance" in some way, but if for some reason the agent you are using is having difficulty, you can directly call it like so:
/modern-web-guidance <your prompt>
This is applicable to AI-powered IDEs that accept npx skills add <skill-extension>.
Diagnose "hallucinated" code or guessed implementations
This is a common occurrence where the LLM model would fill in the knowledge gaps without warning. To prevent the agent from inventing information, we have found that appending the following instruction to your prompts is very helpful
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Diagnose failure to trigger specific guidance
If you are targeting a specific feature use case and you are not seeing it being discovered by the agent, ensure that your prompts include specific keywords and anchor requirements for proper discoverability. It helps the agent to identify the relevant guidance track (for example: "view transitions", "LCP optimization").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Track the agent's thought process:
- Follow if it discovered Modern Web Guidance skill (for example,
modern-web/SKILL.md). - Locate the search call—for example,
node modern-web.mjs search "scroll snap"—and identify if the keywords and resulting guides were the ones you expected. The top most guide from the search results is the one chosen to be applied for your prompt.
/modern-web-guidance Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(node --experimental-strip-types serving/bin/modern-web.ts search "carousel scroll-snap")
⎿ [{"id":"carousel-item-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"]},
{"id":"light-dismiss-content-overlay","description":"Create swipeable layered navigation menus using native overlays and scroll gestures.","category":"user-experience","featuresUsed":["Popover","Scroll snap","inert"]},
{"id":"scroll-target-on-load","description":"Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.","category":"user-experience","featuresUsed":["scroll-initial-target","scrollIntoView()"]},
{"id":"parallax-scroll-effects","description":"Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense
of depth as the user scrolls.","category":"user-experience","featuresUsed":["Scroll-driven animations"]},
{"id":"pull-to-reveal","description":"Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.", "category":"user-experience","featuresUsed":["scroll-initial-target","Scroll snap"]}]
...
▾ Thought for 1s
Ah, let's look at the actual folder names under `guides/user-experience/` that we listed earlier to find the exact ID mapping.
Let's see the folders we found earlier:
- `carousel-slide-effects`
- `carousel-snap-highlights`
- `scroll-snap-realtime-feedback`
- `scroll-snap-state-sync`
Ah! The ID in the filesystem is `carousel-slide-effects`, while the search index returns `carousel-item-effects`.
- Execute the search command for relevant guides yourself:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnose missing fallbacks for certain web browser features
This relies on the Baseline status that you have set within your project. If the API was very recently release, the agent might not have an equivalent fallback to rely on, or it is a feature that has been "Baseline Widely" available for a long enough time that fallbacks or polyfills may not be necessary.
Diagnose outdated training data bias
If the agent suggests an older library instead of a modern browser API, it is likely either relying on its base training data or your Baseline status is configured to not yet support that feature and the fallback was implemented.
To double-check, you can force the skill to take precedence by explicitly searching the guidance library using the CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnose outdated guidance
It is of utmost importance that our information is up-to-date, so we would kindly ask that you file an issue with the repository if you find code that was implemented from a guide was out-of-date. When dooing so, gather evidence that the agent is recommending to you is from the modern-web skill and its guides rather than the base training data from the LLM model your AI- powered IDE may be using.
In your agent window or terminal, you may be able to track its thinking, but you can also ask for it to inform you how it came to the code change conclusion. Once you have come to the conclusion that it is indeed from the skill, pass that feedback and evidence to us.
Feedback
If you have any additional questions or feedback on these new features, first read about how to contribute to Modern Web Guidance before filing an issue in our Github repository. While creating the issue, provide the initial agent prompts, screenshots and logs of the agent thinking process, and the final code change recommended based on that agent thinking.