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
// `three-ws skills`: browse the public community skills registry and import a
// skill onto one of your agents as an editable prompt-only custom skill, or
// turn an OpenAPI spec / GitHub repo into an executable skill draft.
//
// three-ws skills list [--tag <tag>] [--author <name>]
// three-ws skills search <query>
// three-ws skills show <slug>
// three-ws skills import <slug> --agent <agent-id> [--disabled] [--yes] [--acknowledge-gated]
// three-ws skills import <url-or-owner/repo>
// three-ws skills installed --agent <agent-id>
// three-ws skills drafts
//
// Every subcommand takes --json. Reads are public; import, installed, and
// drafts use the stored credential (`three-ws login`) or THREE_WS_API_KEY.
// Server side: /api/skills/community, /api/agents/:id/custom-skills, and
// /api/skills/import (docs/skills.md). A community import installs a
// prompt-only skill directly onto one agent; a URL import generates an
// executable bundle (manifest.json/tools.json/handlers.js) saved as a draft
// under your account, disabled until you choose to enable it.
import { requestJson, ApiError } from '../http.js';
import { bearerFor } from '../oauth.js';
import { readStore, resolveOrigin } from '../store.js';
import { systemEnv } from '../paths.js';
import { createInterface } from 'node:readline/promises';
import { EXIT_CODES, isNonInteractive } from '../automation.js';
export const SKILLS_USAGE = `Usage:
three-ws skills list [--tag <tag>] [--author <name>] [--json]
three-ws skills search <query> [--json]
three-ws skills show <slug> [--json]
three-ws skills import <slug> --agent <agent-id> [--disabled] [--yes] [--acknowledge-gated] [--json] (alias: install)
three-ws skills import <openapi-url-or-owner/repo> [--json]
three-ws skills installed --agent <agent-id> [--json]
three-ws skills drafts [--json]
An external skill (origin: external) comes from a third-party repository that
three.ws has not reviewed. Importing one prints its source and pinned commit and
asks you to confirm; without a terminal, pass --yes. It is scanned first, and a
skill that asks to spend, sign or message also needs --acknowledge-gated.
Browse every skill: https://three.ws/skills/community`;
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
// Community slugs (e.g. "risk-manager") never contain a slash; a bare
// "owner/repo" shorthand or a full URL always does, which is how `import`
// tells the two kinds of argument apart without a separate subcommand.
export function isImportUrl(arg) {
return typeof arg === 'string' && (/^https?:\/\//i.test(arg) || /^[\w.-]+\/[\w.-]+$/.test(arg));
}
// Flags that never take a value, so `--json risk-manager` keeps `risk-manager` positional.
const BOOLEAN_FLAGS = new Set(['json', 'yes', 'disabled', 'acknowledge-gated', 'non-interactive', 'no-color']);
/** Split argv into positionals and --flags (a flag followed by a non-flag takes it as its value). */
export function parseSkillsArgs(argv) {
const positional = [];
const flags = {};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (!a.startsWith('--')) {
positional.push(a);
continue;
}
const [key, inline] = a.slice(2).split('=', 2);
if (inline !== undefined) flags[key] = inline;
else if (!BOOLEAN_FLAGS.has(key) && argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) flags[key] = argv[++i];
else flags[key] = true;
}
const sub = positional[0] === 'install' ? 'import' : positional[0] || 'list';
return { sub, args: positional.slice(1), flags };
}
async function authHeaders(env) {
const key = env.vars.THREE_WS_API_KEY;
const bearer = key || (await bearerFor(env));
if (!bearer) {
throw new ApiError('not signed in. Run `npx three-ws login`, or set THREE_WS_API_KEY.', { code: 'login_required' });
}
return { authorization: `Bearer ${bearer}` };
}
function pad(s, n) {
const str = String(s ?? '');
return str.length >= n ? `${str.slice(0, n - 1)}…` : str.padEnd(n);
}
/** One line per skill, fixed columns. */
export function formatSkillTable(skills) {
if (!skills.length) return 'No skills match. Try `three-ws skills list` with no filters.';
const lines = [`${pad('SLUG', 24)} ${pad('TOKENS', 7)} ${pad('TAGS', 30)} DESCRIPTION`];
for (const s of skills) {
lines.push(`${pad(s.slug, 24)} ${pad(`~${s.tokens}`, 7)} ${pad(s.tags.join(','), 30)} ${s.description}`);
}
return lines.join('\n');
}
/** The installed list with the budget line the chat path enforces. */
export function formatInstalled({ skills, budget }) {
const head = `Budget: ${budget.used_tokens} / ${budget.cap_tokens} tokens injected (${budget.injected_count} of ${skills.length} skills)`;
if (!skills.length) return `${head}\nNo custom skills yet. Import one: three-ws skills import <slug> --agent <agent-id>`;
const rows = skills.map((s) => {
const state = s.injected ? 'on' : s.skip_reason === 'disabled' ? 'off' : 'over budget';
const update = s.registry?.update_available ? ' (update available)' : '';
return `${pad(s.slug, 24)} ${pad(`~${s.tokens}`, 7)} ${pad(state, 12)} ${s.id}${update}`;
});
return [head, `${pad('SLUG', 24)} ${pad('TOKENS', 7)} ${pad('STATE', 12)} ID`, ...rows].join('\n');
}
/** The external skill with this slug, or null when the slug is unknown or in-repo. */
async function externalSkill(origin, slug) {
try {
const { skill } = await requestJson(`${origin}/api/skills/community/${encodeURIComponent(slug)}`);
return skill?.origin === 'external' ? skill : null;
} catch (err) {
if (err instanceof ApiError && err.status === 404) return null;
throw err;
}
}
/** Ask on the terminal. Without one, the answer is no: an external skill never installs unattended. */
async function askYesNo(question) {
if (!process.stdin.isTTY || !process.stderr.isTTY) return false;
const rl = createInterface({ input: process.stdin, output: process.stderr });
try {
return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
} finally {
rl.close();
}
}
/** The notice shown before an external skill is installed. */
export function externalNotice(skill) {
return [
`${skill.name} (${skill.slug}) is an EXTERNAL skill, not reviewed by three.ws.`,
` Source: ${skill.source}`,
` Commit: ${skill.ref}`,
` License: ${skill.license}`,
` Read it: ${skill.tree_url}`,
'It is a set of instructions your agent will follow. It is scanned before install and never enabled automatically.',
].join('\n');
}
/** Scan an external skill at its pinned commit, then approve exactly the scanned bytes. */
async function importExternal({ skill, agent, headers, origin, flags, confirm }) {
const notice = externalNotice(skill);
if (!flags.yes && !(await confirm(`${notice}\nInstall onto agent ${agent}?`))) {
return {
code: EXIT_CODES.GUARD,
output: `${notice}\n\nNot installed. Re-run with --yes to confirm (required when there is no terminal).`,
};
}
const { data: scanned } = await requestJson(`${origin}/api/skill-imports/scan`, {
method: 'POST',
headers,
json: { agent_id: agent, registry: skill.import.registry, skill: skill.import.skill },
});
const request = scanned.request;
if (request.status === 'refused' || request.verdict === 'refused') {
return { code: EXIT_CODES.GUARD, output: `${notice}\n\nThe scan refused this skill (${request.verdict}); it was not installed. Details: ${origin}/skills/import` };
}
if (request.gated && !flags['acknowledge-gated']) {
return {
code: EXIT_CODES.GUARD,
output: `${notice}\n\nThis skill asks to spend, sign or send messages. It stays under the spend gate and needs --acknowledge-gated to install. Review the scan at ${origin}/skills/import first.`,
request,
};
}
const { data } = await requestJson(`${origin}/api/skill-imports/requests/${request.id}`, {
method: 'POST',
headers,
json: { decision: 'approve', acknowledge_gated: Boolean(flags['acknowledge-gated']), enabled: !flags.disabled },
});
return { code: 0, data, installed: data.skill, notice };
}
/**
* Run a `skills` subcommand. Returns { code, output } so the dispatcher decides
* where it goes; nothing here writes to stdout directly.
*/
export async function runSkills(argv, { env = systemEnv(), origin: originFlag, confirm = askYesNo } = {}) {
const { sub, args, flags } = parseSkillsArgs(argv);
const origin = resolveOrigin({ flag: originFlag || flags.origin, env, store: readStore(env) });
const json = Boolean(flags.json);
if (isNonInteractive(flags, env)) confirm = async () => false;
const done = (data, text) => ({ code: 0, output: json ? JSON.stringify(data, null, 2) : text });
if (sub === 'list' || sub === 'search') {
const q = new URLSearchParams();
if (sub === 'search') {
if (!args.length) return { code: EXIT_CODES.USAGE, output: SKILLS_USAGE };
q.set('q', args.join(' '));
}
if (typeof flags.tag === 'string') q.set('tag', flags.tag);
if (typeof flags.author === 'string') q.set('author', flags.author);
const data = await requestJson(`${origin}/api/skills/community?${q}`);
return done(data, `${formatSkillTable(data.skills)}\n\n${data.count} of ${data.total} skills. Import: three-ws skills import <slug> --agent <agent-id>`);
}
if (sub === 'show') {
if (!args[0]) return { code: EXIT_CODES.USAGE, output: SKILLS_USAGE };
const { skill } = await requestJson(`${origin}/api/skills/community/${encodeURIComponent(args[0])}`);
return done(skill, `${skill.name} (${skill.slug} v${skill.version}) by ${skill.author}\n${skill.description}\nTags: ${skill.tags.join(', ')} ~${skill.tokens} tokens\nSource: ${skill.source_url}\n\n${skill.body}`);
}
if (sub === 'import' && isImportUrl(args[0])) {
const headers = await authHeaders(env);
const { data } = await requestJson(`${origin}/api/skills/import`, {
method: 'POST',
headers,
json: { url: args[0] },
});
const toolCount = data.manifest?.provides?.tools?.length || 0;
const toolLine = data.kind === 'openapi' ? `${toolCount} tool${toolCount === 1 ? '' : 's'} generated.` : 'declarative skill (no executable tools; README-only).';
return done(
data,
`Imported from ${data.sourceUrl}: ${toolLine}\n` +
`Draft id: ${data.id} (disabled; it never runs until you enable it)\n` +
`Bundle: ${origin}${data.bundleUri}\n` +
`List your drafts: three-ws skills drafts`,
);
}
if (sub === 'drafts') {
const headers = await authHeaders(env);
const { data } = await requestJson(`${origin}/api/skills/import`, { headers });
if (!data.length) return done(data, 'No skill drafts yet. Create one: three-ws skills import <openapi-url-or-owner/repo>');
const rows = data.map((d) => `${pad(d.id, 38)} ${pad(d.kind, 12)} ${pad(d.enabled ? 'enabled' : 'disabled', 10)} ${d.sourceUrl}`);
return done(data, [`${pad('ID', 38)} ${pad('KIND', 12)} ${pad('STATE', 10)} SOURCE`, ...rows].join('\n'));
}
if (sub === 'import' || sub === 'installed') {
const agent = flags.agent;
if (typeof agent !== 'string' || !UUID_RE.test(agent)) {
return { code: 2, output: `--agent <agent-id> is required (a uuid; list yours with GET ${origin}/api/agents).\n\n${SKILLS_USAGE}` };
}
const headers = await authHeaders(env);
const base = `${origin}/api/agents/${agent}/custom-skills`;
if (sub === 'installed') {
const { data } = await requestJson(base, { headers });
return done(data, formatInstalled(data));
}
if (!args[0]) return { code: EXIT_CODES.USAGE, output: SKILLS_USAGE };
try {
const { data } = await requestJson(base, {
method: 'POST',
headers,
json: { source: 'community', slug: args[0], enabled: !flags.disabled },
});
const { skill, budget } = data;
const state = skill.injected
? 'active in the agent\'s next reply'
: skill.skip_reason === 'over_budget'
? `saved but NOT injected: it does not fit the ${budget.cap_tokens}-token budget. Disable another skill to make room.`
: 'saved, disabled';
return done(data, `Imported ${skill.name} (${skill.slug}) onto ${agent}: ${state}.\nBudget: ${budget.used_tokens} / ${budget.cap_tokens} tokens.\nManage: ${origin}/skills/community?agent=${agent}`);
} catch (err) {
if (err instanceof ApiError && (err.code === 'not_found' || err.status === 404)) {
const external = await externalSkill(origin, args[0]);
if (external) {
const result = await importExternal({ skill: external, agent, headers, origin, flags, confirm });
if (result.code !== 0) return result;
const skill = result.installed;
return done(
result.data,
`${result.notice}\n\nImported ${external.name} (${external.slug}) onto ${agent}${skill?.injected ? ': active in the agent\'s next reply' : ': saved, disabled or over budget'}.\nManage: ${origin}/skills/community?agent=${agent}`,
);
}
}
if (err instanceof ApiError && err.code === 'already_installed') {
return { code: 1, output: `${args[0]} is already installed on this agent (skill ${err.body?.skill_id}). Manage it at ${origin}/skills/community?agent=${agent}` };
}
throw err;
}
}
return { code: 2, output: `Unknown skills subcommand "${sub}".\n\n${SKILLS_USAGE}` };
}