前言¶
在 AI 编程工具里让 Agent「画个页面」，你多半拿到过这样的东西：一个几百行的单文件 HTML，样式靠内联 CSS 硬凑，组件一多就乱，状态一复杂就崩。稍微上点强度——多 Tab 切换、表单联动、弹窗抽屉——Agent 往往要么反复改错，要么堆出一坨难以维护的 JSX 字符串。
如果你希望 Agent 按现代前端工程的方式干活，而不是临时拼页面，Anthropic 官方仓库里的 web-artifacts-builder Skill 值得装一份。它把 React 18、TypeScript、Vite、Tailwind CSS、shadcn/ui 和打包脚本打包成一套可重复的工作流：初始化脚手架、正常写组件、最后产出一个自包含的单 HTML 文件，方便在对话里直接预览或分享。
这是什么¶
web-artifacts-builder 是 Anthropic skills 仓库 中的示例 Skill，面向「需要多组件、状态管理或 shadcn/ui 组件库」的复杂 Web 产物，不适用于简单的单文件 HTML/JSX 场景。
官方定位很直白：用一套脚本帮 Agent 搭建完整前端项目，开发完成后打包成 bundle.html，可直接作为 claude.ai 的 Artifact 展示；在 Cursor、Claude Code 等支持 Agent Skills 的工具里，逻辑同样适用。
技术栈（官方 SKILL.md 原文）：
- React 18 + TypeScript + Vite
- Tailwind CSS 3.4.1 + shadcn/ui（预装 40+ 组件）
- Parcel + html-inline（打包为单 HTML）
核心功能与亮点¶
1. 一键初始化现代前端脚手架¶
Skill 自带 scripts/init-artifact.sh，执行后会：
- 用
pnpm create vite创建 React + TypeScript 项目 - 自动检测 Node 版本（要求 Node 18+；Node 18 会 pin Vite 5.4.11，Node 20+ 用最新 Vite）
- 配置 Tailwind CSS、PostCSS、shadcn/ui 主题变量
- 解压预置的
shadcn-components.tar.gz，一次性装入 accordion、dialog、form、table、tabs 等 40+ 组件 - 配置
@/路径别名与 Vite resolve
开发者熟悉的栈，Agent 写起来也有章可循。
2. 单文件 HTML 打包¶
开发完成后运行 scripts/bundle-artifact.sh：
- 用 Parcel 构建（支持路径别名）
- 通过
html-inline把 JS、CSS、依赖全部内联 - 输出根目录下的
bundle.html，体积会随功能增长，但无需额外服务器即可在浏览器打开
3. 明确的设计约束¶
官方在 SKILL.md 里专门提醒：避免「AI slop」式审美——过度居中布局、紫色渐变、统一大圆角、Inter 字体泛滥。这对产出「能看、能用」的界面很有帮助。
4. 与简单 HTML 产物的边界¶
Skill 的 description 写得很清楚：需要状态管理、路由或 shadcn/ui 组件时才启用；单页静态展示用普通 HTML/JSX 更轻。别用大炮打蚊子。
安装与启用¶
Claude Code¶
Anthropic 官方 README 给出的方式：
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
安装 example-skills 插件后，对话里提到相关需求即可触发；也可直接说明「使用 web-artifacts-builder Skill」。
Claude.ai¶
官方说明：仓库中的示例 Skill 已对付费计划开放；自定义 Skill 上传见 Using skills in Claude。
Cursor¶
Cursor 从项目或用户目录自动发现 Skill。把官方目录整份放到：
- 项目级：
.cursor/skills/web-artifacts-builder/ - 全局：
~/.cursor/skills/web-artifacts-builder/
目录内需包含 SKILL.md 以及 scripts/（含 init-artifact.sh、bundle-artifact.sh、shadcn-components.tar.gz）。Agent 会根据 description 自动匹配，或在 Agent 对话里输入 /web-artifacts-builder 手动调用。
克隆方式示例：
git clone --depth 1 https://github.com/anthropics/skills.git /tmp/anthropics-skills
cp -r /tmp/anthropics-skills/skills/web-artifacts-builder .cursor/skills/
环境要求¶
- Node.js 18 及以上（init 脚本会检测并拒绝更低版本）
- pnpm（脚本检测不到时会尝试
npm install -g pnpm）
典型用法¶
官方 SKILL.md 定义的标准流程如下。
第一步：初始化项目¶
在 Skill 的 scripts 目录所在环境中执行（Agent 通常会代劳）：
bash scripts/init-artifact.sh my-dashboard
cd my-dashboard
完成后可本地预览：
pnpm dev
组件导入方式与常规 shadcn/ui 项目一致：
import { Button } from '@/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
第二步：开发产物¶
编辑 src/ 下文件，按 React 组件方式组织页面。需要路由、全局状态时，在生成的 Vite 项目里按常规方式添加依赖即可——Skill 的价值在于脚手架和打包链路已就绪，而不是限制你只能写单页。
第三步：打包为单 HTML¶
在项目根目录（需有 index.html）执行：
bash scripts/bundle-artifact.sh
成功后会生成 bundle.html。本地验证：
# 直接用浏览器打开 bundle.html
第四步：交付与可选测试¶
把 bundle.html 提供给用户或在对话中展示。官方说明：测试是可选步骤，默认不必在交付前跑 Playwright/Puppeteer，以免增加延迟；若用户反馈有问题再补测。
适用场景与注意事项¶
适合：
- 仪表盘、配置面板、多步骤表单、带 Tab/Dialog 的交互式小应用
- 希望产出物能在浏览器单文件打开、便于分享预览
- 团队已在用 React + Tailwind + shadcn/ui，希望 Agent 输出与现有审美/组件体系一致
不太适合：
- 纯静态落地页、单组件展示（官方明确建议用简单 HTML/JSX Skill）
- 无 Node 环境、无法运行 shell 脚本的受限环境
- 需要长期维护、多人协作的大型工程（这更适合正规仓库 CI/CD，而非 Artifact 打包）
注意：
bundle.html会把依赖全部内联，功能复杂时文件会变大，需权衡。- init 脚本依赖同目录下的
shadcn-components.tar.gz，复制 Skill 时务必保留完整scripts目录。 - Anthropic 仓库 README 有免责声明：示例 Skill 用于演示与教育，Claude 实际行为可能与 Skill 描述存在差异，上线前请在本地实测。
- 该 Skill 最初面向 claude.ai Artifact；在 Cursor 等工具中，最终仍是生成
bundle.html或可在pnpm dev下开发的 Vite 项目，按你的交付方式选用。
小结¶
web-artifacts-builder 解决的不是「会不会写 HTML」，而是「复杂前端产物能否按工程化方式构建并一键打包」。React + shadcn/ui 栈对多数前端开发者没有学习门槛，Agent 也能在明确脚本约束下少犯结构性的错。
官方地址：
https://github.com/anthropics/skills/tree/main/skills/web-artifacts-builder
