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(cli): three-ws skills import <url> generates a draft from an OpenAPI spec or repo

nirholasdf5e2d380fc8
diff --git a/packages/three-ws-cli/src/commands/skills.js b/packages/three-ws-cli/src/commands/skills.js
index 6957067e9..64694d120 100644
--- a/packages/three-ws-cli/src/commands/skills.js
+++ b/packages/three-ws-cli/src/commands/skills.js
@@ -1,15 +1,22 @@
// `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.
+// 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]
+// 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 and installed use
-// the stored credential (`three-ws login`) or THREE_WS_API_KEY. Server side:
-// /api/skills/community and /api/agents/:id/custom-skills (docs/skills.md).
+// 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';
@@ -21,12 +28,21 @@ export const SKILLS_USAGE = `Usage:
three-ws skills search <query> [--json]
three-ws skills show <slug> [--json]
three-ws skills import <slug> --agent <agent-id> [--disabled] [--json]
+ three-ws skills import <openapi-url-or-owner/repo> [--json]
three-ws skills installed --agent <agent-id> [--json]
+ three-ws skills drafts [--json]
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));
+}
+
/** Split argv into positionals and --flags (a flag followed by a non-flag takes it as its value). */
export function parseSkillsArgs(argv) {
const positional = [];
@@ -109,6 +125,32 @@ export async function runSkills(argv, { env = systemEnv(), origin: originFlag }
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)) {
diff --git a/packages/three-ws-cli/tests/skills.test.js b/packages/three-ws-cli/tests/skills.test.js
new file mode 100644
index 000000000..2ea335a3f
--- /dev/null
+++ b/packages/three-ws-cli/tests/skills.test.js
@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { writeStore } from '../src/store.js';
+import { main } from '../src/cli.js';
+import { isImportUrl } from '../src/commands/skills.js';
+
+const ORIGIN = 'https://three.ws';
+const KEY = 'sk_live_cli_skills_test_key_00000000';
+
+function tempEnv() {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'three-ws-skills-'));
+ return { home, platform: process.platform, cwd: home, vars: { THREE_WS_NO_BROWSER: '1' } };
+}
+
+function reply(status, body) {
+ return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+async function run(argv, env) {
+ let out = '';
+ const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+ out += String(chunk);
+ return true;
+ });
+ const err = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+ try {
+ const code = await main(argv, env);
+ return { code, out, json: argv.includes('--json') && out ? JSON.parse(out) : null };
+ } finally {
+ write.mockRestore();
+ err.mockRestore();
+ }
+}
+
+describe('isImportUrl', () => {
+ it('tells a community slug apart from a spec URL or a bare owner/repo', () => {
+ expect(isImportUrl('risk-manager')).toBe(false);
+ expect(isImportUrl('dca-planner')).toBe(false);
+ expect(isImportUrl('https://petstore3.swagger.io/api/v3/openapi.json')).toBe(true);
+ expect(isImportUrl('http://example.com/spec.yaml')).toBe(true);
+ expect(isImportUrl('sindresorhus/is-up')).toBe(true);
+ });
+});
+
+describe('three-ws skills import <url>', () => {
+ let env;
+ let fetchMock;
+ beforeEach(() => {
+ env = tempEnv();
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ fetchMock = vi.fn();
+ vi.stubGlobal('fetch', fetchMock);
+ });
+ afterEach(() => vi.unstubAllGlobals());
+
+ const DRAFT = {
+ id: 'd1',
+ kind: 'openapi',
+ enabled: false,
+ sourceUrl: 'https://petstore3.swagger.io/api/v3/openapi.json',
+ bundleUri: '/api/skills/import/d1/',
+ manifest: { provides: { tools: ['getPetById', 'findPetsByStatus'] } },
+ };
+
+ it('posts the url to /api/skills/import and returns the generated draft as --json', async () => {
+ fetchMock.mockResolvedValueOnce(reply(201, { data: DRAFT }));
+ const { code, json } = await run(
+ ['skills', 'import', 'https://petstore3.swagger.io/api/v3/openapi.json', '--json', '--origin', ORIGIN],
+ env,
+ );
+ expect(code).toBe(0);
+ const [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe(`${ORIGIN}/api/skills/import`);
+ expect(init.method).toBe('POST');
+ expect(init.headers.authorization).toBe(`Bearer ${KEY}`);
+ expect(JSON.parse(init.body)).toEqual({ url: 'https://petstore3.swagger.io/api/v3/openapi.json' });
+ expect(json.id).toBe('d1');
+ });
+
+ it('reports the generated draft in plain text, never implying it is live', async () => {
+ fetchMock.mockResolvedValueOnce(reply(201, { data: DRAFT }));
+ const { code, out } = await run(
+ ['skills', 'import', 'https://petstore3.swagger.io/api/v3/openapi.json', '--origin', ORIGIN],
+ env,
+ );
+ expect(code).toBe(0);
+ expect(out).toContain('2 tools generated');
+ expect(out).toContain('disabled; it never runs until you enable it');
+ });
+
+ it('routes a bare owner/repo the same way as a full URL', async () => {
+ fetchMock.mockResolvedValueOnce(
+ reply(201, {
+ data: {
+ id: 'd2',
+ kind: 'declarative',
+ enabled: false,
+ sourceUrl: 'https://github.com/sindresorhus/is-up',
+ bundleUri: '/api/skills/import/d2/',
+ manifest: { provides: { tools: [] } },
+ },
+ }),
+ );
+ const { code } = await run(['skills', 'import', 'sindresorhus/is-up', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ url: 'sindresorhus/is-up' });
+ });
+
+ it('still imports a community skill by slug onto an agent, unaffected by the url branch', async () => {
+ fetchMock.mockResolvedValueOnce(
+ reply(201, {
+ data: {
+ skill: { id: 's1', slug: 'risk-manager', name: 'Risk Manager', injected: true },
+ budget: { used_tokens: 10, cap_tokens: 1000 },
+ },
+ }),
+ );
+ const agent = '11111111-1111-4111-8111-111111111111';
+ const { code } = await run(['skills', 'import', 'risk-manager', '--agent', agent, '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ const [url] = fetchMock.mock.calls[0];
+ expect(url).toBe(`${ORIGIN}/api/agents/${agent}/custom-skills`);
+ });
+});
+
+describe('three-ws skills drafts', () => {
+ let env;
+ let fetchMock;
+ beforeEach(() => {
+ env = tempEnv();
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ fetchMock = vi.fn();
+ vi.stubGlobal('fetch', fetchMock);
+ });
+ afterEach(() => vi.unstubAllGlobals());
+
+ it('lists drafts with their enabled state', async () => {
+ fetchMock.mockResolvedValueOnce(
+ reply(200, {
+ data: [{ id: 'd1', kind: 'openapi', enabled: false, sourceUrl: 'https://petstore3.swagger.io/api/v3/openapi.json' }],
+ }),
+ );
+ const { code, out } = await run(['skills', 'drafts', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ expect(out).toContain('disabled');
+ expect(out).toContain('petstore3.swagger.io');
+ });
+
+ it('tells an empty account how to create its first draft', async () => {
+ fetchMock.mockResolvedValueOnce(reply(200, { data: [] }));
+ const { out } = await run(['skills', 'drafts', '--origin', ORIGIN], env);
+ expect(out).toContain('three-ws skills import');
+ });
+});