modern-web-guidance

Modern Web Guidance

一個用於搜尋特定網頁開發使用案例並取得對應最佳實務指南的技能。

使用時機

必須使用此技能：

• 在開始實作任何網頁功能時。
• 在建立新元件之前，檢查是否有標準化模式已存在。
• 避免不必要地實作臨時解決方案或載入大型相依套件。

使用說明

步驟 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>"

範例輸出：
The markdown content of the guide describing implementation steps...

使用 npx

• 重要：在 Windows 上，使用 npx 可能會失敗。請改用 npx.cmd ...。
• 需要網路存取以取得任務所需的 npm 套件。
• 如果 npx -y modern-web-guidance… 指令卡住，你可能處於離線狀態。請嘗試以離線模式重新執行：npx --offline …。
• --skill-version 旗標用於判斷此 SKILL.md 是否過期。如果過期，會將警告訊息記錄到 stderr。

指南

• 務必先搜尋以找到最相關的指南。
• 這些指南通常與框架無關；請根據你的設定正確調整。
• 不要憑空想像指南或忽略它們；它們代表使用者專案偏好的本機標準。

解讀瀏覽器支援與降級方案

• 預設行為：所有指南假設 Baseline Widely available 功能可安全使用，無需降級方案。對於非 Baseline Widely available 的功能，你必須遵循指南中的降級建議，除非使用者已指定自訂的瀏覽器支援政策。

• 自訂政策：如果使用者已定義明確的瀏覽器支援需求，請使用指南中的瀏覽器相容性資料判斷是否可以安全忽略降級方案。

  • 對於 Baseline YYYY 目標，若功能的「Baseline since」日期 <= YYYY，則該功能符合此目標。
  • 政策範例：
    • "不要實作功能降級方案。"（適用於尖端網頁的探索性原型）
    • "Safari 17.4+"（適用於針對 macOS 或 Tauri 桌面應用程式的內部工具）
    • "永遠不要建議或實作 polyfill；如果 Baseline Newly Available 功能是核心功能所需，請提供輕量級自訂降級方案或重新設計方法。"（以最小化套件大小並避免技術債）
    • "假設現代執行環境，Baseline Newly Available 功能可在嚴格功能偵測且優雅降級的前提下原生使用。"（適用於漸進增強策略）

• 反應式政策發現：留意環境線索，建議在 CLAUDE.md 或 AGENTS.md 中記錄政策。在以下情況建議：

  • 開發者提到為受限執行環境（例如 Electron 或 Tauri）建置。
  • 明確排除特定目標（例如「我們不支援桌面版 Chrome」）。
  • 對 polyfill 複雜度、套件大小或效能成本表示猶豫。
  • 質疑某功能是否可安全使用而無需降級方案。

  沒有定義的政策格式。以下是一個範例：**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.