Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(skills): teach agents to check the asset catalog before generating a model
nirholase9f112d58946
diff --git a/.agents/skills/SKILLS.md b/.agents/skills/SKILLS.mdindex 6015c8f31..944ae5b12 100644--- a/.agents/skills/SKILLS.md+++ b/.agents/skills/SKILLS.md@@ -20,6 +20,7 @@ Categories:| --- | --- | --- || [`create-3d-avatar`](create-3d-avatar/SKILL.md) ✅ cross-platform-safe | three.ws | Turn a text prompt (or reference image) into a rigged, animation-ready 3D avatar (GLB). Use when you or the user want to create, generate, or make a 3D avatar, character, or humanoid figure that can be posed and animated — "make a 3D avatar of a knight", "generate a character I can animate", "create a rigged astronaut". Generates the mesh and adds a humanoid skeleton in one step. Returns a GLB URL plus a pose-studio link. || [`embed-three-ws-avatar`](embed-three-ws-avatar/SKILL.md) ✅ cross-platform-safe | three.ws | Embed a live, animated three.ws 3D avatar in any website with the <agent-3d> web component. Use when you or the user want to embed, integrate, add, or show a 3D avatar, character, or agent on a site or app ("embed a 3D avatar on my site", "add an animated character to my landing page", "integrate three.ws", "put an avatar in my hero section"), wire avatar animations or moods from page code, let users design an avatar in the three.ws Avatar Studio from inside another app, or debug an existing agent-3d embed. |+| [`find-3d-assets`](find-3d-assets/SKILL.md) ✅ cross-platform-safe | three.ws | Search 3,492 ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app ("I need a 3D chair", "find a rigged character", "is there a wave animation", "add a lamp model to my page"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch. || [`generate-3d-model`](generate-3d-model/SKILL.md) ✅ cross-platform-safe | three.ws | Turn a text prompt into a downloadable, textured 3D model (GLB). Use when you or the user want to generate, create, make, or forge a 3D model, asset, object, mesh, or prop from a text description — "make a 3D model of a robot", "generate a GLB of a sword", "I need a 3D chair". Runs on the FREE text→3D lane (no key, no account, free). Returns a GLB URL plus a browser viewer link. || [`rig-a-model`](rig-a-model/SKILL.md) ✅ cross-platform-safe | three.ws | Auto-rig a static 3D GLB model into an animation-ready one. Use when you or the user have an existing GLB and want to rig it, add a skeleton, add bones, make it posable, or make it animatable — "rig this model", "add a skeleton to my GLB", "make this character animation-ready". Takes a GLB URL, adds a humanoid skeleton plus skin weights, and returns the rigged GLB URL and a pose-studio link. |diff --git a/.agents/skills/find-3d-assets/SKILL.md b/.agents/skills/find-3d-assets/SKILL.mdnew file mode 100644index 000000000..c83084ff3--- /dev/null+++ b/.agents/skills/find-3d-assets/SKILL.md@@ -0,0 +1,141 @@+---+name: find-3d-assets+description: Search 3,492 ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app ("I need a 3D chair", "find a rigged character", "is there a wave animation", "add a lamp model to my page"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch.+when_to_use: Something needs a 3D asset and a ready-made one would do. If the catalog has no match, fall through to generate-3d-model (props) or create-3d-avatar (characters). To put an asset you already have on a page, use embed-three-ws-avatar.+license: MIT+metadata:+ category: 3d/creative+ cross-platform-safe: true+ pack: three-ws-skills+---++# Find a ready-made 3D asset++three.ws publishes three asset libraries and joins them into one searchable catalog:++| Kind | What it is | How many |+| --- | --- | --- |+| `object` | CC0 props and objects (furniture, lighting, tools, electronics, decor) staged as web GLB | 511 |+| `character` | Ready-made rigged humanoids, animation-ready out of the box | 107 |+| `animation` | Retargetable motion clips as `THREE.AnimationClip` JSON | 2,874 |++Everything here is **free and public**: no account, no API key, no payment, no rate card.++## Check the catalog before you generate++Generating a model takes GPU minutes and returns something nobody has reviewed. The catalog+returns a finished, textured asset instantly. So the order is:++1. Search the catalog. If something fits, use it. Done.+2. Nothing fits, and it is a **prop or object**? Use `generate-3d-model`.+3. Nothing fits, and it is a **character**? Use `create-3d-avatar`.++Say which one you did. "I found an existing CC0 chair" and "I generated a chair" are+different answers and the user should know which they got.++## The fastest path: MCP tools++If the three.ws MCP server is connected, three free tools cover the whole flow:++| Tool | Use |+| --- | --- |+| `search_catalog` | Find assets by text, `kind`, `category`, or `tag` |+| `get_catalog_item` | One item in full, with links and related items |+| `get_item_source` | Paste-ready code for one item |++```+search_catalog { "q": "wooden chair", "kind": "object", "limit": 5 }+get_item_source { "id": "object:painted_wooden_chair_01" }+```++Not connected? Add it:++```json+{ "mcpServers": { "three-ws": { "type": "http", "url": "https://three.ws/api/mcp" } } }+```++## Without MCP: the HTTP endpoint++```bash+curl -s 'https://three.ws/api/catalog?q=industrial+lamp&kind=object&limit=5'+curl -s 'https://three.ws/api/catalog?id=object:painted_wooden_chair_01'+```++The search form returns `items[]` with `id`, `title`, `tags`, `license`, `url` (the CDN GLB or+clip JSON), `thumb`, and `facets` you can use to narrow the next query. The `id` form adds+`links`, `related`, and `snippets` for every framework that applies.++Search semantics worth knowing: **every word must match** something, which keeps a two-word+query precise. If nothing matches all of them, the response comes back with `relaxed: true`+and the partial matches, best first. Check that flag before telling a user you found an exact+match.++## Putting it in a project: the CLI++```bash+npx @three-ws/assets search wooden chair --kind object+npx @three-ws/assets add object:painted_wooden_chair_01+```++`add` downloads the GLB into `public/three-ws/` (or `three-ws-assets/` when the project has no+`public/` directory) and prints the snippet **already rewritten to the local path**, so the+host site does not depend on the three.ws CDN staying up.++It is safe to re-run: identical bytes report as already up to date, and a file edited after it+was added is never overwritten without `--force`.++Useful flags: `--dir <path>`, `--framework <f>`, `--thumb`, `--json`.++## Which framework to emit++`get_item_source` (and `show`/`add` in the CLI) default to the right one per kind. Override+with `framework` only when the project dictates it.++| Framework | Emits | Default for |+| --- | --- | --- |+| `model-viewer` | The `<model-viewer>` tag, build, and integrity hash the three.ws browse grids render with | props |+| `agent-3d` | The `<agent-3d>` web component, pinned to the exact published version with its SRI hash | rigged characters |+| `three` | Plain three.js: `GLTFLoader` for a model, `THREE.AnimationClip.parse` for a clip | motion clips |+| `react` | The same as a React component, or a hook for a clip | React projects |+| `all` | Every applicable variant in one response | when you are choosing |++The `agent-3d` snippet is never pinned to `latest`, because `latest` can change under the+reader with no action on their side. Keep the version and the `integrity` attribute intact+when you paste it.++## Worked example++User: *"put a chair on the landing page"*++```+search_catalog { "q": "wooden chair", "kind": "object", "limit": 3 }+```++```+10 matches for "wooden chair" (showing 3 from offset 0):+- `object:painted_wooden_chair_01` | Painted Wooden Chair 01 | CC0 | chair, wood, painted+- `object:painted_wooden_chair_02` | Painted Wooden Chair 02 | CC0 | old, wooden, vintage+- `object:WoodenChair_01` | Wooden Chair 01 | CC0 | wood, prop, vintage+```++```+get_item_source { "id": "object:painted_wooden_chair_01" }+```++Returns the `<model-viewer>` block to paste, the preview link, and the license (`CC0`). Paste+it, tell the user which asset you used and that it is public domain, and link the preview so+they can look at it before shipping.++## Licensing++Every `object` in the library is **CC0**: public domain, commercial use fine, no attribution+required. Characters and clips carry their own `license` field, which travels with every+response. Read it and pass it on; do not assume CC0 outside the object library.++## Related skills++- `generate-3d-model` when the catalog has no match for a prop.+- `create-3d-avatar` when the catalog has no match for a character.+- `embed-three-ws-avatar` for the full `<agent-3d>` embedding story, including moods,+ animations, and driving the avatar from page code.+- `rig-a-model` to add a skeleton to a static GLB you already have.diff --git a/.agents/skills/skills-pack.json b/.agents/skills/skills-pack.jsonindex 1b274124a..5cb8d1485 100644--- a/.agents/skills/skills-pack.json+++ b/.agents/skills/skills-pack.json@@ -10,7 +10,7 @@"intel/trading": "Market data, trading signals, DEX/DeFi execution."},"counts": {- "3d/creative": 4,+ "3d/creative": 5,"intel/trading": 13,"ops/production": 1,"wallet/payments": 24@@ -34,6 +34,15 @@"crossPlatformSafe": true,"path": ".agents/skills/embed-three-ws-avatar"},+ {+ "name": "find-3d-assets",+ "description": "Search 3,492 ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app (\"I need a 3D chair\", \"find a rigged character\", \"is there a wave animation\", \"add a lamp model to my page\"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch.",+ "whenToUse": "Something needs a 3D asset and a ready-made one would do. If the catalog has no match, fall through to generate-3d-model (props) or create-3d-avatar (characters). To put an asset you already have on a page, use embed-three-ws-avatar.",+ "category": "3d/creative",+ "origin": "three.ws",+ "crossPlatformSafe": true,+ "path": ".agents/skills/find-3d-assets"+ },{"name": "generate-3d-model","description": "Turn a text prompt into a downloadable, textured 3D model (GLB). Use when you or the user want to generate, create, make, or forge a 3D model, asset, object, mesh, or prop from a text description — \"make a 3D model of a robot\", \"generate a GLB of a sword\", \"I need a 3D chair\". Runs on the FREE text→3D lane (no key, no account, free). Returns a GLB URL plus a browser viewer link.",diff --git a/data/changelog.json b/data/changelog.jsonindex b02f6eaf8..71ad08798 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-09-05",+ "title": "A new agent skill teaches Claude to look for an existing 3D asset before making one",+ "summary": "find-3d-assets joins the three.ws Agent Skills pack. It tells an AI assistant that the platform already publishes 3,492 finished 3D assets and how to search them, so a request like put a chair on my landing page gets an existing CC0 chair in seconds instead of a generation job that takes GPU minutes and produces something nobody has looked at. The skill covers all three ways in (the free MCP tools, the plain HTTP endpoint, and the command line), which framework to emit for each kind of asset, and how to read the license that travels with every result. It also says plainly when to give up on the catalog and generate instead, and to tell the user which of the two they got.",+ "tags": [+ "feature",+ "docs"+ ],+ "link": "/docs/agent-skills"+ },{"date": "2026-09-05","title": "One command drops a three.ws prop, character or motion clip into your project",diff --git a/docs/agent-skills.md b/docs/agent-skills.mdindex b4b288f65..a3218660c 100644--- a/docs/agent-skills.md+++ b/docs/agent-skills.md@@ -26,7 +26,7 @@ Three categories:| Category | Skills | Notes || --- | --- | --- |-| **3d/creative** | `generate-3d-model`, `create-3d-avatar`, `rig-a-model` | Text→GLB on the free lane, one-call rigged avatars, auto-rigging. **Cross-platform-safe**: zero coin/wallet/payment content, so this subset is reusable on non-Claude tracks (OpenAI, etc.). |+| **3d/creative** | `find-3d-assets`, `generate-3d-model`, `create-3d-avatar`, `rig-a-model` | Text→GLB on the free lane, one-call rigged avatars, auto-rigging. **Cross-platform-safe**: zero coin/wallet/payment content, so this subset is reusable on non-Claude tracks (OpenAI, etc.). || **wallet/payments** | `authenticate-wallet`, `fund`, `send-usdc`, `trade`, `search-for-service`, `pay-for-service`, `monetize-service`, `query-onchain-data`, `x402`, `metamask-agent-*`, okx wallet/identity set | The x402 agent-economy set. Never bundle these on non-crypto tracks. || **intel/trading** | okx dex/defi market-data and execution set | Vendored partner skills (byte-identical to the vendor drop; categorized only in the pack manifest). |@@ -92,6 +92,12 @@ option / skills directory the SDK exposes.The platform's signature set, safe to reuse anywhere:+- **`find-3d-assets`**: search the 3,492 ready-made assets three.ws already+ publishes (511 CC0 props, 107 rigged characters, 2,874 motion clips) and get+ paste-ready code or a downloaded file. Free, and the one to try FIRST: an+ existing asset is instant where a generation is GPU minutes. Reachable three+ ways off one catalog (the `search_catalog` / `get_catalog_item` /+ `get_item_source` MCP tools, `GET /api/catalog`, or `npx @three-ws/assets`).- **`generate-3d-model`** — text → textured GLB on the free `forge_free` lane(NVIDIA NIM / TRELLIS; no key, no account). Returns `glbUrl` + viewer link.- **`create-3d-avatar`** — text/image → **rigged** avatar via `forge_avatar`@@ -101,7 +107,7 @@ The platform's signature set, safe to reuse anywhere:`POST /api/forge?action=rig` (Make-It-Animatable). Returns `riggedGlbUrl` +pose-studio link.-All three run free against the hosted studio endpoint+The three generation skills run free against the hosted studio endpoint`https://three.ws/api/mcp-studio` (JSON-RPC `tools/call`), documented with runnable`curl` examples inside each skill.