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(skills): publish the 3D skills as a public download, not just a submission upload

nirholasbc757af3aaa7
diff --git a/.agents/skills/embed-three-ws-avatar/SKILL.md b/.agents/skills/embed-three-ws-avatar/SKILL.md
index 50a79ae79..088a96284 100644
--- a/.agents/skills/embed-three-ws-avatar/SKILL.md
+++ b/.agents/skills/embed-three-ws-avatar/SKILL.md
@@ -107,10 +107,11 @@ el.addEventListener('agent:ready', async () => {
await el.say('Welcome!'); // speech bubble + talk animation (works with brain="none")
await el.speak('Welcome!'); // spoken TTS variant
});
-// el.pause() / el.resume() for tab-visibility or carousel logic
-// el.destroy() on unmount (call from your framework's cleanup hook)
```
+Lifecycle: call `el.pause()` and `el.resume()` for tab-visibility or carousel
+logic, and `el.destroy()` on unmount, from your framework's cleanup hook.
+
Theming: the element reads CSS custom properties, led by `--agent-accent`, so
you can match it to your brand color per instance:
`el.style.setProperty('--agent-accent', '#b8ff2e')`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6050d8f2..545fed69a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-09-11
- **Selfie to avatar is unstuck: a scan that used to wait forever now finishes in seconds**: Uploading a photo on the selfie page could sit on the same message indefinitely and never start the scan, with no error and nothing to retry. One copy of the face-tracking runtime held at our CDN was telling browsers to expect 11 MB and then sending a third of that, so the page waited for bytes that were never coming. That copy is gone, and three changes make the failure impossible to repeat silently: the face-tracking runtime now loads from three.ws first instead of a public CDN, any wait on it gives up after fifteen seconds and builds your avatar from the photo as it is, and a photo is never rejected for having no face in it just because the detector could not load. A new check also walks every large file on the site the way a browser asks for it and fails loudly when the bytes do not add up. Measured after the fix: a selfie became a rigged, animation-ready avatar in about fifteen seconds, and still finished in under a minute with the face-tracking runtime completely unreachable. (`/create/selfie`) `[fix, infra]`
+- **The 3D creation skills are now a public download**: The skills that teach an AI agent when and how to generate, rig, and embed 3D models on three.ws used to live only inside this repo. Four of them are now published at three.ws/skills/3d-studio: read one straight from the web, or download the whole set as a zip and drop it into whatever agent you are building. Nothing there needs an account, an API key, or a payment. A skill is only included if every tool it tells an agent to call is actually served, so a downloaded skill cannot send an agent after something that does not exist. (`/docs/agent-skills`) `[feature, sdk]`
- **Your selfie avatar now survives a storage outage instead of vanishing at the last step**: For part of today, a selfie could finish building and then be thrown away. The 3D model was generated correctly, but the step that files it into your library could not reach our object storage, so the page said the avatar finished and could not be saved, and trying again hit the same wall. The avatar was never actually lost: a complete copy sits with the service that built it. The last step now recognises a storage outage for what it is and keeps your avatar, serving it from that copy and flagging it to be filed away properly once storage is back, so a problem on our side costs a housekeeping step instead of the model you waited for. Anything that is not a storage outage still fails loudly rather than quietly papering over a real bug. The image API for agents also now answers with a clear temporarily unavailable instead of a generic failure, so it no longer reads as a bad prompt when nothing was wrong with the prompt. (`/create/selfie`) `[fix, infra]`
## 2026-09-10
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 36c805d84..d9c12a931 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -215,7 +215,7 @@ bottom.
| Cross-chain SDKs | [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk) | Published | Cross-chain agent SDKs |
| MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 7 hosted remote (50 total, incl. the free `/api/mcp-studio` 3D Studio), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |
| Awesome 3D Agents (curated list) | Source [data/awesome.json](data/awesome.json), generator [scripts/build-awesome.mjs](scripts/build-awesome.mjs) (`npm run build:awesome`, drift-gated by `npm run check:awesome`, publishable mirror via `npm run awesome:standalone`), outputs [awesome/README.md](awesome/README.md) + [public/awesome.json](public/awesome.json), page [pages/awesome.html](pages/awesome.html) `-> /awesome`, link checker [scripts/check-awesome-links.mjs](scripts/check-awesome-links.mjs) (`npm run awesome:links`) | Live | An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass `npx awesome-lint`: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by [tests/awesome-list.test.js](tests/awesome-list.test.js). Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so `--standalone` emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: [awesome/CONTRIBUTING.md](awesome/CONTRIBUTING.md) |
-| Agent Skills pack | [.agents/skills/](.agents/skills) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json) | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json) | 40 portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface — 3d/creative (cross-platform-safe), wallet/payments, intel/trading. Regenerate manifest: `node scripts/build-skills-pack.mjs`. Docs: [docs/agent-skills.md](docs/agent-skills.md) |
+| Agent Skills pack | [.agents/skills/](.agents/skills) (canonical) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json); published 3D subset [public/skills/3d-studio/](public/skills/3d-studio) `→ /skills/3d-studio/` | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json); 3D subset live on the site | 43 portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface: 3d/creative (cross-platform-safe), wallet/payments, intel/trading. The 3d/creative ones are also published as a public, downloadable bundle at `/skills/3d-studio/` (`three-ws-3d-skills.zip`), which is what an OpenAI Plugin Directory submission uploads on its Skills tab; a skill referencing a tool [api/_mcp-studio/](api/_mcp-studio) does not declare is dropped rather than shipped as a dead path. Regenerate manifest: `node scripts/build-skills-pack.mjs`; regenerate the published bundle: `npm run build:openai-skills` (drift gate `npm run check:openai-skills`, wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) |
| Claude Code plugin marketplace | [marketplace/](marketplace) → plugins [three-ws-3d](marketplace/plugins/three-ws-3d), [three-ws-developer](marketplace/plugins/three-ws-developer) | In-repo · installable via `/plugin marketplace add nirholas/three.ws` | 3D generation + rigged avatars inside Claude Code (free lane + paid x402 tools) and developer tooling for building on three.ws. Index: [marketplace/README.md](marketplace/README.md) |
| SNS naming + pay-by-name | [api/sns.js](api/sns.js), [api/sns-subdomain.js](api/sns-subdomain.js), [api/threews/subdomain.js](api/threews/subdomain.js), [api/x402/pay-by-name.js](api/x402/pay-by-name.js), [src/solana/sns-subdomain.js](src/solana/sns-subdomain.js), [pages/threews-claim.html](pages/threews-claim.html) | In-repo | `*.threews.sol` subdomain mint, x402 payments addressed by name. Env: `THREEWS_SOL_PARENT_SECRET_BASE58` |
| Self-hosted x402 facilitator + ring economy | [api/x402-facilitator/[action].js](api/x402-facilitator/[action].js), [api/_lib/x402/self-facilitator.js](api/_lib/x402/self-facilitator.js), [api/x402/ring-settle.js](api/x402/ring-settle.js), [api/_lib/x402/pipelines/ring-rebalance.js](api/_lib/x402/pipelines/ring-rebalance.js), [api/x402-ring.js](api/x402-ring.js), [scripts/x402-ring-setup.mjs](scripts/x402-ring-setup.mjs) | In-repo (off by default) | Closed-loop agent-to-agent x402: platform wallets pay platform endpoints, settled in-house (no external facilitator). Fee-minimized, SOL-floor guarded, internal-labeled. Env: `X402_SELF_FACILITATOR_ENABLED`, `X402_FEE_PAYER_SECRET_BASE58`, `X402_TREASURY_SECRET_BASE58`. See [docs/x402-ring-economy.md](docs/x402-ring-economy.md) |
diff --git a/data/changelog.json b/data/changelog.json
index 65c0fbc44..d997cbff3 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -28136,6 +28136,16 @@
"improvement",
"infra"
]
+ },
+ {
+ "date": "2026-09-11",
+ "title": "The 3D creation skills are now a public download",
+ "summary": "The skills that teach an AI agent when and how to generate, rig, and embed 3D models on three.ws used to live only inside this repo. Four of them are now published at three.ws/skills/3d-studio: read one straight from the web, or download the whole set as a zip and drop it into whatever agent you are building. Nothing there needs an account, an API key, or a payment. A skill is only included if every tool it tells an agent to call is actually served, so a downloaded skill cannot send an agent after something that does not exist.",
+ "tags": [
+ "feature",
+ "sdk"
+ ],
+ "link": "/docs/agent-skills"
}
]
}
diff --git a/docs/agent-skills.md b/docs/agent-skills.md
index af68e18b9..e7e501f86 100644
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -88,33 +88,45 @@ option / skills directory the SDK exposes.
- After adding or editing a skill, regenerate the manifest:
`node scripts/build-skills-pack.mjs` (CI-style check: `--check`).
-### d) Packaged for the OpenAI Plugin Directory
+### d) Downloaded from three.ws, no clone
-OpenAI's Skills tab takes a zip whose root holds one directory per skill, each
-with its own `SKILL.md`. That is already the shape of `.agents/skills/`, so the
-bundle is derived rather than hand-assembled:
+The 3D skills are published as a public directory anyone can read or fetch:
```bash
-npm run build:openai-skills # writes dist-skills/openai-plugin-skills.zip
-npm run build:openai-skills -- --check # verify only, write nothing
+curl -O https://three.ws/skills/3d-studio/three-ws-3d-skills.zip # the whole set
+curl https://three.ws/skills/3d-studio/generate-3d-model/SKILL.md # just one
```
-The builder takes only the skills whose frontmatter declares
-`metadata.category: 3d/*` and `cross-platform-safe: true`, because a 3D plugin
-shipping the pack's wallet and exchange skills reads as unfocused against
-OpenAI's guidance to keep instructions scoped to the plugin's purpose.
-
-It then does the check that matters: it reads the live tool list from
-`https://three.ws/api/mcp-studio` and **drops any skill that tells the model to
-call a tool the connector does not expose.** Inside ChatGPT there is no shell, so
-a skill's `curl` fallback is unreachable and a missing tool is simply a dead
-path. `find-3d-assets` is excluded today for exactly that reason: its
-`search_catalog` / `get_catalog_item` / `get_item_source` tools live on the full
-MCP server, not on the hosted studio endpoint. Ship those three on mcp-studio and
-the skill rejoins the bundle with no edit to the builder.
-
-Packaged Markdown is normalized to the repo's dash rule on the way into the zip;
-the canonical files under `.agents/skills/` are never rewritten.
+That directory, [`public/skills/3d-studio/`](../public/skills/3d-studio/), is
+generated from `.agents/skills/` and tracked in git, so it is browsable on GitHub
+and served from the site. The zip is also exactly what an OpenAI Plugin Directory
+submission uploads on its Skills tab.
+
+```bash
+npm run build:openai-skills # regenerate it
+npm run check:openai-skills # fail if it drifted (wired into npm run gate)
+```
+
+Two rules the builder enforces, both of which change what ships:
+
+**Scope.** Only skills whose frontmatter declares `metadata.category: 3d/*` and
+`cross-platform-safe: true` are published. The pack's wallet and exchange skills
+are not part of a 3D bundle, and OpenAI's packaging guidance asks for
+instructions scoped to the plugin's purpose.
+
+**No dead paths.** The builder reads the tool names
+[`api/_mcp-studio/`](../api/_mcp-studio/) declares and drops any skill that
+references one the endpoint does not serve. When run online it first checks that
+the live endpoint and this checkout agree on the tool surface, and fails if they
+do not, because that disagreement means production is running different code.
+`find-3d-assets` is excluded today on the first rule: its `search_catalog` /
+`get_catalog_item` / `get_item_source` tools live on the full MCP server, not on
+the hosted studio endpoint, and inside ChatGPT there is no shell to reach the
+skill's `curl` fallback. Ship those three on mcp-studio and the skill rejoins the
+bundle with no edit to the builder.
+
+Published Markdown follows the repo's dash rule; the canonical files under
+`.agents/skills/` are never rewritten.
## The 3D-creation skills
diff --git a/package.json b/package.json
index 10823ac94..f67f5757d 100644
--- a/package.json
+++ b/package.json
@@ -230,7 +230,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
"audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",
@@ -431,6 +431,7 @@
"pump:launch:ui": "node scripts/pump-launch-server.mjs",
"seed:skills": "node scripts/seed-skills.js",
"build:openai-skills": "node scripts/build-openai-skills-bundle.mjs",
+ "check:openai-skills": "node scripts/build-openai-skills-bundle.mjs --check",
"build:skills-seed": "node scripts/build-skills-seed.mjs",
"check:skills-seed": "node scripts/build-skills-seed.mjs --check",
"install:sdk": "npm install --prefix agent-payments-sdk && npm run build --prefix agent-payments-sdk && npm install ./agent-payments-sdk",
diff --git a/prompts/store-submissions/_generated/openai-submission.md b/prompts/store-submissions/_generated/openai-submission.md
index 1a774c72d..137e7aa1b 100644
--- a/prompts/store-submissions/_generated/openai-submission.md
+++ b/prompts/store-submissions/_generated/openai-submission.md
@@ -603,28 +603,73 @@ annotation justifications written, and changing the tool surface now would inval
### Step 5. Testing
-At least five positive cases and three negative ones. Every behaviour below is documented in
-§5 and was verified live; none of it is aspirational.
-
-**Positive**
-
-| # | Prompt | Expected result |
-|---|---|---|
-| 1 | `Make a 3D model of a friendly round robot mascot, glossy white plastic.` | Inline interactive 3D viewer with the textured model, plus Download, Spin, Recenter and Open in three.ws. The widget frames the model, casts a soft ground shadow, and auto-rotates until dragged |
-| 2 | `Generate a low-poly treasure chest with iron bands.` | Same viewer flow, returns a downloadable GLB |
-| 3 | `Create a 3D avatar of a space explorer in a white-and-orange suit.` | Avatar generated and rendered inline |
-| 4 | `Make a rigged, animation-ready knight character I can pose.` | Rigged GLB, and an idle animation plays in the viewer |
-| 5 | `Now make that robot's shell matte instead of glossy.` | The model is refined from the previous turn and the updated GLB replaces it in the viewer |
+The portal asks for exactly five test cases and exactly three negative ones, and each test
+case has four fields: Scenario, User prompt, Tool triggered, Expected output.
+
+**Read "negative" the way the portal means it.** It is not a safety refusal and not a
+malformed input. It is a prompt where this plugin should NOT be invoked at all, "but the model
+may mistakenly think it is relevant". Our safety and bad-URL behaviour is real and is
+documented in §2.4 and §5, but putting it here answers a question nobody asked and wastes all
+three slots. Every tool named below was confirmed against a live `tools/list` on 2026-09-12.
+
+**Test case 1. Generate a 3D prop from a text description**
+
+- Prompt: `Make a 3D model of a friendly round robot mascot, glossy white plastic.`
+- Tool: `forge_free`, then `check_job` if the first response returns status "pending"
+- Expected: an inline interactive 3D viewer with the textured model, plus Download, Spin,
+ Recenter and Open in three.ws. The widget frames the model, casts a soft ground shadow and
+ auto-rotates until dragged. Free, no account. Roughly one to four minutes; past the inline
+ wait the tool returns a `job_id` and `check_job` collects the finished model.
+
+**Test case 2. Generate a rigged, animation-ready character**
+
+- Prompt: `Make a rigged, animation-ready knight character I can pose.`
+- Tool: `forge_avatar`, then `check_job` if pending
+- Expected: a rigged GLB in the same viewer, humanoid skeleton and skin weights already
+ applied, so an idle animation plays instead of a bind pose. One call does mesh and rig.
+
+**Test case 3. Iterate on a model by describing the change**
+
+- Prompt, in the same conversation as case 1: `Now make that robot's shell matte instead of
+ glossy.`
+- Tool: `refine_model`
+- Expected: a new version anchored to the previous model rather than an unrelated
+ regeneration, replacing the GLB in the viewer. The prior version stays reachable, so the
+ change is revertable.
+
+**Test case 4. Let the assistant see a model and report on it**
+
+- Prompt: `Look at this 3D model and tell me what it is and whether it has any obvious
+ defects: https://three.ws/cdn/objects/polyhaven/glb/ArmChair_01.glb`
+- Tool: `look_at_model`
+- Expected: frames from several angles returned as MCP image content blocks, which the client
+ renders into the conversation, plus geometry stats (triangles, materials, textures). The
+ assistant describes the armchair from images it can actually see. Free, seconds not minutes.
+ The URL is on our own domain and needs no credentials, so the case is self-contained.
+
+**Test case 5. Turn a model into a persistent agent body that speaks**
+
+- Prompt, in the same conversation as case 2: `Save that knight as a persistent agent body
+ called Sir Gareth, then have him introduce himself.`
+- Tools: `create_agent_persona`, then `persona_say`
+- Expected: an inline living-body widget framed from `https://three.ws`, our own verified
+ domain and the same origin as the connector, in which the avatar lip-syncs the line with a
+ matching expression and gesture and idles between turns. Returns a `persona_id` that
+ `get_agent_persona` reloads in a fresh session with its accumulated turn count.
+
+Include this case rather than hiding it. The portal warns that `frame_domains` raises review
+requirements because an iframe reduces its visibility into the rendered experience; a reviewer
+who never exercises the widget is left more suspicious of it, not less.
Required test data: none. No account, no key, no seed files.
-**Negative**
+**Negative cases (prompts that must NOT invoke the plugin)**
-| # | Input | Expected safe behaviour |
+| # | Prompt | Why the model might misroute it, and why it must not |
|---|---|---|
-| 1 | A prompt for a real firearm, explosive or drug paraphernalia | Refused instantly, before any provider work, with `isError: true` and the exact text `This 3D Studio cannot generate real firearms, explosives, or drug paraphernalia. Stylized fantasy props (a sword, a wand) are fine.` Verified live 2026-09-11. The gate covers five categories (sexual, child-sexual, gore, hate/extremism, weapons/drugs); this one is the cleanest to demonstrate because the refusal names what IS allowed, and a stylized fantasy sword passes straight through, which shows the gate is not over-broad |
-| 2 | A tool call carrying an invalid or unreachable GLB URL | A designed error rather than a crash. Verified live 2026-09-11: `look_at_model` with `glb_url` set to a 404 returns `isError: true` and the text `could not render this model: render failed: glb load failed: fetch ... responded with 404`. The widget reaches its error state ("Couldn't load the model") and `/api/ar` returns a designed 400 ("Provide a valid https URL to a .glb model.") |
-| 3 | A host that cannot render WebGL | The widget degrades to a download-and-open fallback instead of a broken canvas |
+| 1 | `Draw a cartoon robot mascot for my startup's landing page.` | The wording nearly matches test case 1, but the user wants a 2D image and this plugin only returns 3D GLB models. Image generation owns this |
+| 2 | `Model out our Q3 revenue if we raise prices 20%.` | "Model" is a verb here, meaning a financial projection. Nothing 3D is involved |
+| 3 | `How do I rig a humanoid character in Blender?` | Uses "rig" and "character", but asks for an explanation, not work on a file. `rig_mesh` requires the URL of an existing GLB and would produce nothing the user asked for |
**Honest latency note for the reviewer.** Re-measured on 2026-09-11 against the live
connector, three consecutive `forge_free` calls took **74s, 149s and 213s** end to end. That
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 1fcc3b924..fb7e531db 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-09-11T05:05:14.644Z",
+ "generated_at": "2026-09-11T23:57:28.226Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 3672,
+ "total": 3673,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -20,6 +20,17 @@
"infra"
]
},
+ {
+ "date": "2026-09-11",
+ "type": "update",
+ "title": "The 3D creation skills are now a public download",
+ "summary": "The skills that teach an AI agent when and how to generate, rig, and embed 3D models on three.ws used to live only inside this repo. Four of them are now published at three.ws/skills/3d-studio: read one straight from the web, or download the whole set as a zip and drop it into whatever agent you are building. Nothing there needs an account, an API key, or a payment. A skill is only included if every tool it tells an agent to call is actually served, so a downloaded skill cannot send an agent after something that does not exist.",
+ "link": "/docs/agent-skills",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-09-11",
"type": "update",
@@ -1608,17 +1619,6 @@
"tags": [
"feature"
]
- },
- {
- "date": "2026-09-07",
- "type": "update",
- "title": "Security: the image and mesh workers now run patched libraries",
- "summary": "The services that strip a background, convert a mesh, and paint a texture all decode a file you upload, and they were pinned to an image library with a long list of published flaws, including several that let a crafted image corrupt memory. Those three services now run the patched release, and the mesh converter's 3D-format library was moved off a version with a critical flaw of its own. There is also a new check that scans every pinned Python dependency across the whole worker fleet against the public vulnerability database, so the next one gets found rather than waited for.",
- "link": null,
- "tags": [
- "security",
- "infra"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 424a4d400..1f95140f1 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-11T05:05:14.623Z",
+ "generated_at": "2026-09-11T23:57:28.205Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -17,6 +17,17 @@
"infra"
]
},
+ {
+ "date": "2026-09-11",
+ "type": "update",
+ "title": "The 3D creation skills are now a public download",
+ "summary": "The skills that teach an AI agent when and how to generate, rig, and embed 3D models on three.ws used to live only inside this repo. Four of them are now published at three.ws/skills/3d-studio: read one straight from the web, or download the whole set as a zip and drop it into whatever agent you are building. Nothing there needs an account, an API key, or a payment. A skill is only included if every tool it tells an agent to call is actually served, so a downloaded skill cannot send an agent after something that does not exist.",
+ "link": "/docs/agent-skills",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-09-11",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index f301e327d..39559a1f8 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -14,6 +14,14 @@
<category>fix</category>
<description>Uploading a photo on the selfie page could sit on the same message indefinitely and never start the scan, with no error and nothing to retry. One copy of the face-tracking runtime held at our CDN was telling browsers to expect 11 MB and then sending a third of that, so the page waited for bytes that were never coming. That copy is gone, and three changes make the failure impossible to repeat silently: the face-tracking runtime now loads from three.ws first instead of a public CDN, any wait on it gives up after fifteen seconds and builds your avatar from the photo as it is, and a photo is never rejected for having no face in it just because the detector could not load. A new check also walks every large file on the site the way a browser asks for it and fails loudly when the bytes do not add up. Measured after the fix: a selfie became a rigged, animation-ready avatar in about fifteen seconds, and still finished in under a minute with the face-tracking runtime completely unreachable.</description>
</item>
+ <item>
+ <title>The 3D creation skills are now a public download</title>
+ <link>https://three.ws/docs/agent-skills</link>
+ <guid isPermaLink="false">2026-09-11:The 3D creation skills are now a public download</guid>
+ <pubDate>Fri, 11 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>The skills that teach an AI agent when and how to generate, rig, and embed 3D models on three.ws used to live only inside this repo. Four of them are now published at three.ws/skills/3d-studio: read one straight from the web, or download the whole set as a zip and drop it into whatever agent you are building. Nothing there needs an account, an API key, or a payment. A skill is only included if every tool it tells an agent to call is actually served, so a downloaded skill cannot send an agent after something that does not exist.</description>
+ </item>
<item>
<title>Your selfie avatar now survives a storage outage instead of vanishing at the last step</title>
<link>https://three.ws/create/selfie</link>
diff --git a/public/skills/3d-studio/README.md b/public/skills/3d-studio/README.md
new file mode 100644
index 000000000..880235733
--- /dev/null
+++ b/public/skills/3d-studio/README.md
@@ -0,0 +1,45 @@
+# three.ws 3D Agent Skills
+
+The platform's 3D creation skills, packaged so any agent runtime can load them.
+Each folder is a self-contained skill: a `SKILL.md` whose frontmatter says when
+to trigger it, and instructions for driving the free, keyless 3D tools on
+https://three.ws/api/mcp-studio.
+
+| Skill | What it does |
+| --- | --- |
+| [`create-3d-avatar`](create-3d-avatar/SKILL.md) | Turn a text prompt (or reference image) into a rigged, animation-ready 3D avatar (GLB). |
+| [`embed-three-ws-avatar`](embed-three-ws-avatar/SKILL.md) | Embed a live, animated three.ws 3D avatar in any website with the &lt;agent-3d&gt; web component. |
+| [`generate-3d-model`](generate-3d-model/SKILL.md) | Turn a text prompt into a downloadable, textured 3D model (GLB). |
+| [`rig-a-model`](rig-a-model/SKILL.md) | Auto-rig a static 3D GLB model into an animation-ready one. |
+
+## Use them
+
+Download the whole set:
+
+```bash
+curl -O https://three.ws/skills/3d-studio/three-ws-3d-skills.zip
+```
+
+Or read one directly, no clone required:
+
+```bash
+curl https://three.ws/skills/3d-studio/create-3d-avatar/SKILL.md
+```
+
+Drop a folder into `.claude/skills/` for Claude Code or the Claude apps, upload
+the zip on the Skills tab of an OpenAI plugin submission, or point any other
+agent runtime at the same files. Nothing here needs an account, an API key, or a
+payment: the platform covers provider cost on the free lanes.
+
+## Generated, not hand-maintained
+
+This directory is produced by
+[`scripts/build-openai-skills-bundle.mjs`](../../../scripts/build-openai-skills-bundle.mjs)
+from the canonical pack in [`.agents/skills/`](../../../.agents/skills).
+Edit the skill there, then run `npm run build:openai-skills`.
+`npm run check:openai-skills` fails if this copy has drifted.
+
+Only skills tagged `3d/creative` and `cross-platform-safe` are published here,
+and any skill referencing a tool the studio endpoint does not expose is dropped:
+a skill that tells a model to call a tool that is not there is a dead path, not a
+feature.
diff --git a/public/skills/3d-studio/create-3d-avatar/SKILL.md b/public/skills/3d-studio/create-3d-avatar/SKILL.md
new file mode 100644
index 000000000..e1c421747
--- /dev/null
+++ b/public/skills/3d-studio/create-3d-avatar/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: create-3d-avatar
+description: 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.
+when_to_use: User wants a posable/animatable humanoid character. For a static object or prop, use generate-3d-model. To rig a GLB you already have, use rig-a-model.
+license: MIT
+metadata:
+ category: 3d/creative
+ cross-platform-safe: true
+ pack: three-ws-skills
+---
+
+# Create a rigged 3D avatar
+
+Turn a text prompt or a reference image into a **rigged, animation-ready** humanoid
+avatar (GLB). One call generates the textured mesh, then auto-rigs it, adding a
+humanoid skeleton and skin weights, so the model can be posed and play animation
+clips immediately.
+
+The result is a **`glbUrl`** for the rigged model plus a **pose-studio link** that
+opens the avatar ready to pose in the browser.
+
+## When to use which tool
+
+| Goal | Use |
+| --- | --- |
+| A posable humanoid **character** from text/image | this skill |
+| A static object / prop / creature | `generate-3d-model` |
+| Add a skeleton to a GLB you already generated | `rig-a-model` |
+
+Auto-rigging assumes a **humanoid figure**. A clearly non-humanoid subject
+(furniture, vehicle, quadruped) is steered to `generate-3d-model` instead.
+
+## Fastest path, the MCP tool
+
+If the three.ws MCP server is connected, call the one-step avatar tool:
+
+- **Tool:** `forge_avatar`
+- **Input:** `{ "prompt": "<character description>" }` or
+ `{ "image_url": "<https URL to a reference image>" }`
+ - `prompt`, describe a **single full-body humanoid** in a neutral standing pose:
+ `"a friendly cartoon astronaut in a glossy white suit"`.
+ - `image_url`, reconstruct and rig a character from a photo/render.
+ - `allow_non_humanoid`, set `true` only to rig a non-humanoid subject anyway.
+- **Returns:** the rigged `glbUrl` (or `riggedGlbUrl`), the intermediate mesh URL,
+ a pose-studio link, and per-stage timing.
+
+For a fast unrigged figure (no skeleton), use `text_to_avatar` instead, same
+inputs, mesh only.
+
+## Portable path, the hosted HTTP endpoint
+
+No MCP client needed. The free hosted lane is a public JSON-RPC endpoint at
+`https://three.ws/api/mcp-studio`:
+
+```bash
+curl -s -X POST https://three.ws/api/mcp-studio \
+ -H 'content-type: application/json' \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "forge_avatar",
+ "arguments": { "prompt": "a friendly cartoon astronaut in a glossy white suit" }
+ }
+ }'
+```
+
+`structuredContent` returns the rigged model:
+
+```json
+{
+ "kind": "avatar",
+ "glbUrl": "https://three.ws/cdn/creations/def456/rigged.glb",
+ "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2F...",
+ "format": "glb",
+ "rigged": true,
+ "prompt": "a friendly cartoon astronaut in a glossy white suit"
+}
+```
+
+## Manual two-step (REST)
+
+`forge_avatar` is generate-then-rig bundled. You can run the steps yourself over
+`POST /api/forge`, generate a mesh, then rig it:
+
+```bash
+# 1. Generate the figure (see generate-3d-model/reference.md for the submit/poll shape)
+# "tier": "high" matches what forge_avatar/text_to_avatar request automatically, # it is the tier the router maps to the self-host Hunyuan3D lane for IRL realism.
+curl -s -X POST https://three.ws/api/forge -H 'content-type: application/json' \
+ -d '{ "prompt": "a friendly cartoon astronaut in a glossy white suit", "tier": "high" }'
+
+# 2. Rig the resulting GLB (see rig-a-model)
+curl -s -X POST "https://three.ws/api/forge?action=rig" -H 'content-type: application/json' \
+ -d '{ "glb_url": "<glbUrl from step 1>" }'
+```
+
+## What to do with the result
+
+1. Give the user the **pose-studio / viewer link**, they can pose and preview the
+ rigged avatar in the browser.
+2. Give the **`glbUrl`** for download / import into a 3D engine; it already carries
+ a humanoid skeleton and skin weights, so animation clips play on it.
+
+## Prompting tips
+
+- One **full-body humanoid**, neutral standing pose, arms slightly away from the
+ body, best for a clean rig.
+- Name the silhouette and materials: `"a tall slender elf ranger in green leather
+ armor"`. Avoid scenes, props held in hand, or multiple characters.
+- Hands are the hardest part of the mesh to get right. `forge_avatar` /
+ `text_to_avatar` already direct the generator toward relaxed, open hands with
+ fingers separated and visible (never a fist, never a hand hidden behind the
+ body or in a pocket), do not fight that by asking for "hands on hips" or
+ "arms crossed" unless you accept a higher chance of fused-finger geometry.
+ Asking is not the same as getting: measured across six personas on 2026-09-08,
+ a prompt that explicitly said "hands open, fingers separated" still came back
+ with both hands fused into one clasped blob at the chest in one case, and with
+ cleanly separated fingers in another. What correlates with separated fingers is
+ the hands being **away from the torso and from each other** in the described
+ pose, so say where the hands are ("arms hanging at his sides, palms forward"),
+ not just what they are doing.
+- Both avatar tools always request the platform's `high` quality tier under the
+ hood, the self-host Hunyuan3D lane (people/organic-subject strength, portrait
+ realism cues on the reference image) instead of the faster draft/standard
+ default. This is automatic; no input needed.
+
+## Higher-fidelity & paid lanes
+
+The full three.ws MCP server also exposes higher-fidelity, art-directed and paid
+avatar lanes. The free hosted path above is the cross-platform-safe one. The rig
+internals (skeleton convention, what makes a model riggable) live in the
+`rig-a-model` skill.
+
+## Errors
+
+- `rate_limited` / `busy`, honor `retryAfter` and retry.
+- `not_configured`, lane momentarily cold; retry shortly.
+- Generation succeeded but rigging failed, you still get the unrigged mesh URL;
+ hand it back and offer to retry rigging via `rig-a-model`.
+
+Never report a dead or empty link as success.
diff --git a/public/skills/3d-studio/embed-three-ws-avatar/SKILL.md b/public/skills/3d-studio/embed-three-ws-avatar/SKILL.md
new file mode 100644
index 000000000..088a96284
--- /dev/null
+++ b/public/skills/3d-studio/embed-three-ws-avatar/SKILL.md
@@ -0,0 +1,158 @@
+---
+name: embed-three-ws-avatar
+description: 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.
+when_to_use: A site or app (any framework, or plain HTML) should display or control a three.ws avatar. To generate the avatar model itself, use create-3d-avatar or generate-3d-model first; this skill covers putting the result on a page and driving it.
+license: MIT
+metadata:
+ category: 3d/creative
+ cross-platform-safe: true
+ pack: three-ws-skills
+---
+
+# Embed a three.ws avatar on any site
+
+The `<agent-3d>` web component renders a rigged, animated 3D avatar (GLB) with
+zero framework dependencies. It works in plain HTML, React, Vue, Svelte, Angular,
+WordPress, Webflow, Shopify, Framer, and Notion embeds. The bundle is served from
+the three.ws CDN with `access-control-allow-origin: *`, so it loads from any origin.
+
+## Quick start
+
+```html
+<script
+ type="module"
+ src="https://three.ws/agent-3d/1.5.2/agent-3d.js"
+ integrity="sha384-xkFDjVP866hYt7voUhfnQHj6IO4hYxA6n8Laupk+VtD6y+IKiO/AZdE3VbfLtg0C"
+ crossorigin="anonymous"
+></script>
+
+<agent-3d
+ body="https://three.ws/avatars/default.glb"
+ mode="section"
+ kiosk
+ poster="/images/avatar-poster.webp"
+ style="width:100%;height:420px;display:block"
+></agent-3d>
+```
+
+A UMD build exists at the same path as `agent-3d.umd.cjs` if ES modules are not an option.
+
+## Pick the right CDN channel (do not ship `latest`)
+
+| Path | Cache | Use when |
+| --- | --- | --- |
+| `/agent-3d/<MAJOR>.<MINOR>.<PATCH>/agent-3d.js` | immutable, 1 year | production. Pin exact bytes, always combine with SRI |
+| `/agent-3d/<MAJOR>.<MINOR>/agent-3d.js` | 5 min | follow patch releases automatically |
+| `/agent-3d/<MAJOR>/agent-3d.js` | 5 min | follow minor + patch releases |
+| `/agent-3d/latest/agent-3d.js` | 5 min | demos and prototypes only |
+
+`latest` can ship breaking changes with no action on your side. For production,
+pin an exact version with an `integrity` attribute. Machine-readable release
+data:
+
+- `https://three.ws/agent-3d/versions.json`: current version, channels, publish time.
+- `https://three.ws/agent-3d/<version>/integrity.json`: sha384 SRI hashes for that exact version.
+
+## Getting a GLB for `body`
+
+Any humanoid GLB URL works. Models generated on three.ws come back on persistent
+`https://three.ws/cdn/forge/...` URLs you can use directly in `body` with no
+re-hosting (self-hosting also works if you want control):
+
+- Generate from text or a reference image: the `create-3d-avatar` skill (rigged,
+ animation-ready) or `generate-3d-model` (static prop). Both return a `glbUrl`.
+- Rig an existing GLB: the `rig-a-model` skill.
+- Let end users design one interactively: the Avatar Studio iframe flow below.
+
+Rigging is universal on three.ws: any humanoid skeleton convention (Mixamo,
+VRM/VRoid, Avaturn, Unreal, Daz, MakeHuman, and more) is auto-mapped so the
+built-in animation clips (idle, walk, wave, dance, ...) play on it.
+
+## Key attributes
+
+| Attribute | What it does |
+| --- | --- |
+| `body` | GLB URL of the avatar to render (absolute URL) |
+| `brain` | Conversation engine. Omit or `none` = silent decorative avatar. `free` = real chat with a host-paid free LLM lane: no API key, no cost to you. Any other value is treated as a specific model id |
+| `mode` | Layout: `section` for in-page blocks, plus floating widget positions |
+| `kiosk` (or `viewer`) | Bare display mode: no chrome, pure avatar showcase |
+| `poster` | Image painted instantly while the GLB streams, then crossfaded out. Use it instead of your own skeleton/placeholder div |
+| `eager` | Boot immediately. Default is lazy: the element boots when scrolled into view. Set on above-the-fold hero placements |
+| `background` | `transparent`, `dark`, `light`, or any CSS color |
+| `name-plate` | `off` to hide the floating name label |
+| `clip` | Named animation to play decoratively (e.g. `dance`) |
+| `framing` | `portrait` for a head-and-shoulders crop |
+| `responsive` | Adapt sizing to the container |
+
+There is no `auto-rotate` attribute on `<agent-3d>`; setting one is silently
+ignored (it belongs to `<model-viewer>`, a different element).
+
+## Events (all bubble and cross shadow DOM)
+
+- `agent:ready`: model loaded and animating. Gate your "loaded" UI on this, never on a timeout.
+- `agent:error`: load or boot failed. Show your fallback here.
+- `agent:load-progress`: `{ phase, pct }` detail for a real progress indicator.
+- With a brain enabled: `brain:thinking`, `brain:message`, `brain:stream`,
+ `voice:speech-start`, `voice:speech-end`, `voice:transcript`.
+
+## Imperative API (methods on the element)
+
+```js
+const el = document.querySelector('agent-3d');
+el.addEventListener('agent:ready', async () => {
+ await el.wave({ style: 'enthusiastic' }); // greeting gesture
+ await el.playClip('dance', { loop: false }); // any named clip, reduced-motion aware
+ await el.lookAt('user'); // face the camera
+ el.setMood(0.8, 0.4); // sustained expression: valence -1..1, arousal 0..1
+ await el.say('Welcome!'); // speech bubble + talk animation (works with brain="none")
+ await el.speak('Welcome!'); // spoken TTS variant
+});
+```
+
+Lifecycle: call `el.pause()` and `el.resume()` for tab-visibility or carousel
+logic, and `el.destroy()` on unmount, from your framework's cleanup hook.
+
+Theming: the element reads CSS custom properties, led by `--agent-accent`, so
+you can match it to your brand color per instance:
+`el.style.setProperty('--agent-accent', '#b8ff2e')`.
+
+## Let users design their avatar: Avatar Studio iframe
+
+Open `https://three.ws/create/studio` in an iframe (a modal works well; set
+`allow="camera *; microphone *; clipboard-write"`). When the user exports, the
+studio posts the finished GLB to the parent window:
+
+```js
+window.addEventListener('message', (event) => {
+ if (event.origin !== 'https://three.ws') return; // always check origin
+ const msg = event.data;
+ if (msg?.source === 'characterstudio' && msg.type === 'export' && msg.glb instanceof ArrayBuffer) {
+ const blob = new Blob([msg.glb], { type: 'model/gltf-binary' });
+ // Upload the blob to your storage (or use it in-memory), then point
+ // <agent-3d body="..."> at the resulting URL.
+ }
+});
+```
+
+The message shape is `{ source: 'characterstudio', type: 'export', format: 'glb', glb: ArrayBuffer }`.
+The protocol is currently export-only: you cannot seed an existing GLB into the
+studio for re-editing.
+
+There is also a plain link target for text-to-3D generation with no integration
+work: `https://three.ws/create/prompt`.
+
+## Common mistakes
+
+1. Loading `/agent-3d/latest/` in production. Pin a version and add SRI.
+2. Marking the avatar "ready" on a `setTimeout`. Use `agent:ready` and `agent:load-progress`.
+3. Building your own loading placeholder. Pass a `poster` image instead.
+4. Forgetting `eager` on a hero placement, so the avatar boots late.
+5. Forgetting `el.destroy()` on unmount in SPA frameworks, leaking WebGL contexts.
+6. Setting `auto-rotate`, which does nothing on this element.
+7. Leaving conversation off when it would be free: `brain="free"` costs the embedder nothing.
+
+## Reference
+
+- Full element reference (all attributes, events, JS API): `https://three.ws/docs/web-component`
+- Embedding guide: `https://three.ws/docs/embedding`
+- Release manifest: `https://three.ws/agent-3d/versions.json`
diff --git a/public/skills/3d-studio/generate-3d-model/SKILL.md b/public/skills/3d-studio/generate-3d-model/SKILL.md
new file mode 100644
index 000000000..4930d45f3
--- /dev/null
+++ b/public/skills/3d-studio/generate-3d-model/SKILL.md
@@ -0,0 +1,104 @@
+---
+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.
+when_to_use: User wants a 3D object/asset/prop from text. For a posable character with a skeleton, use create-3d-avatar. To rig an existing GLB, use rig-a-model.
+license: MIT
+metadata:
+ category: 3d/creative
+ cross-platform-safe: true
+ pack: three-ws-skills
+---
+
+# Generate a 3D model from text
+
+Turn a natural-language prompt into a textured, downloadable **GLB** model on the
+**free** three.ws text→3D lane (NVIDIA NIM / Microsoft TRELLIS). No API key and no
+account, the platform's server-side keys cover provider cost.
+
+The result is always two things: a durable **`glbUrl`** (download / import into any
+3D tool) and a **viewer link** that renders the model in the browser.
+
+## When to use which tool
+
+| Goal | Use |
+| --- | --- |
+| A single object / prop / creature from text | this skill (free lane) |
+| A posable humanoid **character with a skeleton** | `create-3d-avatar` |
+| Add a skeleton to a GLB you already have | `rig-a-model` |
+
+## Fastest path, the MCP tool
+
+If the three.ws MCP server is connected, call the free tool directly:
+
+- **Tool:** `forge_free`
+- **Input:** `{ "prompt": "<description>", "tier": "draft" }`
+ - `prompt`, 3 to 1000 chars. Lead with the subject, then its key materials and
+ colors. The free lane conditions on ~77 characters, so front-load what matters:
+ `"a friendly round robot mascot, glossy white plastic, big blue eyes"`.
+ - `tier`, `draft` (fast, default), `standard`, or `high`. All free; higher tiers
+ only take longer.
+- **Returns:** `glbUrl`, `viewerUrl`, `tier`, `backend`, `durationMs`.
+
+This is text-only (the free TRELLIS preview does not accept uploaded photos). For
+image / multi-view → 3D, use the art-directed lanes described in
+[reference.md](reference.md).
+
+## Portable path, the hosted HTTP endpoint
+
+No MCP client required. The same free lane is a public JSON-RPC endpoint at
+`https://three.ws/api/mcp-studio` (no auth, no account):
+
+```bash
+curl -s -X POST https://three.ws/api/mcp-studio \
+ -H 'content-type: application/json' \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "forge_free",
+ "arguments": { "prompt": "a small glossy green ceramic frog figurine", "tier": "draft" }
+ }
+ }'
+```
+
+Response (`structuredContent`) carries the model:
+
+```json
+{
+ "kind": "model",
+ "glbUrl": "https://three.ws/cdn/creations/abc123/mesh.glb",
+ "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2F...",
+ "format": "glb",
+ "prompt": "a small glossy green ceramic frog figurine"
+}
+```
+
+Discover the full free tool set first with `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`.
+
+## What to do with the result
+
+1. Give the user the **viewer link**, they can rotate and inspect the model in the
+ browser immediately.
+2. Give the **`glbUrl`** for download / import into Blender, Unity, three.js, etc.
+3. If they want it animated, feed `glbUrl` into the `rig-a-model` skill.
+
+## Higher-fidelity & art-directed lanes
+
+The full three.ws MCP server also exposes art-directed and image→3D lanes
+(`mesh_forge`) and paid lanes with denser geometry. Those, the tier trade-offs, the
+raw `POST /api/forge` REST shape, and full error handling are in
+[reference.md](reference.md), load it only when you need more than the free
+text→3D path above.
+
+## Errors
+
+The free lane is shared and protected by per-IP rate limits and a global capacity
+breaker. Handle these and retry rather than failing:
+
+- `rate_limited` / `busy`, honor `retryAfter` (seconds) and try again.
+- `not_configured`, the durable lane is momentarily cold; retry shortly.
+- `lane_degraded`, a result was produced but its URL was unreachable; retry.
+
+Never report a dead or empty link as success, only return a `glbUrl` the call
+actually produced.
diff --git a/public/skills/3d-studio/generate-3d-model/reference.md b/public/skills/3d-studio/generate-3d-model/reference.md
new file mode 100644
index 000000000..6ab5c6e89
--- /dev/null
+++ b/public/skills/3d-studio/generate-3d-model/reference.md
@@ -0,0 +1,97 @@
+# generate-3d-model, full reference
+
+Loaded on demand. The free text→3D path in `SKILL.md` covers most needs; this file
+documents the art-directed lanes, the raw REST pipeline, and tuning.
+
+## The three.ws generation lanes
+
+Every lane produces the same artifact, a textured **GLB** plus a viewer link. They
+differ in how the mesh is reconstructed and in fidelity.
+
+| Lane | Tool | Cost | Input | Notes |
+| --- | --- | --- | --- | --- |
+| Free text→3D | `forge_free` | Free | text only | NVIDIA NIM / TRELLIS. Default for this skill. |
+| Art-directed | `mesh_forge` | Paid | text, image, or 1 to 4 multi-view images | IBM Granite "prompt director" refines the prompt, FLUX renders a reference, then TRELLIS / Hunyuan3D reconstruct. Higher single-subject fidelity. |
+| Avatar | `text_to_avatar` | Paid (free on the hosted studio) | text or image | Tuned for figures/characters. |
+
+The **hosted studio** at `https://three.ws/api/mcp-studio` exposes `forge_free`,
+`mesh_forge`, `text_to_avatar`, `rig_mesh`, and `forge_avatar` as a free,
+non-account JSON-RPC tool set (the platform covers provider cost). The full three.ws
+MCP server (`npx`-distributed) exposes the same tools with the art-directed and
+avatar lanes as paid, higher-fidelity options.
+
+## Quality tiers (free lane)
+
+`tier` controls the geometry/texture budget on the free lane:
+
+| Tier | Speed | Mesh density |
+| --- | --- | --- |
+| `draft` | fastest (default) | light, good for previews |
+| `standard` | balanced | medium |
+| `high` | slowest | densest |
+
+All three are free. Higher tiers cost only time.
+
+## Prompting for quality
+
+- **Lead with the subject**, then materials, then color: `"a worn leather armchair,
+ brass studs, deep oxblood"`.
+- Describe **one** object. The lane reconstructs a single subject; scenes and
+ multiple objects degrade quality.
+- Name the **material and finish** (matte / glossy / metallic / ceramic), it
+ drives the texture far more than adjectives like "cool" or "nice".
+- Keep it under ~77 meaningful characters of subject description for the free lane.
+
+## Raw REST pipeline (`/api/forge`)
+
+The MCP tools are thin clients over the public `POST /api/forge` endpoint. Use it
+directly when you want no MCP client at all.
+
+**Submit a job:**
+
+```bash
+curl -s -X POST https://three.ws/api/forge \
+ -H 'content-type: application/json' \
+ -d '{ "prompt": "a small glossy green ceramic frog figurine", "backend": "nvidia", "path": "image" }'
+```
+
+- `backend: "nvidia"` + `path: "image"` pins the free NVIDIA lane.
+- The free lane often finishes inside the submit window and returns
+ `{ "status": "done", "glb_url": "..." }` directly. Otherwise it returns
+ `{ "job_id": "..." }`.
+
+**Poll until done:**
+
+```bash
+curl -s "https://three.ws/api/forge?job=<job_id>" -H 'accept: application/json'
+```
+
+Terminal states: `{"status":"done","glb_url":"..."}` or
+`{"status":"failed","error":"..."}`.
+
+**Build the viewer link** yourself from any GLB URL:
+
+```
+https://three.ws/viewer?src=<URL-encoded glbUrl>
+```
+
+## Error codes
+
+| Code / status | Meaning | Action |
+| --- | --- | --- |
+| `429` / `rate_limited` / `busy` | Per-IP or global rate limit | Honor `retryAfter` / `retry_after`, then retry. |
+| `503` / `not_configured` | Lane momentarily cold or disabled on this deployment | Retry shortly. |
+| `lane_degraded` | Produced a URL that was unreachable | Retry; never return the dead URL. |
+| `generation_failed` | The job failed | Surface the `error`, adjust the prompt, retry. |
+| `timeout` | Generator did not accept/finish in budget | Retry; raise the poll budget if self-hosting. |
+
+## Tuning (self-hosted MCP server)
+
+All optional, with production defaults:
+
+| Env | Default | Purpose |
+| --- | --- | --- |
+| `FORGE_FREE_API_BASE` | `https://three.ws` | Origin to call. |
+| `FORGE_FREE_TIMEOUT_MS` | `180000` | Reconstruct poll budget. |
+| `FORGE_FREE_POLL_MS` | `3000` | Poll interval. |
+| `FORGE_FREE_ATTEMPTS` | `2` | Retries to land the durable lane before falling back to a verified-reachable result. |
diff --git a/public/skills/3d-studio/rig-a-model/SKILL.md b/public/skills/3d-studio/rig-a-model/SKILL.md
new file mode 100644
index 000000000..ab48a5a74
--- /dev/null
+++ b/public/skills/3d-studio/rig-a-model/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: rig-a-model
+description: 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.
+when_to_use: User already has a GLB (a URL) and wants it rigged. To generate a new model from text, use generate-3d-model; to generate an already-rigged character in one step, use create-3d-avatar.
+license: MIT
+metadata:
+ category: 3d/creative
+ cross-platform-safe: true
+ pack: three-ws-skills
+---
+
+# Rig a 3D model
+
+Turn a **static GLB** into an **animation-ready** one. The three.ws auto-rig
+pipeline (Make-It-Animatable) adds a humanoid skeleton and per-vertex skin weights,
+so the model can be posed and play animation clips.
+
+The result is a **`riggedGlbUrl`** plus a **pose-studio link** that opens the
+rigged model in the browser, ready to pose.
+
+## When to use which tool
+
+| Goal | Use |
+| --- | --- |
+| Add a skeleton to a GLB you already have | this skill |
+| A new static object / prop from text | `generate-3d-model` |
+| A new rigged character from text/image in one call | `create-3d-avatar` |
+
+Rigging assumes a roughly **humanoid figure** (head, torso, two arms, two legs,
+standing). Props, furniture, and vehicles won't rig meaningfully.
+
+## Fastest path, the MCP tool
+
+If the three.ws MCP server is connected, call the rig tool directly:
+
+- **Tool:** `rig_mesh`
+- **Input:** `{ "glb_url": "<https URL to the static GLB>" }`
+ - Any reachable GLB URL works, a `glbUrl` from `generate-3d-model`, a CDN
+ link, or a model you host yourself.
+- **Returns:** `riggedGlbUrl`, `sourceGlbUrl`, `poseStudioUrl`, `jobId`,
+ `creationId`, `durationMs`.
+
+## Portable path, the hosted HTTP endpoint
+
+No MCP client needed. `rig_mesh` is exposed free on the hosted studio JSON-RPC
+endpoint at `https://three.ws/api/mcp-studio` (no key, no account):
+
+```bash
+curl -s -X POST https://three.ws/api/mcp-studio \
+ -H 'content-type: application/json' \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "rig_mesh",
+ "arguments": { "glb_url": "https://three.ws/avatars/cesium-man.glb" }
+ }
+ }'
+```
+
+`structuredContent` returns the rigged model:
+
+```json
+{
+ "ok": true,
+ "riggedGlbUrl": "https://three.ws/cdn/creations/def456/rigged.glb",
+ "sourceGlbUrl": "https://three.ws/avatars/cesium-man.glb",
+ "poseStudioUrl": "https://three.ws/pose?src=https%3A%2F%2Fthree.ws%2F...",
+ "jobId": "r9k2m7x4",
+ "durationMs": 48000
+}
+```
+
+## Raw REST pipeline
+
+The MCP tool is a thin client over the public rig endpoint. Submit, then poll:
+
+```bash
+# 1. Start the rig job
+curl -s -X POST "https://three.ws/api/forge?action=rig" \
+ -H 'content-type: application/json' \
+ -d '{ "glb_url": "https://three.ws/avatars/cesium-man.glb" }'
+# → { "job_id": "r9k2m7x4", ... }
+
+# 2. Poll until done (every ~3s, budget ~180s)
+curl -s "https://three.ws/api/forge?job=r9k2m7x4" -H 'accept: application/json'
+# → { "status": "done", "glb_url": "https://.../rigged.glb" } (or "failed" / still "running")
+```
+
+Build the pose-studio link yourself from any rigged GLB URL:
+`https://three.ws/pose?src=<URL-encoded riggedGlbUrl>`.
+
+## What to do with the result
+
+1. Give the user the **pose-studio link**, pose and preview in the browser.
+2. Give the **`riggedGlbUrl`** for download / import; it carries a humanoid
+ skeleton and skin weights, so animation clips retarget onto it.
+3. The original mesh is never modified, `sourceGlbUrl` stays valid.
+
+## Errors
+
+- `rate_limited` / `429`, the rigger is busy; honor `retryAfter` and retry.
+- `not_configured` / `503`, auto-rigging momentarily unavailable; retry shortly.
+- `rig_failed`, the model couldn't be rigged (usually not humanoid enough).
+ Tell the user why and suggest `create-3d-avatar` to generate a riggable figure.
+- `timeout`, the job outlived the poll budget; the response includes a
+ `resumeUrl`, keep polling it rather than restarting the job.
+
+Never report a dead or empty link as success, only return a `riggedGlbUrl` the
+job actually produced.
diff --git a/public/skills/3d-studio/three-ws-3d-skills.zip b/public/skills/3d-studio/three-ws-3d-skills.zip
new file mode 100644
index 000000000..072af7a58
Binary files /dev/null and b/public/skills/3d-studio/three-ws-3d-skills.zip differ
diff --git a/scripts/build-openai-skills-bundle.mjs b/scripts/build-openai-skills-bundle.mjs
index 175d651c5..ed4d1d879 100644
--- a/scripts/build-openai-skills-bundle.mjs
+++ b/scripts/build-openai-skills-bundle.mjs
@@ -1,32 +1,40 @@
#!/usr/bin/env node
-// Package the cross-platform-safe 3D skills as a zip for the OpenAI Plugin
-// Directory's Skills tab, and refuse to ship one that tells the model to call a
-// tool our connector does not expose.
+// Publish the cross-platform-safe 3D skills as a public, downloadable bundle,
+// and refuse to ship one that tells a model to call a tool we do not serve.
//
-// node scripts/build-openai-skills-bundle.mjs # build + verify
-// node scripts/build-openai-skills-bundle.mjs --check # verify only, write nothing
-// node scripts/build-openai-skills-bundle.mjs --offline # skip the live tools/list check
+// npm run build:openai-skills # regenerate the published bundle
+// npm run check:openai-skills # fail if the published copy drifted
//
-// Why a dedicated builder rather than zipping .agents/skills wholesale:
+// Output, all tracked and served from three.ws:
//
-// 1. Only part of the pack belongs in a 3D plugin. The pack carries 43 skills,
-// most of them wallet, payments and partner-exchange work. OpenAI's own
-// packaging guidance asks for scoped instructions that fit the plugin's
-// purpose, so the bundle is derived from frontmatter (category 3d/*, and
-// cross-platform-safe) instead of a hand-kept list that would rot.
+// public/skills/3d-studio/<skill>/SKILL.md readable at /skills/3d-studio/...
+// public/skills/3d-studio/three-ws-3d-skills.zip
+// public/skills/3d-studio/README.md
//
-// 2. A skill is only true if its tools exist. find-3d-assets documents
-// search_catalog / get_catalog_item / get_item_source, which live on the
-// paid /api/mcp endpoint and not on the mcp-studio connector this plugin
-// submits. Inside ChatGPT there is no shell, so the skill's HTTP fallback is
-// unreachable too: the model would simply fail. This script reads the live
-// tool list and drops any skill that references a tool the connector does
-// not have, naming it in the report. When catalog tools land on mcp-studio,
-// that skill rejoins the bundle with no edit here.
+// The zip is the artifact an OpenAI Plugin Directory submission uploads on its
+// Skills tab, and the unpacked tree is what anyone else can read or curl
+// without cloning the repo.
//
-// 3. The listing is public copy, so the packaged text goes through the same
-// dash rule the rest of the submission copy did. Canonical files under
-// .agents/skills are left untouched; only the bundled copy is normalized.
+// Three things this does that a `zip -r` of .agents/skills would not:
+//
+// 1. Scope. The pack carries 43 skills, most of them wallet, payments and
+// partner-exchange work. A 3D plugin shipping those reads as unfocused
+// against OpenAI's guidance to keep instructions scoped to the plugin's
+// purpose, so the set is derived from frontmatter (category 3d/*, and
+// cross-platform-safe) rather than a hand-kept list that would rot.
+//
+// 2. No dead paths. A skill is only true if its tools exist. This reads the
+// tool names the studio endpoint actually declares and drops any skill
+// referencing one that is missing, naming it in the report. find-3d-assets
+// is excluded today for exactly that reason: its catalog tools live on the
+// full MCP server, not on mcp-studio, and inside ChatGPT there is no shell,
+// so the skill's documented curl fallback cannot rescue it either. Ship
+// those tools on mcp-studio and the skill rejoins with no edit here.
+//
+// 3. Determinism. Published output is tracked, so a rebuild that changes bytes
+// for no reason would show up as a diff in everyone else's worktree. Staged
+// files get a fixed timestamp and the zip is built from a sorted file list,
+// which is what lets --check be a real drift gate.
import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, statSync } from 'node:fs';
import { join, resolve, dirname, relative } from 'node:path';
@@ -35,19 +43,22 @@ import { execFileSync } from 'node:child_process';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const SKILLS_DIR = join(ROOT, '.agents', 'skills');
-const OUT_DIR = join(ROOT, 'dist-skills');
-const STAGE = join(OUT_DIR, 'openai-plugin-skills');
-const ZIP = join(OUT_DIR, 'openai-plugin-skills.zip');
+const STUDIO_DIR = join(ROOT, 'api', '_mcp-studio');
+const PUBLISH_DIR = join(ROOT, 'public', 'skills', '3d-studio');
+const ZIP_NAME = 'three-ws-3d-skills.zip';
const CONNECTOR = process.env.OPENAI_CONNECTOR_URL || 'https://three.ws/api/mcp-studio';
-// OpenAI's documented upload limits for a skills bundle.
+// Fixed so a rebuild with unchanged inputs produces a byte-identical zip.
+const STAMP = '202001010000';
+
+// OpenAI's documented limits for a skills bundle upload.
const MAX_ZIP_BYTES = 50 * 1024 * 1024;
const MAX_FILES = 500;
const MAX_FILE_BYTES = 25 * 1024 * 1024;
const argv = new Set(process.argv.slice(2));
const checkOnly = argv.has('--check');
-const offline = argv.has('--offline');
+const offline = argv.has('--offline') || checkOnly;
/** Minimal frontmatter reader: the same subset build-skills-pack.mjs relies on. */
function frontmatter(text) {
@@ -101,22 +112,33 @@ function referencedTools(text) {
toolColumns = [];
continue;
}
- const next = lines[i + 1] || '';
- if (/^\s*\|[\s:|-]+\|\s*$/.test(next)) {
+ if (/^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1] || '')) {
toolColumns = cells(line).flatMap((h, idx) => (/^tools?$/i.test(h) ? [idx] : []));
i++;
continue;
}
for (const idx of toolColumns) {
- const cell = cells(line)[idx];
- if (!cell) continue;
- const m = cell.match(/^`([a-z][a-z0-9_]*)`$/);
+ const m = (cells(line)[idx] || '').match(/^`([a-z][a-z0-9_]*)`$/);
if (m) add(m[1]);
}
}
return found;
}
+/**
+ * The tool names the studio endpoint declares in source. This is the offline
+ * source of truth precisely because it IS the code that serves them, so it
+ * cannot drift from production the way a checked-in snapshot would.
+ */
+function sourceToolNames() {
+ const names = new Set();
+ for (const file of readdirSync(STUDIO_DIR).filter((f) => f.endsWith('.js'))) {
+ const text = readFileSync(join(STUDIO_DIR, file), 'utf8');
+ for (const m of text.matchAll(/^\t*name: '([a-z][a-z0-9_]*)',$/gm)) names.add(m[1]);
+ }
+ return names;
+}
+
async function liveToolNames() {
const res = await fetch(CONNECTOR, {
method: 'POST',
@@ -129,8 +151,7 @@ async function liveToolNames() {
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error(`${CONNECTOR} answered ${res.status}`);
- const raw = await res.text();
- const line = raw.trim().split('\n').filter(Boolean).pop().replace(/^data:\s*/, '');
+ const line = (await res.text()).trim().split('\n').filter(Boolean).pop().replace(/^data:\s*/, '');
const tools = JSON.parse(line).result?.tools || [];
if (!tools.length) throw new Error(`${CONNECTOR} returned no tools`);
return new Set(tools.map((t) => t.name));
@@ -143,12 +164,12 @@ function walk(dir) {
if (entry.isDirectory()) out.push(...walk(full));
else if (entry.isFile()) out.push(full);
}
- return out;
+ return out.sort();
}
-/** The submission copy is public, so it follows the repo's dash rule. */
+/** Published copy is public-facing, so it follows the repo's dash rule. */
function normalizeDashes(text) {
- // Escapes rather than the literal glyphs, so this file passes the same rule it enforces.
+ // Escapes rather than the literal glyphs, so this file passes the rule it enforces.
return text.replace(/\s*\u2014\s*/g, ', ').replace(/\s*\u2013\s*/g, ' to ');
}
@@ -159,13 +180,12 @@ const candidates = readdirSync(SKILLS_DIR, { withFileTypes: true })
.map((name) => {
const skillFile = join(SKILLS_DIR, name, 'SKILL.md');
if (!existsSync(skillFile)) return null;
- const text = readFileSync(skillFile, 'utf8');
- const fm = frontmatter(text);
+ const fm = frontmatter(readFileSync(skillFile, 'utf8'));
if (!fm) return null;
const meta = fm.metadata || {};
if (!String(meta.category || '').startsWith('3d/')) return null;
if (String(meta['cross-platform-safe']) !== 'true') return null;
- return { name, dir: join(SKILLS_DIR, name), fm, text };
+ return { name, dir: join(SKILLS_DIR, name), fm };
})
.filter(Boolean);
@@ -174,8 +194,27 @@ if (!candidates.length) {
process.exit(1);
}
-const live = offline ? null : await liveToolNames();
-if (live) console.log(`connector ${CONNECTOR} exposes ${live.size} tool(s)\n`);
+const declared = sourceToolNames();
+if (!declared.size) {
+ console.error(`no tool names found in ${relative(ROOT, STUDIO_DIR)}; the declaration shape changed`);
+ process.exit(1);
+}
+
+// Online, the served list is the authority and a disagreement with source is a
+// deploy-drift finding worth failing on, not a detail to smooth over.
+if (!offline) {
+ const live = await liveToolNames();
+ const onlyLive = [...live].filter((t) => !declared.has(t)).sort();
+ const onlySource = [...declared].filter((t) => !live.has(t)).sort();
+ if (onlyLive.length || onlySource.length) {
+ console.error(`${CONNECTOR} and ${relative(ROOT, STUDIO_DIR)} disagree about the tool surface:`);
+ if (onlyLive.length) console.error(` served but not in source: ${onlyLive.join(', ')}`);
+ if (onlySource.length) console.error(` in source but not served: ${onlySource.join(', ')}`);
+ console.error('production is running different code than this checkout. Resolve that before publishing.');
+ process.exit(1);
+ }
+ console.log(`${CONNECTOR} serves the same ${live.size} tool(s) this checkout declares\n`);
+}
const included = [];
const excluded = [];
@@ -186,26 +225,19 @@ for (const skill of candidates) {
if (!skill.fm.description) problems.push('no description in frontmatter, so nothing tells the model when to trigger it');
const files = walk(skill.dir);
- if (files.filter((f) => /(^|\/)SKILL\.md$/i.test(f)).length !== 1) {
- problems.push('a skill must carry exactly one SKILL.md');
- }
+ if (files.filter((f) => /(^|\/)SKILL\.md$/i.test(f)).length !== 1) problems.push('a skill must carry exactly one SKILL.md');
for (const f of files) {
if (statSync(f).size > MAX_FILE_BYTES) problems.push(`${relative(ROOT, f)} exceeds the 25MB per-file limit`);
}
- if (live) {
- const wanted = new Set();
- for (const f of files) {
- if (!f.endsWith('.md')) continue;
- for (const t of referencedTools(readFileSync(f, 'utf8'))) wanted.add(t);
- }
- const missing = [...wanted].filter((t) => !live.has(t)).sort();
- if (missing.length) {
- problems.push(`calls ${missing.map((t) => `\`${t}\``).join(', ')}, which the connector does not expose`);
- }
+ const wanted = new Set();
+ for (const f of files.filter((f) => f.endsWith('.md'))) {
+ for (const t of referencedTools(readFileSync(f, 'utf8'))) wanted.add(t);
}
+ const missing = [...wanted].filter((t) => !declared.has(t)).sort();
+ if (missing.length) problems.push(`calls ${missing.map((t) => `\`${t}\``).join(', ')}, which the studio endpoint does not expose`);
- if (problems.length) excluded.push({ ...skill, problems, files });
+ if (problems.length) excluded.push({ ...skill, problems });
else included.push({ ...skill, files });
}
@@ -226,31 +258,123 @@ if (totalFiles > MAX_FILES) {
process.exit(1);
}
-if (checkOnly) {
- console.log(`\n${included.length} skill(s) would ship, ${excluded.length} excluded. Nothing written (--check).`);
- process.exit(0);
+function readme() {
+ // A description is free text: a raw < or > would render as an HTML tag and
+ // vanish (the <agent-3d> element does exactly that), and a pipe would split
+ // the row into the wrong number of cells.
+ const cell = (text) =>
+ normalizeDashes(text)
+ .split('. ')[0]
+ .replace(/&/g, '&amp;')
+ .replace(/</g, '&lt;')
+ .replace(/>/g, '&gt;')
+ .replace(/\|/g, '\\|');
+ const rows = included
+ .map((s) => `| [\`${s.name}\`](${s.name}/SKILL.md) | ${cell(s.fm.description)}. |`)
+ .join('\n');
+ return `# three.ws 3D Agent Skills
+
+The platform's 3D creation skills, packaged so any agent runtime can load them.
+Each folder is a self-contained skill: a \`SKILL.md\` whose frontmatter says when
+to trigger it, and instructions for driving the free, keyless 3D tools on
+${CONNECTOR}.
+
+| Skill | What it does |
+| --- | --- |
+${rows}
+
+## Use them
+
+Download the whole set:
+
+\`\`\`bash
+curl -O https://three.ws/skills/3d-studio/${ZIP_NAME}
+\`\`\`
+
+Or read one directly, no clone required:
+
+\`\`\`bash
+curl https://three.ws/skills/3d-studio/${included[0].name}/SKILL.md
+\`\`\`
+
+Drop a folder into \`.claude/skills/\` for Claude Code or the Claude apps, upload
+the zip on the Skills tab of an OpenAI plugin submission, or point any other
+agent runtime at the same files. Nothing here needs an account, an API key, or a
+payment: the platform covers provider cost on the free lanes.
+
+## Generated, not hand-maintained
+
+This directory is produced by
+[\`scripts/build-openai-skills-bundle.mjs\`](../../../scripts/build-openai-skills-bundle.mjs)
+from the canonical pack in [\`.agents/skills/\`](../../../.agents/skills).
+Edit the skill there, then run \`npm run build:openai-skills\`.
+\`npm run check:openai-skills\` fails if this copy has drifted.
+
+Only skills tagged \`3d/creative\` and \`cross-platform-safe\` are published here,
+and any skill referencing a tool the studio endpoint does not expose is dropped:
+a skill that tells a model to call a tool that is not there is a dead path, not a
+feature.
+`;
}
-rmSync(STAGE, { recursive: true, force: true });
-mkdirSync(STAGE, { recursive: true });
+/** Build the published tree into `dest`. Returns the staged file list. */
+function publish(dest) {
+ rmSync(dest, { recursive: true, force: true });
+ mkdirSync(dest, { recursive: true });
-for (const skill of included) {
- for (const file of skill.files) {
- const dest = join(STAGE, skill.name, relative(skill.dir, file));
- mkdirSync(dirname(dest), { recursive: true });
- const raw = readFileSync(file);
- writeFileSync(dest, file.endsWith('.md') ? normalizeDashes(raw.toString('utf8')) : raw);
+ const staged = [];
+ for (const skill of included) {
+ for (const file of skill.files) {
+ const rel = join(skill.name, relative(skill.dir, file));
+ const out = join(dest, rel);
+ mkdirSync(dirname(out), { recursive: true });
+ const raw = readFileSync(file);
+ writeFileSync(out, file.endsWith('.md') ? normalizeDashes(raw.toString('utf8')) : raw);
+ staged.push(rel);
+ }
}
+ staged.sort();
+
+ // A fixed timestamp and a sorted file list are what make the archive
+ // reproducible; without both, every rebuild rewrites a tracked binary.
+ execFileSync('touch', ['-t', STAMP, ...staged], { cwd: dest });
+ execFileSync('zip', ['-qX', ZIP_NAME, ...staged], { cwd: dest });
+ writeFileSync(join(dest, 'README.md'), readme());
+ return staged;
+}
+
+if (checkOnly) {
+ const tmp = join(ROOT, 'node_modules', '.cache', 'openai-skills-check');
+ publish(tmp);
+ const expected = walk(tmp).map((f) => relative(tmp, f));
+ const actual = existsSync(PUBLISH_DIR) ? walk(PUBLISH_DIR).map((f) => relative(PUBLISH_DIR, f)) : [];
+ const drift = [];
+ for (const rel of new Set([...expected, ...actual])) {
+ const a = existsSync(join(tmp, rel)) ? readFileSync(join(tmp, rel)) : null;
+ const b = existsSync(join(PUBLISH_DIR, rel)) ? readFileSync(join(PUBLISH_DIR, rel)) : null;
+ if (!a) drift.push(`${rel}: published but no longer generated`);
+ else if (!b) drift.push(`${rel}: generated but missing from the published copy`);
+ else if (!a.equals(b)) drift.push(`${rel}: content differs`);
+ }
+ rmSync(tmp, { recursive: true, force: true });
+ if (drift.length) {
+ console.error(`\n${relative(ROOT, PUBLISH_DIR)} has drifted from .agents/skills:`);
+ for (const d of drift) console.error(` ${d}`);
+ console.error('\nRun: npm run build:openai-skills');
+ process.exit(1);
+ }
+ console.log(`\n${relative(ROOT, PUBLISH_DIR)} matches .agents/skills.`);
+ process.exit(0);
}
-rmSync(ZIP, { force: true });
-execFileSync('zip', ['-q', '-r', ZIP, '.'], { cwd: STAGE });
+publish(PUBLISH_DIR);
-const zipBytes = statSync(ZIP).size;
+const zipBytes = statSync(join(PUBLISH_DIR, ZIP_NAME)).size;
if (zipBytes > MAX_ZIP_BYTES) {
console.error(`\nbundle is ${(zipBytes / 1024 / 1024).toFixed(1)}MB, over the 50MB upload limit`);
process.exit(1);
}
-console.log(`\nwrote ${relative(ROOT, ZIP)} (${(zipBytes / 1024).toFixed(1)} KB, ${totalFiles} file(s), ${included.length} skill(s))`);
-console.log('upload it on the Skills tab of the plugin submission.');
+console.log(`\npublished ${relative(ROOT, PUBLISH_DIR)}`);
+console.log(` ${included.length} skill(s), ${totalFiles} file(s), ${ZIP_NAME} is ${(zipBytes / 1024).toFixed(1)} KB`);
+console.log(` live at https://three.ws/skills/3d-studio/ after the next deploy`);