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.

32.0 KB
Raw Blame

Skills System

Skills are the extension mechanism for three.ws — modular, portable capability bundles that tell an agent what it can do and how to do it. A skill packages together the LLM instructions, the tool schema, and the JavaScript handler that runs when the tool is called. Because a skill is just a directory of files served from any URL, the same wave skill can be installed in every agent you build without copying any code.

This document covers how to install skills, how to write them, the full context API available to handlers, the security model, and the lifecycle events that let host pages observe skill execution.


What a skill contains

Every skill is a directory (a "bundle") with up to four files:

File Required Purpose
manifest.json yes Metadata, version, dependencies, compatibility
SKILL.md yes LLM instructions — injected into the system prompt
tools.json yes (if exposing tools) JSON Schema tool definitions the LLM can invoke
handlers.js no ES module that implements each tool

A skill without handlers.js is valid — it is a declarative skill that only injects prompt context. A "british-accent" skill that contains only SKILL.md ("Speak with a British accent. Use terms like 'brilliant', 'cheers'.") needs no handlers and no tools.

Full bundle layout

wave/
├── manifest.json
├── SKILL.md
├── tools.json
├── handlers.js
├── clips/
│   ├── wave-casual.glb
│   ├── wave-enthusiastic.glb
│   └── wave-subtle.glb
├── morphs/
│   └── happy.json
├── prompts/
│   └── greeting.txt
├── assets/
└── LICENSE

Assets (clips, morphs, prompts) are co-located in the bundle. Handlers reference them via ctx.skillBaseURI — the runtime resolves relative paths against the bundle's base URL automatically.


Built-in skills

These skills come pre-installed in every agent. They live in src/agent-skills.js and require no installation.

Skill What it does
greet Wave and say hello on load
present-model Describe the loaded 3D model (name, animations, polygon count)
validate-model Run glTF validation and report errors and warnings
remember Store user-provided information to agent memory
think Surface internal reasoning as a thought bubble in the UI
sign-action Sign the current action with the connected wallet
help List available skills and commands

Built-in skills that are mcpExposed: true are also published in the platform's skills catalog (GET /api/chat-skills) as callable tools named skill_<name> (hyphens and dots converted to underscores, e.g. present-model becomes skill_present_model). The catalog is what the platform chat runtime and external tool consumers read to discover them.


Installing a skill

From the agent manifest

Reference skills by URI in the agent's manifest.json. The runtime fetches and installs them at startup:

{
  "skills": [
    { "uri": "https://your-site.com/skills/wave/", "version": "0.1.0" },
    { "uri": "ipfs://bafy.../validate-model/", "version": "^1.0.0" }
  ]
}

The URI points at any host serving the four-file bundle. The repo ships a copyable starter at examples/skills/wave/ (the same bundle Coach Leo's manifest references); host it on your own site or pin it to IPFS and reference that URI.

URIs can be HTTPS, IPFS (ipfs://), or Arweave (ar://). IPFS URIs are resolved through a gateway fallback chain (ipfs.filebase.io → 4everland.io → gateway.pinata.cloud, see src/ipfs.js).

Via the web component attribute

Pass one or more bundle URIs, comma separated (src/element.js splits on commas; versions cannot be pinned through the attribute, use the manifest for that):

<agent-3d
  agent-id="my-agent"
  skills="https://your-site.com/skills/wave/,https://your-site.com/skills/tip-jar/"
></agent-3d>

At runtime via JavaScript

const el = document.querySelector('agent-3d');
await el.installSkill('https://example.com/skills/weather/');

// List what is installed (built-in + installed skill definitions)
console.log(el.skills);

Skills your agent suggests

Every published version is scanned for secret access, undeclared network calls, hidden code and instructions that skip owner confirmation. Declare the hosts a skill calls under requires.network in manifest.json. See skill-supply-scan.md.

An agent can draft a skill from a run that verifiably worked. The draft appears under Suggested skills on the agent dashboard and installs only when you click it. See skill-candidates.md.

Skill manifest format

manifest.json describes the skill, its compatibility requirements, and what it provides:

{
  "spec": "skill/0.1",
  "name": "wave",
  "version": "0.1.0",
  "description": "Wave at the user with context-appropriate enthusiasm.",
  "author": "0xDeadBeef...",   // optional — wallet address or name
  "license": "MIT",
  "tags": ["greeting", "gesture", "mixamo-compatible"],

  // Compatibility — runtime checks these before installing
  "requires": {
    "rig": ["mixamo", "any"],  // rigs this skill works with
    "runtime": ">=0.1.0",
    "tools": ["play_clip"]     // built-in tools this skill depends on
  },

  // Skill dependencies — installed recursively before this skill
  "dependencies": {
    "https://your-site.com/skills/gesture-base/": "^1.0.0"
  },

  // What this skill adds to the agent
  "provides": {
    "tools": ["wave"],
    "triggers": ["greeting", "farewell", "introduction"]
  },

  // Content-addressed integrity (optional but recommended)
  "integrity": {
    "SKILL.md": "sha256-...",
    "tools.json": "sha256-...",
    "handlers.js": "sha256-..."
  }
}

Field reference:

Field Type Required Description
spec string yes Always "skill/0.1"
name string yes Unique identifier; must match SKILL.md frontmatter
version string yes Semver
description string yes One-line summary
requires object no Runtime/rig/tool compatibility constraints
dependencies object no Other skill URIs to install first (recursive)
provides object no Declared tools and semantic trigger tags
integrity object no SHA-256 hashes for verification before execution
sandboxPolicy string no Set to "trusted-main-thread" to bypass the worker sandbox
author string no Wallet address or author name; enforced under owned-only trust
license string no SPDX license identifier
tags array no Used by skill discovery queries

SKILL.md — LLM instructions

The SKILL.md file is injected into the agent's system prompt whenever the skill is loaded. It tells the LLM when and how to use the skill's tools. Write it as instruction, not description — it speaks directly to the model.

---
name: wave
description: Wave at the user with context-appropriate enthusiasm.
triggers:
    - user_greeting
    - user_farewell
    - introduction
cost: low
---

# Wave

When the user greets you, says goodbye, or when you are introduced to
someone, wave at them. Pick the clip based on the vibe:

- **wave-casual** — default, for most greetings
- **wave-enthusiastic** — when the user seems excited, or after a win
- **wave-subtle** — in a professional context or mid-conversation

Call `wave({ style: "casual" | "enthusiastic" | "subtle" })`.

Do not wave more than once per turn. Do not wave if you just waved.

Frontmatter fields:

Field Type Purpose
name string Must match manifest.json
description string Used in skill discovery UIs
triggers string[] Semantic tags that surface this skill in the router
cost low | medium | high Latency hint — controls eager vs. lazy loading

The runtime wraps the markdown body in a <skill name="..." version="..."> XML tag before injecting it, so the LLM can attribute which skill each instruction came from.


tools.json — tool schema

tools.json defines the callable functions the LLM sees. The format follows the Anthropic tool-use schema (input_schema, not parameters):

{
  "tools": [
    {
      "name": "wave",
      "description": "Wave at the user.",
      "input_schema": {
        "type": "object",
        "properties": {
          "style": {
            "type": "string",
            "enum": ["casual", "enthusiastic", "subtle"],
            "default": "casual"
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 500,
            "maximum": 5000,
            "default": 1500
          }
        },
        "required": []
      }
    }
  ]
}

The runtime merges tool schemas from all installed skills before each LLM call. If two skills expose a tool with the same name, the later-installed skill wins and a warning is logged.


Writing a handler

Handlers are ES modules. Export one async function per tool name. The function receives the validated arguments from the LLM call and a context object:

// handlers.js
export async function wave(args, ctx) {
  const { style = 'casual', duration_ms = 1500 } = args;

  // Try to play a style-specific clip shipped with the skill bundle.
  let played = false;
  try {
    const clip = await ctx.loadClip(
      new URL(`clips/wave-${style}.glb`, ctx.skillBaseURI).href
    );
    if (clip) {
      await ctx.viewer.play(clip, { blend: 0.2 });
      played = true;
    }
  } catch {
    // No bundled clip — fall back to built-in animation hint.
  }

  if (!played) {
    played = ctx.viewer.playAnimationByHint('wave', { duration_ms });
  }

  ctx.memory.note('waved', { style, played });
  return { ok: played, style };
}

Handler signature:

async function toolName(args, ctx) {
  // args: validated parameters from the LLM tool call
  // ctx:  SkillContext — see full API below
  return { ok: true, ...result };
}

Return { ok: true, ... } on success and { ok: false, error: 'message' } on failure. The runtime surfaces errors to the LLM and to the skill-error protocol event.

The context API

interface SkillContext {
  // Scene control
  viewer: {
    play(clip: AnimationClip, opts?: { blend?: number }): Promise<void>;
    stop(clipName?: string): void;
    setExpression(preset: string): void;
    lookAt(target: Vector3 | 'user' | 'camera'): void;
    moveTo(position: Vector3, opts?: MoveOptions): void;
    playAnimationByHint(hint: string, opts?: { duration_ms?: number }): boolean;
    scene: Scene;  // read-only reference to the Three.js scene
  };

  // LLM access
  llm: {
    complete(prompt: string, opts?: CompleteOpts): Promise<string>;
    embed(text: string): Promise<Float32Array>;
  };

  // Memory
  memory: {
    read(key: string): any;
    write(key: string, value: any): void;
    note(type: string, data: any): void;    // appends to timeline
    recall(query: string): Promise<MemoryEntry[]>;
  };

  // Asset loading (paths resolved relative to skillBaseURI)
  loadClip(uri: string): Promise<AnimationClip>;
  loadGLB(uri: string): Promise<GLTF>;
  loadJSON(uri: string): Promise<any>;
  skillBaseURI: string;  // base URL of this skill's bundle

  // Network access, subject to CORS
  fetch(uri: string, opts?: RequestInit): Promise<Response>;

  // Cross-skill calls
  call(toolName: string, args: any): Promise<any>;

  // User interaction
  speak(text: string): Promise<void>;
  listen(opts?: ListenOpts): Promise<string>;
}

Key points:

  • ctx.skillBaseURI always ends with /. Use new URL('./clips/file.glb', ctx.skillBaseURI).href for portable asset resolution.
  • ctx.memory.recall() is substring search — no embeddings yet.
  • ctx.call() invokes another tool by name. It crosses skill boundaries — you can call a built-in like speak from inside a custom skill handler.
  • ctx.viewer.scene is a read-only reference. Use the viewer methods to manipulate state rather than mutating the scene graph directly.
  • Individual ctx.* calls time out after 30 seconds. A timed-out handler surfaces as { error: "..." } without crashing the agent.

Skill sandboxing

By default, handlers run in a Web Worker (src/skills/sandbox-worker.js). The worker has no DOM, no window, no document, no localStorage, and no cookie access.

The worker receives handler source as text and loads it via a blob: URL dynamic import(). Each ctx.* call from inside the worker becomes a structured-cloneable postMessage round-trip to the main thread, which validates and dispatches it, then returns the result. Non-serializable objects (like AnimationClip or GLTF) are stored in a host-side handle registry and represented to the worker as opaque handle strings.

Sandboxed handlers cannot:

  • Read document.cookie, window.localStorage, sessionStorage, or any DOM API
  • Access window, navigator, or location
  • Import external modules (no import statements in handler source — the blob context has no base URL for relative imports)
  • Make network requests outside ctx.fetch and ctx.loadJSON (standard CORS rules apply)

Sandboxed handlers can still do everything via ctx.* — animation, memory, speech, LLM calls, cross-skill calls — through the postMessage proxy.

Trusted main-thread opt-out

Owner-signed skills that require direct Three.js access, window.* APIs, or per-frame work can opt out of the sandbox:

{
  "sandboxPolicy": "trusted-main-thread"
}

When this flag is honored, handlers.js is loaded via a direct import() in the main thread. It is honored only for bundles served from the embedding page's own origin or from the origin that served the <agent-3d> library, and never under any trust. A bundle from any other origin that sets the flag still installs and runs, inside the worker sandbox.


Trust and security

The SkillRegistry enforces a trust policy set per agent:

Mode Behavior
owned-only Only run skills where manifest.author matches the agent owner's wallet (default)
whitelist Allow skills from a configured list of publisher wallets
any All skills from any URL are allowed — use for kiosks and demos

Trust is configured in the agent manifest or passed to SkillRegistry:

new SkillRegistry({ trust: 'owned-only', ownerAddress: '0xDeadBeef...' });

If a skill's author field does not match ownerAddress under owned-only policy, install() throws before fetching any handler code. If integrity hashes are present in the manifest, they are verified before any handler executes.

Declarative skills (no handlers.js) are always safe to load regardless of trust policy.


Skill dependencies

Skills can depend on other skills. The registry installs dependencies recursively before the depending skill:

{
  "name": "full-coaching-kit",
  "version": "1.0.0",
  "dependencies": {
    "https://your-site.com/skills/wave/": "^0.1.0",
    "https://your-site.com/skills/validate-model/": "^1.0.0"
  },
  "provides": { "tools": [] }
}

The dependencies object maps skill URIs to version ranges. Circular dependencies are detected and rejected. If a skill URI is already installed, it is not re-fetched.


Skill lifecycle events

The agent protocol bus fires events at each stage of skill execution. Subscribe on the bus to react to skill activity:

import { protocol } from './src/agent-protocol.js';
// In the three.ws app itself the same singleton is window.VIEWER.agent_protocol.

// Fires when the runtime dispatches a tool call to a skill handler
protocol.on('perform-skill', (action) => {
  console.log('Skill starting:', action.payload.skill, action.payload.args);
});

// Fires when the handler returns successfully
protocol.on('skill-done', (action) => {
  console.log('Skill done:', action.payload.skill, action.payload.result);
});

// Fires when the handler throws or times out
protocol.on('skill-error', (action) => {
  console.error('Skill error:', action.payload.skill, action.payload.error);
});

Host pages embedding <agent-3d> also get DOM CustomEvents re-dispatched on the element for runtime activity: skill:tool-start and skill:tool-called (plus brain:*, voice:*, and memory:write). Listen with el.addEventListener('skill:tool-called', handler) when you only need tool-call notifications.

Event payloads:

Event detail shape
perform-skill { skill: string, args: object, animationHint?: string }
skill-done { skill: string, result: { ok, output?, sentiment?, data? } }
skill-error { skill: string, error: string }

skill-done results with a sentiment number (−1 to 1) trigger the avatar's empathy layer — positive values produce a celebration blend, negative values produce concern.


Calling skills programmatically

In the three.ws app, the built-in skills executor is exposed as window.VIEWER.agent_skills (an AgentSkills instance from src/agent-skills.js):

const skills = window.VIEWER.agent_skills;

// Execute a skill directly, bypassing the LLM
const result = await skills.perform('greet', { name: 'Alex' });
console.log(result); // { success: true, output: '...', sentiment: ... }

// List all registered skills
skills.list();

// Get a specific skill definition
const greetDef = skills.get('greet');

For external skills installed via SkillRegistry (src/skills/index.js), invoke through the registry:

const registry = new SkillRegistry({ trust: 'owned-only', ownerAddress });
await registry.install({ uri: 'https://example.com/skills/weather/' });

const skill = registry.findSkillForTool('get_weather');
const result = await skill.invoke('get_weather', { city: 'Berlin' }, ctx);

Skill loading sequence

When a skill URI is installed, the runtime follows this sequence:

{ uri, version }
      │
      ▼
fetch {uri}/manifest.json
      │
      ▼
enforce trust policy (author vs. ownerAddress)
      │
      ▼
verify integrity hashes (if present)
      │
      ▼
check requires.rig matches agent body.rig
      │
      ▼
install dependencies (recursive)
      │
      ▼
parallel fetch: SKILL.md, tools.json, handlers.js
      │
      ▼
merge tools into runtime tool-use schema
      │
      ▼
inject SKILL.md into system prompt as <skill> fragment
      │
      ▼
skill is live — LLM can now call its tools

Worked example: the wave skill

The wave skill is the minimal complete example — small enough to reproduce here in full. Create it as a wave/ directory anywhere you serve static files; every file the bundle needs is listed below. For real, installable bundles that ship with the repo, see examples/skills/ (pump-fun, solana-wallet, and friends) and public/skills/ (tip-jar, crypto-price, dca).

manifest.json

{
  "spec": "skill/0.1",
  "name": "wave",
  "version": "0.1.0",
  "description": "Wave at the user with context-appropriate enthusiasm.",
  "license": "MIT",
  "tags": ["greeting", "gesture", "mixamo-compatible"],
  "requires": {
    "rig": ["mixamo", "any"],
    "runtime": ">=0.1.0",
    "tools": []
  },
  "provides": {
    "tools": ["wave"],
    "triggers": ["greeting", "farewell", "introduction"]
  }
}

tools.json

{
  "tools": [
    {
      "name": "wave",
      "description": "Wave at the user.",
      "input_schema": {
        "type": "object",
        "properties": {
          "style": {
            "type": "string",
            "enum": ["casual", "enthusiastic", "subtle"],
            "default": "casual"
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 500,
            "maximum": 5000,
            "default": 1500
          }
        },
        "required": []
      }
    }
  ]
}

SKILL.md

---
name: wave
description: Wave at the user with context-appropriate enthusiasm.
triggers:
    - user_greeting
    - user_farewell
    - introduction
cost: low
---

When the user greets you, says goodbye, or when you are introduced,
wave at them. Pick the clip based on the vibe:

- **wave-casual** — default, for most greetings
- **wave-enthusiastic** — when the user seems excited, or after a win
- **wave-subtle** — in a professional context or mid-conversation

Call `wave({ style: "casual" | "enthusiastic" | "subtle" })`.

Do not wave more than once per turn.

handlers.js

export async function wave(args, ctx) {
  const { style = 'casual', duration_ms = 1500 } = args;

  let played = false;
  try {
    const clip = await ctx.loadClip(
      new URL(`clips/wave-${style}.glb`, ctx.skillBaseURI).href
    );
    if (clip) {
      await ctx.viewer.play(clip, { blend: 0.2 });
      played = true;
    }
  } catch {
    // No bundled clip — fall back to built-in animation hint.
  }

  if (!played) {
    played = ctx.viewer.playAnimationByHint('wave', { duration_ms });
  }

  ctx.memory.note('waved', { style, played });
  return { ok: played, style };
}

The handler tries to load a style-specific GLB clip from the bundle (e.g. clips/wave-casual.glb). If the clip is not found, it falls back to playAnimationByHint('wave'), which searches the loaded model's existing animation tracks for one tagged with the wave hint. This makes the skill work on any Mixamo avatar whether or not you ship animation clips.


Worked example: Coach Leo

examples/coach-leo/ shows a complete agent manifest that references the wave skill. Key sections of examples/coach-leo/manifest.json:

{
  "spec": "agent-manifest/0.1",
  "name": "Coach Leo",
  "body": {
    "uri": "/avatars/cz.glb",
    "rig": "mixamo",
    "boundingBoxHeight": 1.78
  },
  "brain": {
    "provider": "anthropic",
    "model": "claude-opus-4-6",
    "instructions": "instructions.md",
    "temperature": 0.8,
    "maxTokens": 2048
  },
  "skills": [
    { "uri": "../skills/wave/", "version": "0.1.0" }
  ],
  "tools": ["wave", "lookAt", "play_clip", "setExpression", "speak", "remember"]
}

The tools array in the agent manifest is the allowlist of built-in tools the LLM can call directly. The skills array references external skill bundles to install. Together they define the agent's complete capability surface.

Coach Leo's instructions.md uses the wave skill naturally:

When the user greets you, call `wave()` to wave at them.
When they describe a drill, set a focused expression with
`setExpression({ preset: "focused" })` while you explain,
then smile afterward.

This is the pattern: SKILL.md in the skill bundle explains the tool in the abstract; the agent's instructions.md tells this specific persona when and why to use it.


Publishing a skill

A skill is just a directory of static files. Publish it anywhere:

  • GitHub Releases — attach a zip, reference the raw URL
  • Vercel / Netlify / S3 — deploy the directory as a static site
  • IPFS — ipfs add -r skills/wave/ and distribute the CID
  • The platform itself: first-party bundles live under public/skills/<name>/ in this repo (e.g. public/skills/tip-jar/) and are served at https://three.ws/skills/<name>/
  • npm: publish the directory as a package and reference it via a CDN like jsDelivr

Convention: name the manifest manifest.json and co-locate handlers.js in the same directory. Agents resolve all relative paths (./clips/, ./prompts/) against the manifest's URL, so the layout must be preserved.

skills/wave/
├── manifest.json      ← fetched first
├── SKILL.md
├── tools.json
├── handlers.js
└── clips/
    ├── wave-casual.glb
    └── wave-enthusiastic.glb

For IPFS publishing, the CID of the directory becomes the stable URI. Agents can pin a specific version by CID and upgrade by updating the URI.


Importing a skill from an OpenAPI spec or a GitHub repo

Writing a bundle by hand is not the only path. @three-ws/skill-import turns a public OpenAPI/Swagger spec URL, or a GitHub repo, directly into a draft bundle: every operation becomes a tools.json entry and a generated handlers.js function that calls it, SKILL.md prose is written from the spec's own descriptions, and Swagger 2.0 specs are upgraded to OpenAPI 3 automatically. A repo whose only content is a README becomes a declarative skill (prose only, no tools), the same shape as a hand-written SKILL.md-only bundle.

curl -s -X POST https://three.ws/api/skills/import \
  -H "authorization: Bearer $THREE_WS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url": "https://petstore3.swagger.io/api/v3/openapi.json"}' | jq '.data | {id, kind, bundleUri, tools: .manifest.provides.tools}'
{
  "id": "a96ddb60-...",
  "kind": "openapi",
  "bundleUri": "/api/skills/import/a96ddb60-.../",
  "tools": ["updatePet", "addPet", "findPetsByStatus", "getPetById", "..."]
}

The CLI wraps the same endpoint:

three-ws skills import https://petstore3.swagger.io/api/v3/openapi.json
three-ws skills import sindresorhus/is-up   # owner/repo shorthand also works
three-ws skills drafts                       # list your generated drafts

Every import lands as a disabled draft, owner-scoped and labelled untrusted: it is never enabled automatically and never installed onto any agent. GET /api/skills/import lists your drafts, GET /api/skills/import/:id fetches one, and the generated bundle itself is served at bundleUri (manifest.json, SKILL.md, tools.json, handlers.js) so you can inspect every generated tool call before trusting it. PATCH /api/skills/import/:id with { "enabled": true } is the only way a draft's enabled flag ever changes; DELETE /api/skills/import/:id removes it. The same flow is available from the UI at /skills/import, under the From an API tab: paste a spec URL or repo, review the generated tool list in the result card, then enable or delete each draft from your drafts list.

Generated handlers call ctx.fetch with auth placeholders filled from the skill's declared secrets (an API key header, a bearer token, etc.), never a hardcoded credential, so the skill's eventual owner supplies the real secret at install time, the same as any other skill with a secrets declaration in its manifest.

Importing a Solana program from its Anchor IDL

The same endpoint turns an Anchor IDL into a skill, the Solana counterpart of the OpenAPI path. Send idl_url (any public IDL JSON) or program_id (the importer reads the IDL the program published on chain), plus an optional cluster of mainnet-beta (default) or devnet.

curl -s -X POST https://three.ws/api/skills/import \
  -H "authorization: Bearer $THREE_WS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"idl_url": "https://raw.githubusercontent.com/nirholas/three.ws/main/contracts/idl/skill_license.json"}' \
  | jq '.data | {id, kind, tools: [.tools.tools[].name]}'

Per account type you get a read_<account> tool that fetches and decodes an account by address. Per instruction you get two tools:

  • preview_<instruction> builds the unsigned instruction and returns its accounts, base64 and hex data, a plain summary and a risk read. It never signs and never reads a secret.
  • send_<instruction> returns the same payload with status: "confirmation_required". It is marked destructiveHint: true, signs and sends nothing, and exists to hand the instruction to the wallet owner's confirm-gated flow, which executes only after an explicit yes.

Accounts with a fixed address in the IDL (token program, system program) are filled in; every other account is passed by the caller, because PDA derivation needs ed25519 curve checks the sandbox does not have. The generated SKILL.md ends with a risk panel that flags instructions that move tokens, spend SOL, close accounts or change an authority. IDLs carry no Anchor constraints, so a flag is a prompt to read the program and a clean row is not an audit. Drafts are disabled and owner-scoped exactly like OpenAPI imports (kind: "anchor"). Pre-0.30 IDLs (isMut/isSigner, no discriminators) are normalized on import.


Marketplace skills: install once, applied in every chat

Alongside URI-addressed bundles, the platform hosts a community catalog at /marketplace?tab=skills. A marketplace skill is a database-backed record with a description, category, tags, ratings, and either:

  • content: a markdown playbook (the equivalent of a standalone SKILL.md): analysis frameworks, trading checklists, integration guides. This is the common kind.
  • schema_json: a JSON tool-schema pack for agents that bring their own executor.

Installing is free and instant (POST /api/skills/:id/install, sign-in required; DELETE uninstalls). What an install does:

  • Knowledge skills load into your chats. /api/chat reads your installed skills at request time (api/_lib/installed-skills.js) and injects their playbooks into the system prompt, so your agent follows them anywhere you chat signed-in on three.ws (the /app workspace included). Budgets keep prompts sane: newest 8 installs, 6k chars per skill, 24k total. Each reply's SSE done event lists the slugs that were in context as skills_applied.
  • Your installed set is one API call away. GET /api/skills?installed=true (authed) returns the full payload, content and schema_json included, so an external agent, MCP client, or script can hydrate itself from your library.

Paid skills price per call, not per install: the detail page shows an x402 endpoint (GET /api/x402/skill-call?skill=<slug>) any wallet can pay in USDC, settling to the author. The 402 challenge names the author's own wallet as the payee, so their share moves at settlement rather than being forwarded later, and Solana is offered first whenever the author has a Solana wallet. What the author keeps, where they watch it land, and how to verify a payout on-chain: Skill royalties.

Publish your own from the marketplace ("Publish a Skill") or POST /api/skills with { name, slug, description, category, tags, content } (or schema_json).

Browsing the catalog from code

GET /api/skills is public and takes the same filters the marketplace UI uses, so a script can reproduce any view you can link to:

Param Meaning
q Substring match across name, description, and tags
category Exact category slug (GET /api/skills/categories lists them with counts)
tag Exact tag, case-insensitive, matched against the skill's tags array
sort popular (default), new, or az
limit / cursor Page size (max 50) and the keyset cursor returned as next_cursor
installed=true Authed only: your own installed set, with content and schema_json
# Every free skill tagged "solana", newest first
curl -s 'https://three.ws/api/skills?tag=solana&sort=new&limit=50' \
  | jq '.skills[] | select(.price_per_call_usd == 0) | {name, slug, tags}'

Those filters are also the page URL, so /marketplace?tab=skills&tag=solana&sort=new opens that exact view in a browser and can be shared as-is. The retired /skills path forwards there, carrying q, category, tag, and sort with it.


Versioning

  • spec: "skill/0.1" — the skill bundle format version.
  • version in manifest.json — semver, author-controlled, used for dependency resolution.
  • Agent manifests can pin an exact version ("0.1.0") or a range ("^0.1.0").
  • The runtime prefers the highest-compatible published version within range.

See also

  • Architecture Overview — how skills fit into the agent runtime
  • Agent System — the protocol bus and built-in tool system
  • Web Component — embedding agents and passing skill attributes
  • specs/SKILL_SPEC.md — the authoritative skill bundle specification
  • specs/PERMISSIONS_SPEC.md — ERC-7710/ERC-7715 delegation for fine-grained skill permissions