Skip to content

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.

feat(examples): publish the file-defined agent examples under /examples with absolute asset URLs so embeds work off-site

nirholas5d8c0d897436
diff --git a/public/examples/coach-leo/SKILL.md b/public/examples/coach-leo/SKILL.md
new file mode 100644
index 000000000..a79fd30d4
--- /dev/null
+++ b/public/examples/coach-leo/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: Coach Leo
+description: Top-level capability summary of this agent
+---
+
+# Coach Leo — Capabilities
+
+- Wave at users on greetings (via the `wave` skill).
+- Read glTF/body data to comment on your avatar.
+- Remember user context across sessions (memory is local by default).
+- Speak aloud when voice mode is on.
+
+Further skills can be added by setting `skills:` in `manifest.json`.
diff --git a/public/examples/coach-leo/instructions.md b/public/examples/coach-leo/instructions.md
new file mode 100644
index 000000000..d1c9a392b
--- /dev/null
+++ b/public/examples/coach-leo/instructions.md
@@ -0,0 +1,27 @@
+---
+name: Coach Leo
+model: claude-opus-4-6
+temperature: 0.8
+---
+
+You are Coach Leo, a former Argentine midfielder turned football coach. You
+wear the Argentina jersey with pride. You are warm, direct, and genuinely
+invested in the user's progress.
+
+## How you work
+
+- When the user greets you, call `wave()` to wave at them.
+- When they describe a drill or ask about form, set a focused expression
+ with `setExpression({ preset: "focused" })` while you explain, then smile
+ afterward.
+- If the user shares something worth remembering (their position, goals,
+ injuries, schedule), call `remember()` to save it durably.
+- Reference past memory naturally — don't recite, weave it in.
+- Keep replies short in voice mode: 1–2 sentences, then invite the user
+ to respond. Save long explanations for when they ask for depth.
+
+## Your voice
+
+- Direct. No coddling. "That's not quite right — try this instead."
+- Warm. Genuine wins get genuine praise.
+- Never break character.
diff --git a/public/examples/coach-leo/manifest.json b/public/examples/coach-leo/manifest.json
new file mode 100644
index 000000000..dfcb5a7af
--- /dev/null
+++ b/public/examples/coach-leo/manifest.json
@@ -0,0 +1,55 @@
+{
+ "$schema": "https://3d-agent.io/schemas/manifest/0.1.json",
+ "spec": "agent-manifest/0.1",
+ "name": "Coach Leo",
+ "description": "Football coach. Reviews your form, cheers you on.",
+ "image": "https://three.ws/avatars/cz.glb",
+ "tags": [
+ "coach",
+ "football",
+ "argentina"
+ ],
+ "body": {
+ "uri": "https://three.ws/avatars/cz.glb",
+ "format": "gltf-binary",
+ "rig": "mixamo",
+ "boundingBoxHeight": 1.78
+ },
+ "brain": {
+ "provider": "anthropic",
+ "model": "claude-opus-4-6",
+ "instructions": "instructions.md",
+ "temperature": 0.8,
+ "maxTokens": 2048
+ },
+ "voice": {
+ "tts": {
+ "provider": "browser",
+ "rate": 1.05
+ },
+ "stt": {
+ "provider": "browser",
+ "language": "en-US"
+ }
+ },
+ "skills": [
+ {
+ "uri": "../skills/wave/",
+ "version": "0.1.0"
+ }
+ ],
+ "memory": {
+ "mode": "local",
+ "index": "memory/MEMORY.md",
+ "maxTokens": 8192
+ },
+ "tools": [
+ "wave",
+ "lookAt",
+ "play_clip",
+ "setExpression",
+ "speak",
+ "remember"
+ ],
+ "version": "0.1.0"
+}
diff --git a/public/examples/skills/wave/SKILL.md b/public/examples/skills/wave/SKILL.md
new file mode 100644
index 000000000..8e94e29ee
--- /dev/null
+++ b/public/examples/skills/wave/SKILL.md
@@ -0,0 +1,37 @@
+# wave
+
+The starter skill. One tool, ten lines of handler: it plays the built-in `wave`
+gesture, then speaks a greeting. Referenced by
+[examples/coach-leo/manifest.json](../../coach-leo/manifest.json) and walked
+through in the [skills guide](https://three.ws/docs/skills).
+
+| Tool | Use it for |
+|---|---|
+| `waveAndGreet` | Wave + spoken greeting in one call |
+
+## Why it exists
+
+Every skill bundle has the same four files (`manifest.json`, `tools.json`,
+`handlers.js`, `SKILL.md`). This one is intentionally minimal so you can copy
+the directory, rename the tool, and have a working custom skill in minutes. The
+handler shows the two context calls most skills need:
+
+```js
+await ctx.call('wave', {}); // dispatch any built-in or skill tool
+await ctx.speak('Hello!'); // TTS through the agent's configured voice
+```
+
+## Config
+
+`manifest.config.greeting` sets the default line. Callers can override it per
+call with the `greeting` argument.
+
+## Try it
+
+Load Coach Leo (`examples/coach-leo/`) and ask him to say hi, or install the
+skill on any agent and call the tool directly:
+
+```js
+const el = document.querySelector('agent-3d');
+await el.installSkill('/examples/skills/wave/');
+```
diff --git a/public/examples/skills/wave/handlers.js b/public/examples/skills/wave/handlers.js
new file mode 100644
index 000000000..c00323b01
--- /dev/null
+++ b/public/examples/skills/wave/handlers.js
@@ -0,0 +1,10 @@
+// wave — starter skill. Composes two built-in runtime tools into one new tool:
+// the `wave` gesture (src/runtime/tools.js) and `ctx.speak` TTS. Use this as
+// the template for your own skills: same four-file layout as the siblings.
+
+export async function waveAndGreet(args, ctx) {
+ await ctx.call('wave', {});
+ const greeting = args?.greeting ?? ctx?.skillConfig?.greeting ?? 'Hey there!';
+ await ctx.speak(greeting);
+ return { ok: true, data: { waved: true, greeting } };
+}
diff --git a/public/examples/skills/wave/manifest.json b/public/examples/skills/wave/manifest.json
new file mode 100644
index 000000000..8db1ecfaa
--- /dev/null
+++ b/public/examples/skills/wave/manifest.json
@@ -0,0 +1,25 @@
+{
+ "spec": "skill/0.1",
+ "name": "wave",
+ "version": "0.1.0",
+ "description": "Starter skill: wave and greet in one tool call. The smallest useful example of composing built-in runtime tools (wave + speak) into a new skill tool.",
+ "license": "MIT",
+ "tags": [
+ "starter",
+ "gesture",
+ "example"
+ ],
+ "requires": {
+ "runtime": ">=0.1.0",
+ "capabilities": []
+ },
+ "provides": {
+ "tools": [
+ "waveAndGreet"
+ ],
+ "triggers": []
+ },
+ "config": {
+ "greeting": "Hey there! Great to see you."
+ }
+}
diff --git a/public/examples/skills/wave/tools.json b/public/examples/skills/wave/tools.json
new file mode 100644
index 000000000..f8278f146
--- /dev/null
+++ b/public/examples/skills/wave/tools.json
@@ -0,0 +1,17 @@
+{
+ "tools": [
+ {
+ "name": "waveAndGreet",
+ "description": "Play the wave gesture and speak a short greeting. Pass `greeting` to override the default line from the skill config.",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "greeting": {
+ "type": "string",
+ "description": "What to say while waving. Defaults to manifest.config.greeting."
+ }
+ }
+ }
+ }
+ ]
+}
diff --git a/scripts/build-hosted-examples.mjs b/scripts/build-hosted-examples.mjs
new file mode 100644
index 000000000..0de475fd5
--- /dev/null
+++ b/scripts/build-hosted-examples.mjs
@@ -0,0 +1,84 @@
+// Publish the file-defined agent examples to public/ so the web component can
+// load them from any page on the open web.
+//
+// examples/coach-leo/manifest.json is written for a repository reader: its body
+// URI is root-relative (/avatars/cz.glb), which resolves against the HOST page
+// when <agent-3d manifest="..."> runs on someone else's domain. This script
+// copies the tree into public/examples/ and rewrites exactly those references to
+// absolute https://three.ws URLs, so a copy-pasted snippet works off-site.
+//
+// Relative references (instructions.md, ../skills/wave/) are left alone: the
+// runtime resolves them against the manifest URL (src/manifest.js fetchRelative),
+// and the directory layout is preserved here so they keep resolving.
+//
+// Run via `npm run build:examples`. Output is committed, because the production
+// build chain (build:gcp) does not regenerate it.
+
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const ORIGIN = 'https://three.ws';
+const OUT_DIR = join(root, 'public/examples');
+
+// Each entry is a directory copied verbatim except for the rewrites below.
+const TREES = ['examples/coach-leo', 'examples/skills/wave'];
+
+// Manifest fields that must be absolute for an off-site embed to resolve them.
+const ABSOLUTE_FIELDS = [
+ ['body', 'uri'],
+ ['image'],
+];
+
+// README.md is written for a repository reader and nothing at runtime fetches
+// it, so it stays out of the published tree.
+const SKIP = new Set(['README.md']);
+
+function walk(dir, base = dir, out = []) {
+ for (const name of readdirSync(dir)) {
+ const full = join(dir, name);
+ if (statSync(full).isDirectory()) walk(full, base, out);
+ else if (!SKIP.has(name)) out.push(relative(base, full));
+ }
+ return out;
+}
+
+function absolutize(value) {
+ if (typeof value !== 'string' || !value.startsWith('/')) return value;
+ return ORIGIN + value;
+}
+
+function rewriteManifest(text) {
+ const json = JSON.parse(text);
+ for (const path of ABSOLUTE_FIELDS) {
+ let node = json;
+ for (const key of path.slice(0, -1)) node = node?.[key];
+ const leaf = path[path.length - 1];
+ if (node && typeof node === 'object' && leaf in node) node[leaf] = absolutize(node[leaf]);
+ }
+ return JSON.stringify(json, null, '\t') + '\n';
+}
+
+rmSync(OUT_DIR, { recursive: true, force: true });
+
+let files = 0;
+for (const tree of TREES) {
+ const src = join(root, tree);
+ // public/examples/coach-leo, public/examples/skills/wave; the layout under
+ // examples/ is preserved so ../skills/wave/ still resolves from the manifest.
+ const dest = join(OUT_DIR, relative(join(root, 'examples'), src));
+ for (const rel of walk(src)) {
+ const from = join(src, rel);
+ const to = join(dest, rel);
+ mkdirSync(dirname(to), { recursive: true });
+ const raw = readFileSync(from, 'utf8');
+ writeFileSync(to, rel === 'manifest.json' ? rewriteManifest(raw) : raw);
+ files++;
+ }
+}
+
+console.log(
+ `wrote ${files} file(s) to public/examples/ from ${TREES.length} example tree(s); ` +
+ 'body/image URIs rewritten to absolute',
+);