# 拆web-artifacts-builder：一页纸指挥部 ## 概述 官方 example-skills 家族里的重头件，docx、xlsx、mcp-builder、skill-creator 本栏都拆过，这次轮到家族里设计取向最极端的一个：web-artifacts-builder。它的 SKILL.md 正文薄到一页纸，真正的体重全压在两个 shell 脚本里；它甚至把「不要先测试」写进了流程制度。本文基于本机实装的插件原文逐段拆解，看官方如何用最少的提示词管住最重的工程活。 ## 档案：一件身体很轻、行李很重的 Skill 本机实装路径为 `example-skills` 插件缓存目录下的 `skills/web-artifacts-builder`（官方仓库 anthropics/skills 的分发版），构成清清楚楚三样东西： - `SKILL.md`：一页纸正文，五个步骤加几段约束 - `scripts/init-artifact.sh`：初始化脚本，负责生成整个项目 - `scripts/bundle-artifact.sh`：打包脚本，负责把工程缝回一个 HTML 技术栈在正文第二行就写死了：**React 18 + TypeScript + Vite + Parcel（打包）+ Tailwind CSS + shadcn/ui**。这句话值得单独一节讲，我们先看骨架。 ```mermaid flowchart TD M["SKILL.md 一页纸"] --> N["五步流程骨架"] M --> O["风格禁令清单"] M --> P["平台交付契约"] N --> Q["init 脚本"] N --> R["bundle 脚本"] Q --> S["组件预装样板间"] Q --> T["版本钉死与适配"] R --> U["Parcel 打包"] R --> V["html-inline 内联"] ``` ## 逐段拆 SKILL.md ### 第一段：五步流程，就是全部骨架 正文开篇一句话定调——「To build powerful frontend claude.ai artifacts, follow these steps」，随后列出五步： 1. 用 `scripts/init-artifact.sh` 初始化前端仓库 2. 编辑生成的代码开发你的 artifact 3. 用 `scripts/bundle-artifact.sh` 把全部代码打成单个 HTML 4. 把产物展示给用户 5. （可选）测试 artifact 这个写法是典型的「流程即骨架」：正文不解释原理、不铺陈知识，只规定动作顺序。Claude 拿到后不需要理解 React 工程细节——它只需要知道**下一步跑什么**。原理和重活分别外包给了官方文档和两个脚本。 对比同家族其他件的拆解结论：docx 把踩过的坑刻成 CRITICAL，xlsx 把交付写成合同条款，mcp-builder 用评分卡把质量关做成制度。而 web-artifacts-builder 的答案是第四种形态——**指挥部只放一张作战地图，武器库另设两间屋**。 ### 第二段：技术栈一行写死，是约束也是礼物 「Stack: React 18 + TypeScript + Vite + Parcel + Tailwind CSS + shadcn/ui」。很多自学者写 Skill 会在这里犯犹豫：要不要让模型自己选型？这件官方件的态度是**不商量**。选型写死带来三个好处：提示词更短、产出可复现、脚本可以按确定的前置条件来写。生成式任务里，自由度是 Bug 的温床，这里官方替你把自由度没收了。 ### 第三段：「AI slop」禁令——负面清单的教科书 正文里唯一一处情绪化标记给了审美： > VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font. 翻译一下：避免过度居中布局、紫色渐变、千篇一律的圆角、以及 Inter 字体。这段设计有两点值得抄： - **用负面清单而非正面描述**。说「不要紫色渐变」比说「要有高级感」可执行得多——模型对禁令的服从度远高于对形容词的领悟力。 - **给问题起名字**。"AI slop" 这个行话一词就把所有已知俗套打包成了单个概念，模型一听就懂要躲开的是哪一类东西。 这不是泛泛的「设计要好看」，而是一份精确到字体名的避雷清单。官方在文档体系里反复迭代这段话，说明 AI 生成界面的同质化已经严重到需要在 Skill 层面立法。 ### 第四段：init 脚本——交付的是一间样板间 第一步的说明列出了脚本的交付物清单： - ✅ React + TypeScript（经 Vite） - ✅ Tailwind CSS **3.4.1** 与 shadcn/ui 主题系统 - ✅ `@/` 路径别名已配置 - ✅ **40+ 个 shadcn/ui 组件预装** - ✅ 全部 Radix UI 依赖就位 - ✅ Parcel 打包配置（.parcelrc） - ✅ Node 18+ 兼容（自动探测并钉住 Vite 版本） 两个细节最见功力。其一是**版本钉死**：Tailwind 精确到 3.4.1，不给依赖漂移留门缝；其二是**自适应兜底**：检测到 Node 18 时自动钉住兼容的 Vite 版本。前者保证复现，后者保证老环境不炸——一紧一松，是工程脚手架的成熟手艺。 「40+ 组件预装」则是空间换心智的打法：不是等模型要用按钮再去装 shadcn/button，而是开工前整屋家具先搬进来。模型写代码时随手 import 就有，省掉一整条「发现缺依赖→安装→改配置」的出错链路。 ### 第五段：bundle 脚本——把平台契约缝进流程 第三步是这件 Skill 的真正目的所在。claude.ai 的 artifact 只认**单个自包含 HTML**，于是正文明确写下脚本的五件事： - 安装打包依赖（parcel、@parcel/config-default、parcel-resolver-tspaths、html-inline） - 生成带路径别名支持的 `.parcelrc` 配置 - 用 Parcel 构建（不出 source map） - 用 html-inline 把所有资源内联 - 产出 `bundle.html`——所有 JS、CSS、依赖全部内联的单文件 注意「Requirements: 项目根目录必须有 index.html」这行小字——契约式写法，前置条件一句话讲清，不满足就直接失败给你看。整个第三步本质上是在提示词里**编码了平台的交付格式**：模型不需要知道 artifact 系统怎么工作，它只需要知道终点长什么样。 ### 第六段：交付动作也是步骤 第四步单独一步：把 bundle.html 在对话里分享给用户。听起来像废话，其实是对齐节奏的关键一步——确保模型把「给用户看到东西」当成流程终点，而不是构建完成就收工。交付语义写进流程，是官方件反复出现的设计母题，xlsx 件把交付写成合同是同一思想的另一个切面。 ### 第七段：最反直觉的一步——「别先测试」 第五步标着 Optional，正文里写得毫不含糊： > In general, avoid testing the artifact upfront as it adds latency between the request and when the finished artifact can be seen. 大意是：通常别提前测试，那会拉长从请求到「用户看到成品」的延迟；先展示，用户提出问题或需要时再测。这句话把一条**产品价值观**写进了 Skill：对交互式 artifact 而言，首屏速度的体验价值高于出厂合格率。测试工具也点明了——用现成工具即可，「包括其他 Skills 或内置工具，比如 Playwright 或 Puppeteer」，这是 Skill 之间互相调用的官方示范。 本栏此前观察过「审查闸挤破头，测试闸空着」的生态现象，这件官方件给出了另一个视角：测试闸不是没人管，而是在某些赛道里被**制度性地排在交付之后**。 ### 第八段：Reference 只有一行外链 全文的参考区只有一条：shadcn/ui 组件文档的外链。知识外包给官方文档，而不是把组件用法抄进 Skill——这是把「正文长度预算」花在刀口上的典型取舍：用法可以现查，流程和禁令必须常驻。 ## 设计模式提炼：能直接抄走的五条 1. **薄正文 + 重脚本**：正文只管流程顺序与禁令，确定性工作全部下沉到脚本。脚本即 API，正文即 README。 2. **负面风格禁令**：把审美要求写成具体的「不要清单」，并给病起名（AI slop），服从度远高于正面形容。 3. **平台契约前置**：目标格式（单文件 HTML）与前置条件（根目录 index.html）开篇讲清，让模型始终知道终点。 4. **可选项显式降权**：不想要的默认行为（提前测试）不是不提，而是标注 Optional 并给出反指示与理由。 5. **版本钉死 + 环境自适应**：依赖版本精确固定保证复现，同时对老运行时自动降级适配，一硬一软两条腿。 ```mermaid flowchart TD A["用户要一个网页工具"] --> B["命中 web-artifacts-builder"] B --> C["读一页纸五步骨架"] C --> D["跑 init 脚本"] D --> E["生成样板间工程"] E --> F["按需开发改造"] F --> G["跑 bundle 脚本"] G --> H["产出单文件 bundle.html"] H --> I["交付给用户"] I --> J{"报错或要改?"} J -->|是| K["按需测试再迭代"] J -->|否| L["收工"] K --> F ``` ## 适用与不适用：边界要说清 **适用**：claude.ai / Claude Code 里交付单文件网页工具——数据可视化小工具、交互式 demo、表单与计算器类原型、面向单人的效率小件。凡是「一个 HTML 走天下」的场景，它都是官方给出的标准答案。 **不适用**：多页面工程、需要 SEO 与服务端的正式站点、需要后端或持久化的产品。bundle 成单文件这件事对复杂应用是负担而非优点；全量预装 40+ 组件对轻量小工具也偏重。另外两条现实约束：打包链路首次要安装 parcel 等依赖，冷启动偏慢；离线或网络受限的沙箱环境里，依赖安装和外链文档查用都会受阻。脚本本体在本次拆解环境中因权限未能展开，以上对脚本行为的描述均以 SKILL.md 自述为准——不过换角度看，正文能把脚本的活儿预告得这么完整，本身就是「脚本当 API 用」设计成熟度的证明。 ## 评测记分卡 | 维度 | 评分 | 一句话理由 | |------|------|-----------| | 功能完整度 | ★★★★★ | 从空目录到可分享成品一条龙，边界场景（Node 18）都有兜底 | | 设计质量 | ★★★★★ | 薄正文、负面禁令、契约前置、延迟取舍，教科书级取舍 | | 实战效果 | ★★★★☆ | 官方样板间路线成熟；「先交付后测试」见仁见智 | | 上手难度 | ★★★★★ | 一句「帮我做个网页小工具」即可触发，零配置 | | 社区活跃度 | ★★★★☆ | 随官方 example-skills 插件分发维护，属生态第一梯队 | 综合：**4.6 / 5**。它不是最炫的 Skill，却是「如何用最少的提示词管最重的活」这个问题的官方参考答案。 ## 安装与使用 本机若已装官方 example-skills 插件则开箱即用，无需安装。手动安装的两种方式： ```bash # 方式一：从官方仓库安装 git clone https://github.com/anthropics/skills.git cp -r skills/web-artifacts-builder ~/.claude/skills/ # 注：目录名以仓库实际为准（部分分发版叫 artifacts-builder） # 方式二：先搜索定位再装 npx skills find artifacts-builder ``` 使用无需任何口令，直接提需求即可命中：「用 web-artifacts-builder 给我做一个番茄钟网页小工具」。想显式点名，就在请求里带上技能名。 ## 结语 生态里多数 Skill 在卷描述词、卷触发率，这件官方件反向操作：正文薄到不能再薄，把体重全部转移到确定性的脚本里，甚至敢于把「不测试」写成制度。它示范了一个朴素的道理——**Skill 的上限不取决于正文写了多少，而取决于它把多少不确定性提前关进了笼子**。想写自己第一件 Skill 的人，与其模仿厚文档，不如先学这份一页纸指挥部的克制。 ## 参考来源 1. [anthropics/skills 官方仓库](https://github.com/anthropics/skills) — web-artifacts-builder 的源头分发仓库（Star 数据本轮未核验，不作引用） 2. 本机 example-skills 插件实装文件 `plugins/cache/anthropic-agent-skills/example-skills/3d5951151859/skills/web-artifacts-builder/SKILL.md` — 本文全部引文出处（两个脚本本体因环境读取权限未能展开，相关描述以正文自述为准） 3. [skillsmp.com](https://skillsmp.com) / [skills.sh](https://skills.sh) — Skills 聚合目录，可用于交叉检索该件的分发与热度信息 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。