企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

在 GSD-2（gsd-2）这个面向长时自治的元提示（meta-prompting）、上下文工程与规格驱动开发系统中，代码审查类工作被拆解为一系列可插拔的"技能"（Skills）。其中，web-design-guidelines 是一个专注于 Web 界面规范合规审查的内置技能：当 Agent 被要求"review my UI""check accessibility""audit design""review UX""check my site against best practices"时，它会拉取最新版 Web Interface Guidelines，按规则逐条核对指定文件，并以file:line的简洁格式输出审查结论。读完本文，你将掌握该技能的工作流程、触发机制、frontmatter 结构，以及它在 GSD-2 技能解析与发现体系中的底层实现。

技能定位：UI 合规审查的标准作业程序

web-design-guidelines不是一套固定的审查规则，而是一套**"先取规则、再审代码、再给结论"的审查协议**。它的核心设计在于：审查依据不是硬编码在技能文件里的旧清单，而是每次审查前从最新来源拉取，从而避免规则过期。

该技能的 frontmatter 定义了 Agent 如何识别与使用它：

--- name: web-design-guidelines description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". metadata: author: vercel version: "1.0.0" argument-hint: <file-or-pattern> ---

其中argument-hint: <file-or-pattern>明确告诉调用方：该技能需要一个文件路径或 glob 模式作为入参；metadata.author: vercel与metadata.version则标注了规则体系的来源与版本基线。这种 frontmatter 结构是 GSD-2 全部技能的通用约定，skill-discovery.ts 中的parseSkillFrontmatter会读取name与description字段来生成技能元数据，因此 description 中列出触发短语（"review my UI""check accessibility"等）是技能被正确激活的关键。

工作流程：取规则 → 读文件 → 逐条核对 → 输出 file:line

技能正文给出了四步标准作业程序（SOP）：

1. 从下面的来源 URL 拉取最新版 Guidelines；
2. 读取用户指定的文件（若未指定，则向用户询问文件或模式）；
3. 用拉取到的全部规则逐条核对目标文件；
4. 以简洁的file:line格式输出审查发现。

关键的规则来源：

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

技能明确要求：每次审查前都要先获取最新规则，并使用 WebFetch 工具检索，因为"fetched content contains all the rules and output format instructions"——即规则全集与输出格式说明都随每次拉取动态更新，技能文件本身不保存规则副本。这意味着该技能天然具备"规则保鲜"能力：当上游 Guidelines 新增规则或调整输出格式时，技能无需修改即可自动跟随。

使用方式：带参调用与无参回退

技能定义了两种调用形态：

• 用户提供文件或模式参数时：依次执行"拉取规则 → 读取指定文件 → 应用全部规则 → 按规则要求格式输出"。
• 未指定文件时：不强行猜测，而是向用户询问要审查哪些文件（"If no files specified, ask the user which files to review"）。

这种"先澄清入参、再执行审查"的交互设计，与该技能在 GSD-2 系统中的激活触发词共同保证了它只在 UI 审查语境下被唤起，避免误用。

注册与触发：系统上下文中的技能路由

该技能被注册在 GSD-2 的系统上下文触发器表中。system-context.ts 中维护了一个BUNDLED_SKILL_TRIGGERS数组，其中对应条目为：

{ trigger: "Review UI code for Web Interface Guidelines compliance — UX, design, and accessibility patterns", skill: "web-design-guidelines" }

buildBundledSkillsTable()会遍历该数组，用resolveSkillReference将技能名解析为绝对路径，并把"触发器 → 技能路径"对照表注入系统提示词；若技能未安装（解析结果为unresolved）则该行被跳过。

这条注册关系还受到回归测试的保护：bundled-skill-triggers.test.ts 断言web-design-guidelines必须出现在BUNDLED_SKILL_TRIGGERS中（归属于 PR #5060 引入的"之前未暴露的技能"批次），同时断言每个触发器条目都非空、技能 ID 全局唯一。这套测试保证了技能路由表不会在后续改动中静默退化。

源码视角：技能如何被发现、解析与加载

要理解web-design-guidelines在运行时的完整生命周期，需要看 GSD-2 的技能基础设施：

技能目录与解析优先级

preferences-skills.ts 中的getSkillSearchDirs定义了技能查找目录，按优先级排列：

解析规则（resolveSkillReference）依次支持：绝对文件路径 → 绝对目录（内部查找SKILL.md）→ 裸技能名（在已知目录中扫描<name>/SKILL.md）。技能文件被约定命名为SKILL.md，这正是 web-design-guidelines/SKILL.md 的落盘位置。

技能发现与上下文注入

skill-discovery.ts 负责在 auto-mode 会话中发现新安装的技能：它在会话开始时对技能目录做快照（snapshotSkills），随后用detectNewSkills比对差异，解析新技能 frontmatter 中的name/description，最后通过formatSkillsXml生成<newly_discovered_skills>XML 块注入系统提示词，使后续单元能直接read加载匹配的技能文件。这套机制与本文主题的直接关联是：web-design-guidelines的 description 字段质量直接决定了它能否在新技能发现、偏好匹配中被正确选中。

偏好配置：用 always/prefer/avoid 控制审查技能的选用

GSD-2 允许通过偏好配置精准控制技能选用，详见 docs/user-docs/skills.md：

--- version: 1 always_use_skills: - web-design-guidelines prefer_skills: - frontend-design avoid_skills: - some-other-skill skill_rules: - when: frontend styling work prefer: [frontend-design] ---

• always_use_skills：无条件加载的技能；
• prefer_skills：优先倾向使用的技能；
• avoid_skills：明确回避的技能；
• skill_rules：按任务条件动态路由到特定技能。

此外，skill_discovery偏好控制技能的自动发现方式：auto（自动发现并应用）、suggest（识别但需确认，默认）、off（关闭）。如果希望 UI 审查流程完全自动化，可将其设为auto；若希望保持人对技能使用的控制权，保留suggest即可。

与相邻技能的分工

web-design-guidelines在 GSD-2 的 UI 审查能力矩阵中并非孤军作战，docs/dev/FILE-SYSTEM-MAP.md 列出了完整的技能清单，与其相邻的技能各有侧重：

其中userinterface-wiki与web-design-guidelines构成"规则百科 + 外部规范"互补：前者提供可检索的分类规则（155 个文件规模的参考库），后者则每次动态拉取外部最新规范。二者都遵循file:line输出约定，便于后续修复直接定位到行。

实践建议：把 UI 审查固化到工作流中

综合来看，在 GSD-2 中落地 UI 合规审查的推荐路径是：

1. 确认技能已安装：技能目录采用 Agent Skills 开放标准（SKILL.md格式），可通过npx skills add安装到~/.agents/skills/；也可直接在项目.agents/skills/下放置SKILL.md实现项目级共享（可提交版本库）。
2. 显式调用或靠触发词唤起：直接要求"review my UI / check accessibility / audit design / review UX"，或在 auto-mode 下启用skill_discovery: auto让系统按任务自动匹配。
3. 每次审查前先获取最新规则：技能会通过 WebFetch 拉取最新版 Web Interface Guidelines，确保审查依据不过期。
4. 以file:line为准输出：所有发现都落在具体文件行上，并遵守当次拉取内容中规定的输出格式。

这套机制的核心价值在于"审查标准与代码审查解耦"：规则集可以独立演进（由上游维护），而 GSD-2 侧的技能只需稳定维护"拉取—比对—定位"这条链路，即可持续产出有行号定位的、可执行的 UI 合规审查结果。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用