Guide · Agent skill
How to use the 3D Ultra-Realistic Water agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains what the 3d-ultra-realistic-water agent skill does, how to install it, and how to ask your agent for an open sea in a Three.js scene. It is written for people who have not used agent skills before. By the end you will know what the skill needs, how to trigger it, and which settings prevent common water artifacts.
3D Ultra-Realistic WaterMengTo/Skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page. Keep the folder structure intact when you unzip it.
- 2Place the skill. Unzip into ~/.claude/skills/ for personal use, into .claude/skills/ for one project, or upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
- 3Confirm Three.js is available. Make sure your host project supplies Three.js with WebGL2 support. The skill does not include its own copy.
- 4Ask for the water in plain language. Describe the scene, such as a sunset sea with a moving camera and a ship. Mention the wake or glitter if you want them.
- 5Copy and wire the module. Let the agent copy assets/ocean.mjs into your project and set up the per-frame order from references/ocean.md.
- 6Compare with the demo. Open demo/index.html in a WebGL2 browser to check the look against the reference scene before you tune it.
What an agent skill is and what this one makes the agent do
An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches it. This skill, named 3d-ultra-realistic-water, teaches the agent a tested recipe for rendering a believable open sea in Three.js, the JavaScript 3D library.
With the skill installed, the agent knows how to build waves from a deep-water Gerstner spectrum, shade them per pixel, add sun glitter, reflections, foam, a ship wake and horizon haze, and it knows which settings avoid shimmering in the distance. It can wire these into a reusable water module at assets/ocean.mjs.
- Eight Gerstner waves with per-pixel shading from analytic derivatives
- Fresnel reflections from a sky cube and a planar reflection for ships and islands
- Subsurface light through the wave crests and HDR sun glitter for bloom
- Jacobian-driven lace foam, hull foam and a Kelvin ship wake
- Buoyancy height queries on the same wave function, and aerial perspective into the sky's horizon haze
Install the skill in Claude or in your project
Download the ZIP from this page. You then have two options. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
- Personal: unzip into ~/.claude/skills/
- Per project: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check what you need before you start
The module expects Three.js to be supplied by your host project. The skill does not bring its own copy, so pass in your project's THREE object. The demo needs a browser or another WebGL2-capable renderer. If you want to rebuild the demo, you also need Node.js to run demo/build.mjs and the Pirate Ship Sunset reference HTML file.
The skill is aimed at Three.js projects. It is not designed for other web libraries or for native game engines.
- Three.js with WebGL2 support, provided by your project (check references/ocean.md for the minimum release)
- A browser or WebGL2-capable renderer to view the demo
- Node.js, only if you rebuild the demo with demo/build.mjs
- A Pirate Ship Sunset reference HTML file, only for rebuilding the demo
Trigger the skill with natural requests
You do not need special syntax. Describe the scene you want and mention water, a sea, sunset light or a ship. The skill's description lists the kinds of work it covers, including seas, oceans, sunset or daylight water, sun glitter paths, ship or boat scenes, wakes, coastal flyovers and any 3D scene with a moving camera and a water horizon.
The demo prompt in demo/PROMPT.md is a good template. It asks for the 8-wave spectrum, per-pixel shading, a sky cube reflection, subsurface light, sun glitter and lacy foam, with fog matched to the sky's horizon.
- Add an open ocean to this Three.js scene with sun glitter and a horizon.
- Add a sunset sea behind my boat, with a wake trailing the stern and a moving camera.
- Use the water module from the skill to add reflections and foam to this harbour scene.
- Make the far water stop shimmering as the camera flies toward the horizon.
Use the water module in your scene
Copy assets/ocean.mjs into your project. Before you integrate it, read references/ocean.md, which lists the constants, render order, buoyancy and post-processing details. The example below shows the core setup. Every frame, the waves update first, buoyancy reads the same heights, then the ocean, wake and reflection are rendered in order.
The demo at demo/index.html runs the same module inside the original scene, so you can compare your output against it.
import { createWaves, bakeOceanDetail, createOcean, createWake, createPlanarReflection } from './ocean.mjs';
const waves = createWaves({ direction: 1.22 });
const ocean = createOcean(THREE, { waves, detailTexture: bakeOceanDetail(THREE, renderer), skyCube, hazeGLSL: SKY_GLSL + 'vec3 oceanHaze(vec3 d){ return hazeColor(d); }', hazeUniforms: skyUniforms });
scene.add(ocean.mesh);
waves.update(dt);
ship.y = waves.height(ship.x, ship.z);
ocean.update({ time, camera, ship: { x, z, fx, fz } });
renderer.render(scene, camera);Avoid the artifacts the rules are written to prevent
The skill's rules were A/B tested in the demo scene. Each one addresses a specific failure. Keep them in place when you adapt the module.
Fading each wave at its own footprint stops the far sea from boiling into moiré. Shading from analytic derivatives keeps glitter sharp. Keeping the sum of steepness values below 1 stops the surface folding through itself. Clamping the reflection vector above the horizon stops dark or pale smears on wave backs.
- Fade every wave at its own footprint in both the vertex and fragment shaders
- Compute the normal in the fragment shader from the analytic derivatives
- Keep the sum of steepness values below 1 (setSeaState caps it at 0.95)
- Clamp the reflection vector: R.y = abs(R.y) + 0.002
- Fog into the same haze function the sky draws
- Query height with the same spectrum you render
What people use it for
- A three-masted ship sailing a rolling sea at sunset in a single-file Three.js scene, with an auto-cycling camera.
- A harbour or coastal flyover where the camera moves over water toward a visible horizon.
- A ship or boat scene with a Kelvin wake and hull foam that follows the vessel's motion.
- A daylight sea with sun glitter paths, used as a reference for physically motivated water shading.
Frequently asked questions
How do I install the 3D Ultra-Realistic Water agent skill?
Download the ZIP from this page. Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can instead upload the ZIP under Settings, Capabilities, Skills.
Is the 3D Ultra-Realistic Water skill free to use?
The skill is licensed under the MIT licence, as listed on this page. Check the licence file in the download for the full terms before you use it in a commercial project.
What do I need to run the water effect?
You need Three.js with WebGL2 support, supplied by your host project, and a WebGL2-capable browser to view the demo. Node.js is only needed if you rebuild the demo with demo/build.mjs, which also needs the Pirate Ship Sunset reference HTML file.
Does the skill run scripts or use the network?
According to the skill's listing, it does not run scripts and does not use the network. The only script is demo/build.mjs, which is for rebuilding the demo with Node.js, not for the water effect itself.
Can I use this skill for a flat or mirror-like lake?
Probably not. The skill itself says that for mirror-flat water seen from the waterline with no mesh, a full-screen analytic water plane is cheaper. For ripples on a UI surface, use shaders-cursor-ripples instead.
Why does the far water shimmer or boil in my scene?
The skill fades each wave out once its wavelength falls below the pixel footprint, in both shaders. Make sure you keep that fade in place, and keep the rest of the rules, such as the fog matching the sky's haze.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build 3D ocean, sea or harbour scenes in Three.js and want a tested, physically motivated water recipe with a reusable module and a rebuildable demo. Pick something else if you need flat or mirror-like water, a non-Three.js engine, or ready-made gameplay physics, since buoyancy here is only a height query on the same wave function.
Download the skill