modern-web-guidance

Modern Web Guidance

用于检索特定 Web 开发场景并获取对应最佳实践指南的 Skill。

何时使用

出现以下情况必须使用本 Skill：

• 在开始实现任何 Web 功能时。
• 在创建新组件之前，检查是否已存在标准化模式。
• 避免实现临时凑合的替代方案，或无谓地引入大型第三方依赖。

使用说明

步骤 1. 搜索使用场景

使用 search 命令，通过总结你想要实现的目标（以动作导向的查询）进行搜索。直接使用 npx 运行 modern-web-guidance。

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_05_16-c5e78707

输出示例：

[
  {
    "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
  }
]

注意：如果搜索结果过于宽泛、未匹配到任何结果，或者相似度得分较低，可运行 list 命令浏览所有指南：

npx -y modern-web-guidance@latest list

---

步骤 2. 获取最佳实践指南

从搜索结果中获取相关的 id 后，使用 retrieve 命令调用此脚本以获取完整的指南。你可以传入多个以逗号分隔的 ID。

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

输出示例：
包含具体实现步骤的指南 Markdown 内容...

使用 npx 的注意事项

• 重要提示：在 Windows 环境下使用 npx 可能会失败，请改用 npx.cmd ...。
• 获取任务所需的 npm 包需要访问网络。
• 如果 npx -y modern-web-guidance… 命令卡住无响应，可能是网络离线。请尝试在离线模式下再次运行：npx --offline …。
• --skill-version 参数用于判断当前的 SKILL.md 是否已过期。如果已过期，会在 stderr（标准错误输出）中打印一条警告信息。

使用规范

• 务必优先进行搜索，找到关联度最高的指南。
• 这些指南通常与具体框架无关；请根据你的技术栈妥善适配。
• 切勿凭空编造指南或忽略它们；它们代表了当前项目所推荐的本地标准。

浏览器兼容性与降级方案解读

• 默认行为：所有指南均默认达到 Baseline Widely available（ Baseline 广泛可用） 标准的特性均可安全使用，无需编写降级（fallback）代码。对于尚未达到 Baseline 广泛可用级别的特性，除非用户明确指定了自定义的浏览器兼容策略，否则必须遵循指南中的降级建议。

• 自定义策略：如果用户已明确定义了具体的浏览器兼容要求，请结合指南中的浏览器兼容性数据，判定是否可以安全地忽略降级代码。

  • 对于 Baseline YYYY 目标，若某特性的“Baseline since”日期早于或等于 YYYY，则该特性满足该目标。
  • 策略示例：
    • "无需编写特性降级方案。"（适用于针对前沿 Web 特性的探索性原型开发）
    • "Safari 17.4+"（适用于针对 macOS 或基于 Tauri 开发的桌面端内部工具）
    • "绝不推荐或实现 Polyfill；若核心功能需要 Baseline Newly Available（ Baseline 最新可用）特性，请提供轻量级的自定义降级代码或重新设计方案。"（以最小化打包体积并避免技术债务）
    • "假设在一个现代执行环境中，只要严格进行特性检测（feature-detection）并实现优雅降级（degrade gracefully），即可原生使用 Baseline Newly Available 特性。"（适用于渐进增强策略）

• 响应式策略发现：注意观察环境线索，若开发人员出现以下行为，建议提议将相关策略记录在 CLAUDE.md 或 AGENTS.md 中：

  • 提到正在为受限的运行时环境（如 Electron 或 Tauri）开发。
  • 明确排除某些特定的目标平台（例如“我们不支持 Desktop Chrome”）。
  • 对 Polyfill 的复杂性、打包体积或性能成本表达了顾虑。
  • 询问某项特性在不加降级方案的情况下是否可以安全使用。

  无固定格式要求。示例如下：**Browser Support:** 允许使用 Newly Available 特性，但仅接受新增代码 <= 20 行且无需引入额外依赖的自定义降级代码。