本机执行方式(DSH 接线, 本地补丁)
- 安装位置: DSH 没有官方 install 目标(官方 install 委托第三方 skills CLI, 只有 claude/codex/cursor/gemini/kimi/copilot 宿主)。本 skill 直接放在
~/.agents/skills/modern-web-guidance/,由dsh-skill-filesystem插件扫描热加载,无需注册。 - telemetry 默认是开的(实测): CLI 默认起 detached
watchdog/main.js子进程,把查询词、命中 id、OS、agent 名上报 Google Clearcut。本机一律加DISABLE_TELEMETRY=1,检索结果完全不受影响。 - 命令优先用本地副本(0.2 s 级, 检索索引在本地
gen/, 不依赖网络):DISABLE_TELEMETRY=1 node ~/.agents/skills/modern-web-guidance/modern-web.mjs search "<query>" DISABLE_TELEMETRY=1 node ~/.agents/skills/modern-web-guidance/modern-web.mjs retrieve "<id>" DISABLE_TELEMETRY=1 node ~/.agents/skills/modern-web-guidance/legacy-scan.mjs <path> --json - 本地执行不通(文件缺失/报错)时才退回官方写法(首次需联网):
DISABLE_TELEMETRY=1 npx -y modern-web-guidance@latest <cmd>。 - 查询词用英文: 索引只有英文, 中文查询返回
[]。 - 边界裁定: 纯内容排版 / 文案搬运 / 中文长文页面(不新增或改动交互逻辑与 CSS 布局机制)不强制跑 search; 一旦涉及交互组件(dialog / popover / 表单 / 动画 / view transitions / 容器查询 / a11y / 性能),先 search 再写。
- 升级: 跑
~/.agents/scripts/update-mwg.sh(默认 dry-run, 加--apply才覆盖; 会重建本段与精简后的 frontmatter description)。
Modern Web Guidance
Search and retrieve standardized modern web best practices at the start of implementing or updating any web UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility, UX fixes) before writing ad-hoc solutions or adding dependencies.
Primary Workflow
Step 1. Search Use Cases
Run modern-web-guidance directly with npx using a 2–5 word action-oriented query for a single web platform capability or UI pattern:
- Keep queries focused and generic: Describe the user-visible capability (
<verb> + <UI/platform object>, optionally paired with the target HTML/CSS/JS feature name if known). Omit framework/library names (React,Vue,Tailwind, etc.) and app/domain nouns (product, route, or component/file names). Split multi-feature tasks into separatesearchcalls. - Name implied UI primitives: When the user's prompt expresses intent without naming the UI primitive (e.g. "confirm first", "delete with confirmation", "pick a date"), translate the domain intent into the implied UI component or platform mechanism (e.g. search
"confirmation modal dialog"or"confirm dialog"rather than"confirm destructive action", or"date picker input"rather than"pick a date"). - Example: Search
"light dismiss dialog"or"responsive data table", not"dialog"(too terse),"responsive table dark mode"(compound — split into two searches), or"close React settings modal on outside click"(framework/app noise).
npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_11_09-5bcc021b
Note: Returns
[{ "id", "description" }, ...]. Judge results by theirdescriptionfields:
- Match found: Call
retrievedirectly—do not also runlist.- Weak or empty results: If
searchreturns[]or unrelated descriptions, rephrasesearchonce using the concrete HTML/CSS/UI component noun or synonym (e.g.,dialog,modal,popover,table,form) before falling back tolist(or uselistonce for broad UI audits).- Topic not covered: If no
descriptionmatches after rephrasing, proceed without retrieving unrelated guides.
Step 2. Retrieve Best Practices
Once you have relevant id(s) from the search results, call retrieve to get the full guide(s)—including both specific use-case guides that match your task and any broader discipline guide (e.g., html, css, forms, accessibility, color, performance, security) that applies. You can pass multiple IDs separated by commas.
npx -y modern-web-guidance@latest retrieve "<id>"
If retrieve saves large output (> 9.5 KB) to a temporary file to prevent truncation, read that file path in full using your file-reading tool (reading remaining line ranges if needed)—do not use cat or head.
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.
- Do not run
legacy-scan; it's for detecting legacy patterns to modernize, not this.
Step 4. Disclose Skill Usage
When you consult modern-web-guidance for a task, end the response where you deliver those changes with a ### Modern Web Guidance section:
- When retrieved guides shaped your code: Write one bullet (1–2 sentences, ≤75 words) per newly applied
<id>in first-person voice explaining the non-obvious implementation choices, CSS/API overrides, or fallbacks<id>required and the pitfall it prevented, anchored by a short verbatim quote of that specific rule or gotcha (never the guide's intro overview):- **\`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("").`- Never guess
<id>s or quotes from memory after context compaction (re-runsearch/retrieveif needed), and credit only guide-backed changes from the current turn.
- Never guess
- When searched/listed in this turn but zero guides applied: Write one first-person sentence naming which topics or guides you checked in
modern-web-guidanceand why none applied (omit if any guide applied).
Alternative flow: Modernize an existing codebase
Only when asked for a broad, open-ended codebase modernization or legacy-pattern scan where no specific target feature or component is named (do not run legacy-scan when asked to add, update, fix, or audit a specific feature or component), run the 4-step modernization flow:
Note:
legacy-scanscans for a curated subset (~20% of the guidance corpus).
npx -y modern-web-guidance@latest legacy-scan <path> --json
- Scan: Run
legacy-scan <path> --jsonto detect legacy web platform patterns across the project or directory. - Verify: Check each finding against its
keepWhen/dropWhenrubric; drop false positives (fallbacks, cross-file helpers, vendor code, lookalikes). - Report: Summarize verified findings (and the modernization plan, if editing) for the user, noting that
legacy-scanonly checks the subset of guides (~20% of the catalog) that have deterministic legacy rules. - Modernize (when the user asked to modernize rather than only audit/report): Retrieve each finding's guide (
retrieve "<guide-id>"via Step 2), apply the replacement (keeping existing libraries as fallbacks where the guide requires one), and re-runlegacy-scan <path>on the modified files to confirm resolution.- Dropped findings and kept fallbacks still match static scans; do not edit safe code or inspect
legacy-scan.mjsto force 0 findings.
- Dropped findings and kept fallbacks still match static scans; do not edit safe code or inspect
Using npx / pnpx
- Runner & Permissions: Prefer
pnpxovernpxifpnpmis available (pnpxdoes not use-y); on Windows, usenpx.cmd. When requesting tool permissions, allowlistnpx -y modern-web-guidance@latest *(orpnpx modern-web-guidance@latest *) specifically, never barenpx *orpnpx *. - Sandboxes & Network: Fetching
modern-web-guidancerequires outbound network access. In sandboxed or approval-gated environments (e.g., Codex, Claude Code), proactively request approval/allowlisting with network access BEFORE the first execution to avoid timeouts, and setNPM_CONFIG_CACHE=/tmp/npm-cacheif~/.npmis read-only. - Offline: If the command hangs due to being offline, retry with
npx --offline ….
Guidelines
- Always search first to find the most relevant guides. Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.
- These guides use vanilla HTML/CSS/JS; adapt them to your framework without dropping the modern feature:
- Types: Spread/cast newly shipped HTML attributes (
{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)},[attr.*]) rather than removing them or merging@types/react. - SSR & Bundlers: Guard
window/HTMLElementin SSR and load polyfills via bareimport('<pkg>')in client effects (or set Vitebuild.target: 'esnext'for top-levelawait)—never copy files fromnode_modules. - DOM, IDs & CSS: Call
showModal()/moveBefore()via refs on non-VDOM-managed nodes, generate per-instance IDs/anchor-names (useId()), and keep:rootand@starting-styletop-level/unscoped.
- Types: Spread/cast newly shipped HTML attributes (
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 defines explicit browser support requirements, use the guide's compatibility data to determine if a fallback can be ignored (for
Baseline YYYYtargets, a feature satisfies the target if its "Baseline since" date is<= YYYY). Examples: "Do not implement feature fallbacks", "Safari 17.4+", "Never implement polyfills; use a lightweight custom fallback or redesign", or "Allow Newly Available features if feature-detected with graceful degradation". - Reactive Policy Discovery: Suggest documenting a policy in
AGENTS.mdorCLAUDE.md(e.g.,**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and no external dependencies) if the developer targets a restricted runtime (Electron/Tauri), excludes specific browsers, hesitates over polyfill size/complexity, or asks if a feature is safe without fallbacks.