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): package the 3D skills for OpenAI, and refuse to ship one whose tools do not exist
nirholase27252393249
diff --git a/.gitignore b/.gitignoreindex 25f7f9520..561e90e36 100644--- a/.gitignore+++ b/.gitignore@@ -627,3 +627,6 @@ scripts/.selfie-verify/# are stripped so the paste lands clean. The source of truth is the docs/ copy;# the root file is regenerated from it and never committed./paste-*.md++# Generated submission bundle (scripts/build-openai-skills-bundle.mjs)+dist-skills/diff --git a/docs/agent-skills.md b/docs/agent-skills.mdindex a3218660c..af68e18b9 100644--- a/docs/agent-skills.md+++ b/docs/agent-skills.md@@ -88,6 +88,34 @@ 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++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:++```bash+npm run build:openai-skills # writes dist-skills/openai-plugin-skills.zip+npm run build:openai-skills -- --check # verify only, write nothing+```++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.+## The 3D-creation skillsThe platform's signature set, safe to reuse anywhere:diff --git a/package.json b/package.jsonindex 7b561e8cb..10823ac94 100644--- a/package.json+++ b/package.json@@ -430,6 +430,7 @@"pump:launch": "node scripts/pump-launch-repos.mjs","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","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.mdindex 311c147b5..1a774c72d 100644--- a/prompts/store-submissions/_generated/openai-submission.md+++ b/prompts/store-submissions/_generated/openai-submission.md@@ -552,10 +552,47 @@ does not apply: there is no login to give. Full connectivity detail is in §3.### Step 3. Skills-Import from the MCP server. It exposes 11 tools, each already carrying its four `openai/*`-annotations and its `outputTemplate`, plus two widget resources. Do not hand-edit the-annotations after import: §2.3 audits them and a wrong `readOnlyHint` on a tool that spends-compute is a documented rejection reason.+Two things land here, and they are separate.++**Tools come from the MCP server, not from this tab.** Selecting **Scan Tools** on the MCP+tab imports all 11, each already carrying its four `openai/*` annotations and its+`outputTemplate`, plus two widget resources. Do not hand-edit the annotations after import:+§2.3 audits them and a wrong `readOnlyHint` on a tool that spends compute is a documented+rejection reason.++**Skills are an optional upload, and we have one.** Skills teach the model when and how to+reach for the tools; the tools alone teach it only what exists. Build the bundle:++```bash+npm run build:openai-skills # dist-skills/openai-plugin-skills.zip+```++Upload that zip. It carries four skills, one directory each with its own `SKILL.md`:++| Skill | Triggers on | Drives |+|---|---|---|+| `generate-3d-model` | "make a 3D model of...", a prop or object from text | `forge_free`, `mesh_forge` |+| `create-3d-avatar` | "make a 3D avatar/character I can animate" | `forge_avatar`, `text_to_avatar` |+| `rig-a-model` | "rig this GLB", "add a skeleton" | `rig_mesh` |+| `embed-three-ws-avatar` | "embed a 3D avatar on my site" | the `<agent-3d>` web component |++The bundle is derived from `.agents/skills/`, not hand-assembled, and the builder enforces+the two rules that matter for review:++1. **Scope.** Only skills tagged `3d/creative` and `cross-platform-safe` ship. The pack's+ other 39 skills are wallet, payments and partner-exchange work; shipping them in a 3D+ plugin contradicts OpenAI's guidance to keep instructions scoped to the plugin's purpose,+ and none of them are reachable through this connector anyway.+2. **No dead paths.** The builder reads `tools/list` off the live connector and drops any+ skill referencing a tool that is not there. `find-3d-assets` is excluded on that rule:+ its `search_catalog` / `get_catalog_item` / `get_item_source` tools live on the full MCP+ server, not on mcp-studio. A skill that tells ChatGPT to call a tool the connector does+ not expose is a reviewer-visible failure, and inside ChatGPT there is no shell, so the+ skill's documented `curl` fallback cannot rescue it.++Adding those three catalog tools to mcp-studio is the follow-up that unlocks a fifth skill.+It is deliberately not done pre-submission: the 11 tools are already scanned and their 33+annotation justifications written, and changing the tool surface now would invalidate both.### Step 4. Promptsdiff --git a/scripts/build-openai-skills-bundle.mjs b/scripts/build-openai-skills-bundle.mjsnew file mode 100644index 000000000..175d651c5--- /dev/null+++ b/scripts/build-openai-skills-bundle.mjs@@ -0,0 +1,256 @@+#!/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.+//+// 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+//+// Why a dedicated builder rather than zipping .agents/skills wholesale:+//+// 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.+//+// 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.+//+// 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.++import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, statSync } from 'node:fs';+import { join, resolve, dirname, relative } from 'node:path';+import { fileURLToPath } from 'node:url';+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 CONNECTOR = process.env.OPENAI_CONNECTOR_URL || 'https://three.ws/api/mcp-studio';++// OpenAI's documented upload limits for a skills bundle.+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');++/** Minimal frontmatter reader: the same subset build-skills-pack.mjs relies on. */+function frontmatter(text) {+ const m = text.match(/^---\n([\s\S]*?)\n---\n/);+ if (!m) return null;+ const out = {};+ let section = null;+ for (const line of m[1].split('\n')) {+ if (!line.trim() || line.trimStart().startsWith('#')) continue;+ const nested = line.match(/^ {2}([A-Za-z0-9_-]+):\s*(.*)$/);+ if (nested && section) {+ out[section][nested[1]] = nested[2].trim();+ continue;+ }+ const top = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);+ if (!top) continue;+ if (top[2].trim() === '') {+ section = top[1];+ out[section] = {};+ } else {+ section = null;+ out[top[1]] = top[2].trim();+ }+ }+ return out;+}++/**+ * Tool names a skill instructs the model to CALL, as opposed to snake_case+ * words in prose. Three call-site shapes appear across the pack.+ *+ * Markdown tables are the subtle one: a pack file may list tools in a table+ * whose tool column is not the first (`| Lane | Tool | Cost |`), while another+ * table in the same file lists ERROR CODES in its first column+ * (`| lane_degraded | ... |`). Reading whichever column the header actually+ * names "Tool" is what separates a real dead path from an error-code string.+ */+function referencedTools(text) {+ const found = new Set();+ const add = (n) => n && found.add(n);+ for (const m of text.matchAll(/\*\*Tools?:\*\*\s*`([a-z][a-z0-9_]*)`/g)) add(m[1]);+ for (const m of text.matchAll(/^([a-z][a-z0-9_]*_[a-z0-9_]+)\s*\{/gm)) add(m[1]);+ for (const m of text.matchAll(/"tool"\s*:\s*"([a-z][a-z0-9_]*)"/g)) add(m[1]);++ const cells = (row) => row.replace(/^\||\|$/g, '').split('|').map((c) => c.trim());+ const lines = text.split('\n');+ let toolColumns = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i];+ if (!line.trimStart().startsWith('|')) {+ toolColumns = [];+ continue;+ }+ const next = lines[i + 1] || '';+ if (/^\s*\|[\s:|-]+\|\s*$/.test(next)) {+ 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_]*)`$/);+ if (m) add(m[1]);+ }+ }+ return found;+}++async function liveToolNames() {+ const res = await fetch(CONNECTOR, {+ method: 'POST',+ headers: {+ 'content-type': 'application/json',+ accept: 'application/json, text/event-stream',+ 'mcp-protocol-version': '2025-06-18',+ },+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),+ 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 tools = JSON.parse(line).result?.tools || [];+ if (!tools.length) throw new Error(`${CONNECTOR} returned no tools`);+ return new Set(tools.map((t) => t.name));+}++function walk(dir) {+ const out = [];+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const full = join(dir, entry.name);+ if (entry.isDirectory()) out.push(...walk(full));+ else if (entry.isFile()) out.push(full);+ }+ return out;+}++/** The submission copy is public, 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.+ return text.replace(/\s*\u2014\s*/g, ', ').replace(/\s*\u2013\s*/g, ' to ');+}++const candidates = readdirSync(SKILLS_DIR, { withFileTypes: true })+ .filter((d) => d.isDirectory())+ .map((d) => d.name)+ .sort()+ .map((name) => {+ const skillFile = join(SKILLS_DIR, name, 'SKILL.md');+ if (!existsSync(skillFile)) return null;+ const text = readFileSync(skillFile, 'utf8');+ const fm = frontmatter(text);+ 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 };+ })+ .filter(Boolean);++if (!candidates.length) {+ console.error('no skill declares metadata.category 3d/* with cross-platform-safe: true');+ process.exit(1);+}++const live = offline ? null : await liveToolNames();+if (live) console.log(`connector ${CONNECTOR} exposes ${live.size} tool(s)\n`);++const included = [];+const excluded = [];++for (const skill of candidates) {+ const problems = [];+ if (skill.fm.name !== skill.name) problems.push(`frontmatter name "${skill.fm.name}" does not match its directory`);+ 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');+ }+ 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`);+ }+ }++ if (problems.length) excluded.push({ ...skill, problems, files });+ else included.push({ ...skill, files });+}++for (const s of included) console.log(` include ${s.name} (${s.files.length} file(s))`);+for (const s of excluded) {+ console.log(` EXCLUDE ${s.name}`);+ for (const p of s.problems) console.log(` ${p}`);+}++if (!included.length) {+ console.error('\nevery candidate skill was excluded, so there is no bundle to build');+ process.exit(1);+}++const totalFiles = included.reduce((n, s) => n + s.files.length, 0);+if (totalFiles > MAX_FILES) {+ console.error(`\n${totalFiles} files exceeds the ${MAX_FILES}-file limit`);+ process.exit(1);+}++if (checkOnly) {+ console.log(`\n${included.length} skill(s) would ship, ${excluded.length} excluded. Nothing written (--check).`);+ process.exit(0);+}++rmSync(STAGE, { recursive: true, force: true });+mkdirSync(STAGE, { 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);+ }+}++rmSync(ZIP, { force: true });+execFileSync('zip', ['-q', '-r', ZIP, '.'], { cwd: STAGE });++const zipBytes = statSync(ZIP).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.');