一个 skill就能让 AI 编程助手直接产出带粒子光效、旋转动画、鼠标交互的 3D 特效网页听起来很像标题党但实际跑通之后我觉得这条思路确实值得展开聊聊。这里说的 skill指的不是网盘里那个资源合集而是 AI 编程工具里的可复用能力包。在 Claude Code、Codex、OpenCode 这类 Agent 工具里skill 是一种比普通提示词更结构化的扩展方式它可以把模板、脚本、参考文档打包在一起让模型在合适的场景里直接使用。这个主题适合谁看第一已经接触过 Agent 编程工具但还没自己写过 skill 的人第二想在本地快速生成 3D 特效网页不想每次从零搭 Three.js 项目的人第三想把自己的 Agent 工作流做成可复用模块的人。下面按“理解 skill — 设计 skill — 编写 skill — 运行验证 — 排查问题 — 进阶生产化”的顺序拆一遍。1. 先用一个真实场景理解 skill 和普通提示词的区别1.1 skill 是给 Agent 用的“干活包”不是一句提示词很多人有个误区把 skill 理解成一个特别长的提示词模板。这个理解不全对。提示词只是在对话里给模型写了一段要求模型看完就忘下次还要重新写。而 skill 在 Agent 工具里的常见形态是一个目录里面至少包含一个描述文件说明这个 skill 在什么情况下被调用。若干模板文件把高频使用的代码框架提前写好。可选脚本用来处理参数、生成文件或做校验。可选参考文档把最佳实践、注意事项、常见坑位固定下来。换句话说skill 是一套可复用的工具包。Agent 是执行者skill 是执行者随身携带的操作手册和工具。你告诉 Agent“帮我做一个 3D 粒子银河”Agent 读取 skill 的说明发现“这个需求在当前 skill 的适用范围内”然后加载对应模板再按照当前需求填充变量最终生成一个 HTML 文件。这个差别看表格会更清楚对比项普通提示词skill生命周期对话结束就消失存在于目录中可反复使用代码模板每次靠模型现场写从 template 文件直接加载参数规范每次可能不一致提前定义好稳定复用排查经验不在上下文里写在 references 文档中可分享性一段文字一个目录可分享给团队1.2 为什么 3D 特效网页特别适合用 skill 来做因为 3D 网页的代码有几个明显特点。第一样板代码多。任何一个 Three.js 项目都需要 scene、camera、renderer、light、animation loop。这套东西非常固定不值得每次重复写。第二参数调整频率高。同样一个粒子系统数量从 1000 改成 10000颜色从蓝色改成橙色交互从鼠标旋转改成点击爆炸其实都是参数和函数选择的变化而不是整个项目结构的重写。第三容易出错。WebGL 报错、CDN 加载失败、模型路径不对、GPU 兼容性问题这些坑几乎每个项目都会碰到。把这些排查顺序写进 skill 的参考文档Agent 在生成代码时就会主动避免常见问题。所以用一个 skill 来封装 3D 特效网页的生成逻辑看起来是“炫酷”本质上是在解决复用性和稳定性问题。这也是为什么我建议不要把 skill 写得太大一个 skill 解决一类问题效果往往比一个万能 skill 好得多。1.3 为什么最近大家都在聊 agent skill、skill 脚本如果你最近关注 Claude Code skill、Codex skill、OpenCode skill 这类关键词会发现很多团队开始把日常工作流沉淀成 skill。原因不复杂Agent 的能力边界不是模型参数决定的而是“有没有合适的工具和规范”决定的。一个会写前端页面的模型如果没有拿到稳定的渲染模板生成的代码就可能一次一个样子。有了 skill输出质量、目录结构、参数命名、验证流程都能对齐。这个思路对个人开发者同样成立。你把一次成功的 3D 网页项目拆成模板和参数下次就能稳定复现甚至批量生成多个页面。所以与其说 skill 是一个“新概念”不如说它是把过去散落在提示词里的经验重新组织成了工程化目录。2. 写一个 3D 特效网页 skill 之前先把环境和目录想清楚2.1 本地环境到底要准备什么生成 3D 特效网页的 skill和跑大型模型的 skill 不一样它对硬件要求并不高。实测时我用的是一台普通的 Windows 笔记本没有独立显卡8GB 内存跑单页面特效完全没问题。需要准备的主要是软件环境Node.js 18 或更高版本。不直接用 Node 跑 Three.js 也行但本地静态服务器和 npm 包管理会用到装上更省事。一个支持 WebGL 的现代浏览器。Chrome、Edge、Firefox 都可以。判断标准很简单打开 WebGL 测试页如果能显示动态立方体就说明浏览器没问题。一个支持 skill 机制的 Agent 工具比如 Claude Code、Codex、OpenCode 中任选一个。编辑器用于查看和修改生成的代码。这里要提醒一句不是说低配置就不能玩 3D。粒子数量控制在几千分辨率默认普通的集成显卡也能流畅运行。但如果要做超多粒子、后处理光晕、阴影叠加就需要考虑 GPU 和内存的边界。2.2 skill 的目录结构先给自己定一个稳定习惯不同工具对 skill 目录的默认位置和命名规则会有差别。常见做法是放在用户目录下的.claude/skills、.codex/skills、.opencode/skill目录里。我一般会建立一个专门放自己技能包的目录比如my-skills然后把它指向 Agent 工具的配置。这一步的好处是多个工具共用一套技能包不至于换一个 Agent 就重写一遍。一个 3D 特效网页 skill 的目录我习惯这样组织my-skills/ └── web3d-skills/ ├── SKILL.md ├── scripts/ │ ├── generate_page.py │ └── validate_output.js ├── templates/ │ ├── base_scene.html │ ├── particle_field.html │ ├── galaxy_rotation.html │ └── radar_ripple.html └── references/ ├── performance_tips.md └── troubleshooting.md这个结构里核心是 SKILL.md它是 Agent 理解这个 skill 的入口templates 是已有的页面骨架scripts 用来做参数替换、文件生成和基本校验references 存经验和排查清单。为什么要分这么细因为如果不把模板和描述分开SKILL.md 会越来越长最后变成一个谁都看不懂的巨型文档。模板负责“代码复用”SKILL.md 负责“什么时候用、怎么用、选哪个模板”脚本负责“替用户把重复动作干了”参考文档负责“遇到问题去哪查”。四件事各干各的整个 skill 才容易维护。2.3 模板文件决定了生成质量的底线很多人以为 skill 的效果取决于模型聪明程度其实更大程度上取决于模板质量。模型再强如果模板里没有正确的渲染循环生成的页面也跑不起来。反过来模板足够稳定哪怕模型只是简单地替换参数结果也不会差。所以模板文件不要写得花里胡哨先保证最小可运行。我最开始写模板时犯过两个错误第一个把各种特效都堆进一个页面结果打开页面后 FPS 很低以为是 skill 问题其实是模板没拆开。第二个模板里用了较新的 Three.js 模块写法但没有写 importmap导致浏览器直接报模块解析错误。后来我把模板拆成 base_scene、particle_field、galaxy_rotation、radar_ripple 几个独立文件每个页面只做一件事生成前明确告诉 Agent 应该选哪个模板出问题概率大大下降。3. 动手写一个基于 Three.js 的 3D 特效网页 skill3.1 先写 SKILL.md把适用场景和调用方式说清楚SKILL.md 是 Agent 最先读取的文件。写的时候第一要务不是写代码而是把“什么时候调用这个 skill”写清楚。否则 Agent 可能在一个跟 3D 完全无关的需求里也硬套这个模板。下面是一个简化的 SKILL.md 示例结构上可以作为参考--- name: web3d-skills description: 当用户需要创建 3D 特效网页、Three.js 动画、WebGL 场景、粒子效果、星空背景、3D 地球效果时使用此 skill。也可以用于把现有页面升级为带 3D 特效的展示页。 --- # Web3D Skills ## 核心思路 - 用 Three.js 创建 3D 场景。 - 优先使用 templates 目录下的模板文件不要从零编写。 - 根据用户需求选择模板 base_scene 用于最简场景particle_field 用于粒子效果galaxy_rotation 用于旋转星系radar_ripple 用于雷达波纹。 - 生成代码后先做基础校验检查是否引入 three 模块、是否创建 scene/camera/renderer、是否启动 animation loop。 ## 输出约定 - 输出一个单独的 .html 文件JS 和 CSS 内联方便直接打开。 - 文件放在用户指定的目录默认命名为 index.html。 - 如需批量生成文件名使用 skill_demo_01.html、skill_demo_02.html 这类规则。 ## 常见参数 - particleCount: 粒子数量默认 3000。 - backgroundColor: 背景色默认 #0a0a2e。 - rotateSpeed: 旋转速度默认 0.002。 - pointerInteraction: 是否启用鼠标交互默认 true。这里我特意把“生成代码后先做基础校验”写了进去。为什么因为 Agent 生成代码最大的问题不是“能不能写”而是“写完不检查”。多了这一条它在输出前就会主动检查关键函数是否存在。3.2 最小可运行模板场景、相机、渲染器、动画循环接下来是最关键的 base_scene 模板。它不用做任何花哨效果只要保证打开页面后能看到一个旋转的物体就说明渲染链路是通的。示例片段如下!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title3D Base Scene/title style body { margin: 0; overflow: hidden; background: #0a0a2e; } /style /head body script typeimportmap { imports: { three: https://unpkg.com/three/build/three.module.js, three/addons/: https://unpkg.com/three/examples/jsm/ } } /script script typemodule import * as THREE from three; const scene new THREE.Scene(); scene.background new THREE.Color(#0a0a2e); const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); camera.position.set(0, 0, 5); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement); const geometry new THREE.BoxGeometry(1, 1, 1); const material new THREE.MeshStandardMaterial({ color: 0x4a9eff }); const mesh new THREE.Mesh(geometry, material); scene.add(mesh); const light new THREE.DirectionalLight(0xffffff, 3); light.position.set(1, 1, 1); scene.add(light); function animate() { requestAnimationFrame(animate); mesh.rotation.x 0.005; mesh.rotation.y 0.01; renderer.render(scene, camera); } animate(); window.addEventListener(resize, () { camera.aspect window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); }); /script /body /html这段代码是标准的 Three.js 入门写法。scene 是场景容器camera 决定从哪个角度观察renderer 负责把 3D 画面绘制到浏览器。在 animate 里不断调整 mesh 的 rotation 并重新渲染就产生了旋转动画。为什么加 resize 监听因为浏览器窗口变化后如果相机比例和渲染尺寸不同步画面会变形。3.3 把特效拆成可配置参数而不是每个效果写一套代码这里要说一个很实用的思路。很多人写 skill 模板时喜欢把每种特效都写成独立 HTML比如“星星背景.html”“粒子球.html”“旋转地球.html”。这样当然能跑但模板数量一多维护成本很高。更好的做法是把公共部分抽出去只差异化为参数。以粒子星系为例差异点主要是这些particleCount 粒子数量决定密度和性能。color1、color2 粒子颜色决定视觉风格。spread 粒子分布范围。rotateSpeed 旋转速度。pointerInteraction 是否开启鼠标视差。在模板里这些值可以放在 HTML 顶部的配置区。生成时Agent 只需要替换配置区不需要重写整个 3D 逻辑。用这种“公共模板 参数化配置”的方式一个模板可以衍生出几十种不同观感的效果。批量生成多个展示页时也只是替换配置区再另存文件不会把页面间的不一致性带到代码里。4. 实际跑一遍从调用 skill 到得到可用的特效网页4.1 先跑最小样例让 Agent 生成一个带粒子星河的页面完成 skill 目录和模板后第一次使用不要一上来就提复杂需求。我会先让 Agent 生成一个最简单的粒子星河页面。示例指令是使用 web3d-skills 生成一个 3D 粒子星河页面。 要求 - 背景深蓝色 - 粒子数量 3000 - 粒子颜色从蓝渐变到紫 - 鼠标移动时产生轻微视差 - 输出到 ./output/star_river.html这时Agent 会读取 SKILL.md根据描述决定使用 particle_field 模板再根据当前需求替换参数。如果你第一次体验输出往往不会直接到位而是生成一个基本可用的版本。这不奇怪。重点不是一次成功而是跑通链路。4.2 验证输出是不是真的合格别只看预览图生成完代码后我一般不会直接说“效果很好”而是分成四步验证。第一步检查文件是否完整。打开生成的 HTML确认 CSS、JS、模板引用都在没有被截断。第二步启动本地静态服务器。直接在浏览器双击打开 HTML虽然能运行但涉及模块加载时可能出现跨域问题。更稳妥的方式是在项目目录执行npx serve output或者用 Python 自带的静态服务器python -m http.server 8080然后访问http://localhost:8080/star_river.html。第三步打开浏览器开发者工具看 Console 和 Network。如果 Console 有红色报错优先处理如果 Network 里 three 模块加载失败优先检查 CDN 和网络。第四步实际感受交互和性能。鼠标移动是否跟手旋转是否卡顿窗口缩放后画面有没有变形。这四步做完才能说这个页面是合格的。很多看起来炫酷的 3D 项目实际上连控制台报错都没清理这类问题以后部署到线上会非常麻烦。4.3 从单页面扩展到批量生成skill 真正体现价值的地方是批量生成场景。比如你需要在同一个活动页面里输出 5 个不同主题的 3D 背景星空、极光、光球、数据波纹、粒子旋涡。按照传统方式需要手写 5 个页面有了 skill 后你可以准备一个需求列表让 Agent 逐个生成。比如使用 web3d-skills 批量生成 5 个 3D 背景页面 1. demo_star.html星空粒子蓝色 2. demo_aurora.html极光渐变绿色 3. demo_core.html核心光球金色 4. demo_wave.html雷达波纹青色 5. demo_spiral.html螺旋粒子紫色 输出到 ./output/使用统一命名规范。批量任务的关键不是“能生成”而是“一致性”。你要在 SKILL.md 里写清楚命名规范、输出目录、参数默认值这样生成出的多个文件结构才统一。否则第一个页面粒子数量 3000第二个页面变成 30000页面风格就乱了。注意不要第一次就要求十个特效全部塞进一个页面。先把一个粒子的场景跑通再谈组合。4.4 从 3D 特效网页扩展到 3D 可视化用同一个 skill 思路也可以扩展到 3D 数据可视化。很多人会搜索 3D 点云、3D 地球效果、ECharts 3D 饼图这些都是同一个底层逻辑Three.js 负责渲染数据源负责提供坐标和颜色skill 负责把数据映射成三维对象。这种能力在实际项目里很有用。比如把城市坐标投影成 3D 地球上的亮点或者把传感器数据按位置显示成点云。skill 的模板里只要预留数据接口生成时把静态数组替换成接口返回就行。更高阶的方向是 3D Gaussian Splatting也就是 3D 高斯泼溅渲染。这种技术本身比较复杂但对 skill 来说它也只是另一个模板方向把数据加载、相机控制、渲染参数固定下来用户需要时替换数据源。也就是说skill 的价值不会局限在“做一个转动的立方体”它同样能承载新一代渲染技术。5. 常见问题排查skill 不生效、页面空白、卡片顿5.1 skill 没有被识别先查路径和描述如果指令发出后Agent 完全忽略你的 skill没有使用对应模板排查顺序是先看 skill 是否放在 Agent 工具能扫描到的目录。路径不对是最常见原因。再看 SKILL.md 的 description 是否足够清晰。描述太模糊Agent 可能认为该 skill 与当前需求无关。看工具日志。大多数 Agent 工具会记录“使用了哪个 skill”的调用信息。最后测试把 description 改成更明确的话比如“当用户提到粒子、3D、Three.js、特效网页时必须使用本 skill”再试一次。这里要注意不同 Agent 工具的 skill 扫描规则不完全一样。我建议以你使用的工具文档为准不要只凭网上的教程猜。5.2 生成页面后空白优先查控制台而不是改代码页面空白是 3D 网页最常见的失败状态。很多人第一反应是“模型生成的代码有问题”然后反复让 Agent 重写其实很多时候问题不在代码而在运行环境。我会按这个顺序排查第一步看浏览器控制台。如果报错信息是THREE is not defined说明 three 模块没有正确加载检查 importmap 和 CDN 是否被拦截。第二步看 Network 面板。确认 three.module.js 是否请求成功是不是网络问题。第三步看页面是否有 canvas 元素。如果有 canvas 但黑屏可能是相机朝向问题或者场景里没有加入任何对象。第四步看动画循环是否启动。如果没有requestAnimationFrame或renderer.render画面永远不会更新。第五步再看参数。粒子数量太大、位置超出相机范围、颜色值写错都可能导致视觉上看起来是空白。这套顺序的目标是先把“环境问题”和“代码问题”区分开。否则你会花很多时间改代码最后发现只是浏览器兼容问题。页面空白时先把浏览器开发者工具打开。结论写在 Console 和 Network 里不要靠猜。5.3 低配置机器上卡顿按优先级调参数如果你在普通笔记本上跑粒子特效感觉掉帧不一定需要换电脑。按优先级做下面这些调整降低粒子数量。默认 5000 改成 2000视觉差异可能不大流畅度提升明显。关闭抗锯齿。把antialias: true改成false。降低设备像素比。在渲染器初始化后设置renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));减少不必要的灯光和阴影。阴影是性能杀手页面是背景特效时通常不需要开阴影。用静态背景色替代复杂的环境贴图。这几个调整里降低粒子数量效果最直接。这里要特别注意低配置能跑不代表适合同时开多个 3D 页面。如果页面中还有后台任务或者打开了多个标签页掉帧是正常现象。5.4 兼容性问题有些功能不是“支持”而是“限定浏览器”Three.js 的大部分功能在现代浏览器上都能运行但某些特性会有兼容性边界。比如 WebGPU 相关的渲染器就需要较新的浏览器WebGL 1 与 WebGL 2 在一些旧设备上表现不同。如果你的目标是活动页、宣传页尽量用兼容性最好的基础渲染方式不要为了炫酷使用冷门扩展。再补充一个实际体验点3D 页面在手机上的表现和电脑差别很大。手机上 GPU 性能弱触控事件与鼠标事件不同如果你的页面只绑定了mousemove会在手机端完全失效。模板里可以同时处理pointermove和touchmove这样兼容性会好很多。6. 让 skill 真正成为生产工具的进阶建议6.1 增加脚本做文件生成和参数校验当 skill 越来越复杂纯靠 Agent 替换 HTML 里的配置区可能不够稳定。这时候可以在 scripts 目录里加一个 Python 或 Node 脚本专门负责“读配置 - 填模板 - 输出文件”。比如用一个 JSON 配置描述所有特效参数脚本自动生成 HTML。这样的好处是流程可重复参数可以版本化管理。示例调用方式可以是python scripts/generate_page.py --template particle_field --config configs/demo_star.json --output output/demo_star.html如果用到了脚本SKILL.md 里就要写清楚什么情况下运行脚本脚本参数是什么输出文件到哪里。Agent 只负责根据用户需求生成 config 文件脚本负责精确生成最终 HTML。这相当于把“模型写代码”和“代码执行”分开了稳定性更高。6.2 把 skill 沉淀成团队规范如果你不是一个人玩而是团队里有多个人都在用 Agent 生成 3D 页面skill 就会变成一种轻量级规范。目录结构统一、命名统一、参数含义统一、排查文档统一。新同学拿到 skill 后不需要从零研究 Three.js也能生成合格的网页。这个价值往往比“生成速度快”更值得关注。我一般在团队里会约定三条硬规则所有 3D 页面必须基于模板生成禁止从零手写。所有参数必须写在页面顶部的配置区禁止散落在代码各处。所有输出必须通过本地静态服务器验证禁止只检查代码不检查渲染效果。有了这些规则skill 就不仅是一个工具而是团队规范的载体。6.3 我的真实经验先守住最小闭环再谈炫酷最后说几句实在话。用过几次 skill 后我的体会是它帮你解决的是“重复劳动被自动化”的问题而不是“创意自动涌现”的问题。3D 特效网页之所以显得炫酷是因为 Three.js 本身能做出很强的视觉冲击力但真正决定页面能不能用的还是场景搭建、相机控制、性能优化这些基础能力。我个人的建议是第一次写 skill 时不要贪多。先做一个 base_scene 模板能生成旋转立方体就说明链路通了。然后再逐步加粒子、加鼠标交互、加多个模板。等这套流程稳定了再考虑批量生成和参数脚本。踩过几次坑以后我也发现很多问题不是 skill 能力不够而是前置条件没有处理干净。路径不对、Node 版本太老、浏览器不支持 importmap、CDN 加载失败这些看起来像“模型不好”的问题实际都是工程问题。先把这些排查清楚了再去调模型指令效率会高很多。 AI编程助手Skill实战：用Three.js模板化生成3D特效网页
一个 skill就能让 AI 编程助手直接产出带粒子光效、旋转动画、鼠标交互的 3D 特效网页听起来很像标题党但实际跑通之后我觉得这条思路确实值得展开聊聊。这里说的 skill指的不是网盘里那个资源合集而是 AI 编程工具里的可复用能力包。在 Claude Code、Codex、OpenCode 这类 Agent 工具里skill 是一种比普通提示词更结构化的扩展方式它可以把模板、脚本、参考文档打包在一起让模型在合适的场景里直接使用。这个主题适合谁看第一已经接触过 Agent 编程工具但还没自己写过 skill 的人第二想在本地快速生成 3D 特效网页不想每次从零搭 Three.js 项目的人第三想把自己的 Agent 工作流做成可复用模块的人。下面按“理解 skill — 设计 skill — 编写 skill — 运行验证 — 排查问题 — 进阶生产化”的顺序拆一遍。1. 先用一个真实场景理解 skill 和普通提示词的区别1.1 skill 是给 Agent 用的“干活包”不是一句提示词很多人有个误区把 skill 理解成一个特别长的提示词模板。这个理解不全对。提示词只是在对话里给模型写了一段要求模型看完就忘下次还要重新写。而 skill 在 Agent 工具里的常见形态是一个目录里面至少包含一个描述文件说明这个 skill 在什么情况下被调用。若干模板文件把高频使用的代码框架提前写好。可选脚本用来处理参数、生成文件或做校验。可选参考文档把最佳实践、注意事项、常见坑位固定下来。换句话说skill 是一套可复用的工具包。Agent 是执行者skill 是执行者随身携带的操作手册和工具。你告诉 Agent“帮我做一个 3D 粒子银河”Agent 读取 skill 的说明发现“这个需求在当前 skill 的适用范围内”然后加载对应模板再按照当前需求填充变量最终生成一个 HTML 文件。这个差别看表格会更清楚对比项普通提示词skill生命周期对话结束就消失存在于目录中可反复使用代码模板每次靠模型现场写从 template 文件直接加载参数规范每次可能不一致提前定义好稳定复用排查经验不在上下文里写在 references 文档中可分享性一段文字一个目录可分享给团队1.2 为什么 3D 特效网页特别适合用 skill 来做因为 3D 网页的代码有几个明显特点。第一样板代码多。任何一个 Three.js 项目都需要 scene、camera、renderer、light、animation loop。这套东西非常固定不值得每次重复写。第二参数调整频率高。同样一个粒子系统数量从 1000 改成 10000颜色从蓝色改成橙色交互从鼠标旋转改成点击爆炸其实都是参数和函数选择的变化而不是整个项目结构的重写。第三容易出错。WebGL 报错、CDN 加载失败、模型路径不对、GPU 兼容性问题这些坑几乎每个项目都会碰到。把这些排查顺序写进 skill 的参考文档Agent 在生成代码时就会主动避免常见问题。所以用一个 skill 来封装 3D 特效网页的生成逻辑看起来是“炫酷”本质上是在解决复用性和稳定性问题。这也是为什么我建议不要把 skill 写得太大一个 skill 解决一类问题效果往往比一个万能 skill 好得多。1.3 为什么最近大家都在聊 agent skill、skill 脚本如果你最近关注 Claude Code skill、Codex skill、OpenCode skill 这类关键词会发现很多团队开始把日常工作流沉淀成 skill。原因不复杂Agent 的能力边界不是模型参数决定的而是“有没有合适的工具和规范”决定的。一个会写前端页面的模型如果没有拿到稳定的渲染模板生成的代码就可能一次一个样子。有了 skill输出质量、目录结构、参数命名、验证流程都能对齐。这个思路对个人开发者同样成立。你把一次成功的 3D 网页项目拆成模板和参数下次就能稳定复现甚至批量生成多个页面。所以与其说 skill 是一个“新概念”不如说它是把过去散落在提示词里的经验重新组织成了工程化目录。2. 写一个 3D 特效网页 skill 之前先把环境和目录想清楚2.1 本地环境到底要准备什么生成 3D 特效网页的 skill和跑大型模型的 skill 不一样它对硬件要求并不高。实测时我用的是一台普通的 Windows 笔记本没有独立显卡8GB 内存跑单页面特效完全没问题。需要准备的主要是软件环境Node.js 18 或更高版本。不直接用 Node 跑 Three.js 也行但本地静态服务器和 npm 包管理会用到装上更省事。一个支持 WebGL 的现代浏览器。Chrome、Edge、Firefox 都可以。判断标准很简单打开 WebGL 测试页如果能显示动态立方体就说明浏览器没问题。一个支持 skill 机制的 Agent 工具比如 Claude Code、Codex、OpenCode 中任选一个。编辑器用于查看和修改生成的代码。这里要提醒一句不是说低配置就不能玩 3D。粒子数量控制在几千分辨率默认普通的集成显卡也能流畅运行。但如果要做超多粒子、后处理光晕、阴影叠加就需要考虑 GPU 和内存的边界。2.2 skill 的目录结构先给自己定一个稳定习惯不同工具对 skill 目录的默认位置和命名规则会有差别。常见做法是放在用户目录下的.claude/skills、.codex/skills、.opencode/skill目录里。我一般会建立一个专门放自己技能包的目录比如my-skills然后把它指向 Agent 工具的配置。这一步的好处是多个工具共用一套技能包不至于换一个 Agent 就重写一遍。一个 3D 特效网页 skill 的目录我习惯这样组织my-skills/ └── web3d-skills/ ├── SKILL.md ├── scripts/ │ ├── generate_page.py │ └── validate_output.js ├── templates/ │ ├── base_scene.html │ ├── particle_field.html │ ├── galaxy_rotation.html │ └── radar_ripple.html └── references/ ├── performance_tips.md └── troubleshooting.md这个结构里核心是 SKILL.md它是 Agent 理解这个 skill 的入口templates 是已有的页面骨架scripts 用来做参数替换、文件生成和基本校验references 存经验和排查清单。为什么要分这么细因为如果不把模板和描述分开SKILL.md 会越来越长最后变成一个谁都看不懂的巨型文档。模板负责“代码复用”SKILL.md 负责“什么时候用、怎么用、选哪个模板”脚本负责“替用户把重复动作干了”参考文档负责“遇到问题去哪查”。四件事各干各的整个 skill 才容易维护。2.3 模板文件决定了生成质量的底线很多人以为 skill 的效果取决于模型聪明程度其实更大程度上取决于模板质量。模型再强如果模板里没有正确的渲染循环生成的页面也跑不起来。反过来模板足够稳定哪怕模型只是简单地替换参数结果也不会差。所以模板文件不要写得花里胡哨先保证最小可运行。我最开始写模板时犯过两个错误第一个把各种特效都堆进一个页面结果打开页面后 FPS 很低以为是 skill 问题其实是模板没拆开。第二个模板里用了较新的 Three.js 模块写法但没有写 importmap导致浏览器直接报模块解析错误。后来我把模板拆成 base_scene、particle_field、galaxy_rotation、radar_ripple 几个独立文件每个页面只做一件事生成前明确告诉 Agent 应该选哪个模板出问题概率大大下降。3. 动手写一个基于 Three.js 的 3D 特效网页 skill3.1 先写 SKILL.md把适用场景和调用方式说清楚SKILL.md 是 Agent 最先读取的文件。写的时候第一要务不是写代码而是把“什么时候调用这个 skill”写清楚。否则 Agent 可能在一个跟 3D 完全无关的需求里也硬套这个模板。下面是一个简化的 SKILL.md 示例结构上可以作为参考--- name: web3d-skills description: 当用户需要创建 3D 特效网页、Three.js 动画、WebGL 场景、粒子效果、星空背景、3D 地球效果时使用此 skill。也可以用于把现有页面升级为带 3D 特效的展示页。 --- # Web3D Skills ## 核心思路 - 用 Three.js 创建 3D 场景。 - 优先使用 templates 目录下的模板文件不要从零编写。 - 根据用户需求选择模板 base_scene 用于最简场景particle_field 用于粒子效果galaxy_rotation 用于旋转星系radar_ripple 用于雷达波纹。 - 生成代码后先做基础校验检查是否引入 three 模块、是否创建 scene/camera/renderer、是否启动 animation loop。 ## 输出约定 - 输出一个单独的 .html 文件JS 和 CSS 内联方便直接打开。 - 文件放在用户指定的目录默认命名为 index.html。 - 如需批量生成文件名使用 skill_demo_01.html、skill_demo_02.html 这类规则。 ## 常见参数 - particleCount: 粒子数量默认 3000。 - backgroundColor: 背景色默认 #0a0a2e。 - rotateSpeed: 旋转速度默认 0.002。 - pointerInteraction: 是否启用鼠标交互默认 true。这里我特意把“生成代码后先做基础校验”写了进去。为什么因为 Agent 生成代码最大的问题不是“能不能写”而是“写完不检查”。多了这一条它在输出前就会主动检查关键函数是否存在。3.2 最小可运行模板场景、相机、渲染器、动画循环接下来是最关键的 base_scene 模板。它不用做任何花哨效果只要保证打开页面后能看到一个旋转的物体就说明渲染链路是通的。示例片段如下!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title3D Base Scene/title style body { margin: 0; overflow: hidden; background: #0a0a2e; } /style /head body script typeimportmap { imports: { three: https://unpkg.com/three/build/three.module.js, three/addons/: https://unpkg.com/three/examples/jsm/ } } /script script typemodule import * as THREE from three; const scene new THREE.Scene(); scene.background new THREE.Color(#0a0a2e); const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); camera.position.set(0, 0, 5); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement); const geometry new THREE.BoxGeometry(1, 1, 1); const material new THREE.MeshStandardMaterial({ color: 0x4a9eff }); const mesh new THREE.Mesh(geometry, material); scene.add(mesh); const light new THREE.DirectionalLight(0xffffff, 3); light.position.set(1, 1, 1); scene.add(light); function animate() { requestAnimationFrame(animate); mesh.rotation.x 0.005; mesh.rotation.y 0.01; renderer.render(scene, camera); } animate(); window.addEventListener(resize, () { camera.aspect window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); }); /script /body /html这段代码是标准的 Three.js 入门写法。scene 是场景容器camera 决定从哪个角度观察renderer 负责把 3D 画面绘制到浏览器。在 animate 里不断调整 mesh 的 rotation 并重新渲染就产生了旋转动画。为什么加 resize 监听因为浏览器窗口变化后如果相机比例和渲染尺寸不同步画面会变形。3.3 把特效拆成可配置参数而不是每个效果写一套代码这里要说一个很实用的思路。很多人写 skill 模板时喜欢把每种特效都写成独立 HTML比如“星星背景.html”“粒子球.html”“旋转地球.html”。这样当然能跑但模板数量一多维护成本很高。更好的做法是把公共部分抽出去只差异化为参数。以粒子星系为例差异点主要是这些particleCount 粒子数量决定密度和性能。color1、color2 粒子颜色决定视觉风格。spread 粒子分布范围。rotateSpeed 旋转速度。pointerInteraction 是否开启鼠标视差。在模板里这些值可以放在 HTML 顶部的配置区。生成时Agent 只需要替换配置区不需要重写整个 3D 逻辑。用这种“公共模板 参数化配置”的方式一个模板可以衍生出几十种不同观感的效果。批量生成多个展示页时也只是替换配置区再另存文件不会把页面间的不一致性带到代码里。4. 实际跑一遍从调用 skill 到得到可用的特效网页4.1 先跑最小样例让 Agent 生成一个带粒子星河的页面完成 skill 目录和模板后第一次使用不要一上来就提复杂需求。我会先让 Agent 生成一个最简单的粒子星河页面。示例指令是使用 web3d-skills 生成一个 3D 粒子星河页面。 要求 - 背景深蓝色 - 粒子数量 3000 - 粒子颜色从蓝渐变到紫 - 鼠标移动时产生轻微视差 - 输出到 ./output/star_river.html这时Agent 会读取 SKILL.md根据描述决定使用 particle_field 模板再根据当前需求替换参数。如果你第一次体验输出往往不会直接到位而是生成一个基本可用的版本。这不奇怪。重点不是一次成功而是跑通链路。4.2 验证输出是不是真的合格别只看预览图生成完代码后我一般不会直接说“效果很好”而是分成四步验证。第一步检查文件是否完整。打开生成的 HTML确认 CSS、JS、模板引用都在没有被截断。第二步启动本地静态服务器。直接在浏览器双击打开 HTML虽然能运行但涉及模块加载时可能出现跨域问题。更稳妥的方式是在项目目录执行npx serve output或者用 Python 自带的静态服务器python -m http.server 8080然后访问http://localhost:8080/star_river.html。第三步打开浏览器开发者工具看 Console 和 Network。如果 Console 有红色报错优先处理如果 Network 里 three 模块加载失败优先检查 CDN 和网络。第四步实际感受交互和性能。鼠标移动是否跟手旋转是否卡顿窗口缩放后画面有没有变形。这四步做完才能说这个页面是合格的。很多看起来炫酷的 3D 项目实际上连控制台报错都没清理这类问题以后部署到线上会非常麻烦。4.3 从单页面扩展到批量生成skill 真正体现价值的地方是批量生成场景。比如你需要在同一个活动页面里输出 5 个不同主题的 3D 背景星空、极光、光球、数据波纹、粒子旋涡。按照传统方式需要手写 5 个页面有了 skill 后你可以准备一个需求列表让 Agent 逐个生成。比如使用 web3d-skills 批量生成 5 个 3D 背景页面 1. demo_star.html星空粒子蓝色 2. demo_aurora.html极光渐变绿色 3. demo_core.html核心光球金色 4. demo_wave.html雷达波纹青色 5. demo_spiral.html螺旋粒子紫色 输出到 ./output/使用统一命名规范。批量任务的关键不是“能生成”而是“一致性”。你要在 SKILL.md 里写清楚命名规范、输出目录、参数默认值这样生成出的多个文件结构才统一。否则第一个页面粒子数量 3000第二个页面变成 30000页面风格就乱了。注意不要第一次就要求十个特效全部塞进一个页面。先把一个粒子的场景跑通再谈组合。4.4 从 3D 特效网页扩展到 3D 可视化用同一个 skill 思路也可以扩展到 3D 数据可视化。很多人会搜索 3D 点云、3D 地球效果、ECharts 3D 饼图这些都是同一个底层逻辑Three.js 负责渲染数据源负责提供坐标和颜色skill 负责把数据映射成三维对象。这种能力在实际项目里很有用。比如把城市坐标投影成 3D 地球上的亮点或者把传感器数据按位置显示成点云。skill 的模板里只要预留数据接口生成时把静态数组替换成接口返回就行。更高阶的方向是 3D Gaussian Splatting也就是 3D 高斯泼溅渲染。这种技术本身比较复杂但对 skill 来说它也只是另一个模板方向把数据加载、相机控制、渲染参数固定下来用户需要时替换数据源。也就是说skill 的价值不会局限在“做一个转动的立方体”它同样能承载新一代渲染技术。5. 常见问题排查skill 不生效、页面空白、卡片顿5.1 skill 没有被识别先查路径和描述如果指令发出后Agent 完全忽略你的 skill没有使用对应模板排查顺序是先看 skill 是否放在 Agent 工具能扫描到的目录。路径不对是最常见原因。再看 SKILL.md 的 description 是否足够清晰。描述太模糊Agent 可能认为该 skill 与当前需求无关。看工具日志。大多数 Agent 工具会记录“使用了哪个 skill”的调用信息。最后测试把 description 改成更明确的话比如“当用户提到粒子、3D、Three.js、特效网页时必须使用本 skill”再试一次。这里要注意不同 Agent 工具的 skill 扫描规则不完全一样。我建议以你使用的工具文档为准不要只凭网上的教程猜。5.2 生成页面后空白优先查控制台而不是改代码页面空白是 3D 网页最常见的失败状态。很多人第一反应是“模型生成的代码有问题”然后反复让 Agent 重写其实很多时候问题不在代码而在运行环境。我会按这个顺序排查第一步看浏览器控制台。如果报错信息是THREE is not defined说明 three 模块没有正确加载检查 importmap 和 CDN 是否被拦截。第二步看 Network 面板。确认 three.module.js 是否请求成功是不是网络问题。第三步看页面是否有 canvas 元素。如果有 canvas 但黑屏可能是相机朝向问题或者场景里没有加入任何对象。第四步看动画循环是否启动。如果没有requestAnimationFrame或renderer.render画面永远不会更新。第五步再看参数。粒子数量太大、位置超出相机范围、颜色值写错都可能导致视觉上看起来是空白。这套顺序的目标是先把“环境问题”和“代码问题”区分开。否则你会花很多时间改代码最后发现只是浏览器兼容问题。页面空白时先把浏览器开发者工具打开。结论写在 Console 和 Network 里不要靠猜。5.3 低配置机器上卡顿按优先级调参数如果你在普通笔记本上跑粒子特效感觉掉帧不一定需要换电脑。按优先级做下面这些调整降低粒子数量。默认 5000 改成 2000视觉差异可能不大流畅度提升明显。关闭抗锯齿。把antialias: true改成false。降低设备像素比。在渲染器初始化后设置renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));减少不必要的灯光和阴影。阴影是性能杀手页面是背景特效时通常不需要开阴影。用静态背景色替代复杂的环境贴图。这几个调整里降低粒子数量效果最直接。这里要特别注意低配置能跑不代表适合同时开多个 3D 页面。如果页面中还有后台任务或者打开了多个标签页掉帧是正常现象。5.4 兼容性问题有些功能不是“支持”而是“限定浏览器”Three.js 的大部分功能在现代浏览器上都能运行但某些特性会有兼容性边界。比如 WebGPU 相关的渲染器就需要较新的浏览器WebGL 1 与 WebGL 2 在一些旧设备上表现不同。如果你的目标是活动页、宣传页尽量用兼容性最好的基础渲染方式不要为了炫酷使用冷门扩展。再补充一个实际体验点3D 页面在手机上的表现和电脑差别很大。手机上 GPU 性能弱触控事件与鼠标事件不同如果你的页面只绑定了mousemove会在手机端完全失效。模板里可以同时处理pointermove和touchmove这样兼容性会好很多。6. 让 skill 真正成为生产工具的进阶建议6.1 增加脚本做文件生成和参数校验当 skill 越来越复杂纯靠 Agent 替换 HTML 里的配置区可能不够稳定。这时候可以在 scripts 目录里加一个 Python 或 Node 脚本专门负责“读配置 - 填模板 - 输出文件”。比如用一个 JSON 配置描述所有特效参数脚本自动生成 HTML。这样的好处是流程可重复参数可以版本化管理。示例调用方式可以是python scripts/generate_page.py --template particle_field --config configs/demo_star.json --output output/demo_star.html如果用到了脚本SKILL.md 里就要写清楚什么情况下运行脚本脚本参数是什么输出文件到哪里。Agent 只负责根据用户需求生成 config 文件脚本负责精确生成最终 HTML。这相当于把“模型写代码”和“代码执行”分开了稳定性更高。6.2 把 skill 沉淀成团队规范如果你不是一个人玩而是团队里有多个人都在用 Agent 生成 3D 页面skill 就会变成一种轻量级规范。目录结构统一、命名统一、参数含义统一、排查文档统一。新同学拿到 skill 后不需要从零研究 Three.js也能生成合格的网页。这个价值往往比“生成速度快”更值得关注。我一般在团队里会约定三条硬规则所有 3D 页面必须基于模板生成禁止从零手写。所有参数必须写在页面顶部的配置区禁止散落在代码各处。所有输出必须通过本地静态服务器验证禁止只检查代码不检查渲染效果。有了这些规则skill 就不仅是一个工具而是团队规范的载体。6.3 我的真实经验先守住最小闭环再谈炫酷最后说几句实在话。用过几次 skill 后我的体会是它帮你解决的是“重复劳动被自动化”的问题而不是“创意自动涌现”的问题。3D 特效网页之所以显得炫酷是因为 Three.js 本身能做出很强的视觉冲击力但真正决定页面能不能用的还是场景搭建、相机控制、性能优化这些基础能力。我个人的建议是第一次写 skill 时不要贪多。先做一个 base_scene 模板能生成旋转立方体就说明链路通了。然后再逐步加粒子、加鼠标交互、加多个模板。等这套流程稳定了再考虑批量生成和参数脚本。踩过几次坑以后我也发现很多问题不是 skill 能力不够而是前置条件没有处理干净。路径不对、Node 版本太老、浏览器不支持 importmap、CDN 加载失败这些看起来像“模型不好”的问题实际都是工程问题。先把这些排查清楚了再去调模型指令效率会高很多。