Skip to content
weside.aiweside docs

Skills SDK

A skill is a package that teaches your companion something new: extra context, a set of tools it may use, optional sub-agents, and hooks that fire on a schedule or an event. Skills are how the platform’s behaviour grows without changing the companion’s core identity.

What it is

Section titled “What it is”

Every skill is described by a manifest — a JSON document validated against a fixed schema. The manifest is the contract; the heavy content (instructions, reference docs) lives in files the manifest points to, loaded only when needed. That layering keeps an idle skill cheap (≈50 tokens of metadata) and only pays for the detail when the skill is actually used.

A manifest declares:

  • name, version, description, author — identity. name is lowercase-hyphenated, version is semver (1.0.0).
  • context — whether a SKILL.md (the how-to, ~500 tokens) and a reference.md (deep detail, ~2000 tokens) exist.
  • tools — tools the skill binds, each core (a built-in companion tool) or composio (an external action), and whether it’s required.
  • agents — optional sub-agents, each with its own prompt and a whitelist of tools it may call.
  • hooks — when the skill acts on its own: on_schedule (cron), on_event, on_before_model, on_after_model, or on_agent_complete, each with a config and an action (send a message, call an agent, or take a silent turn).

Why it matters to you

Section titled “Why it matters to you”

A skill is the unit of reusable companion capability. Understanding the manifest tells you exactly what a skill can touch — which tools it gets, when it runs unprompted — before you install it, and shows you the shape you’d build toward when authoring your own.

How you use it

Section titled “How you use it”

Today the developer surface is installation and configuration, exposed over the REST API under /api/v1/companions/{id}/skills:

Terminal window
# List skills published on the platform
curl https://api.weside.ai/api/v1/companions/available \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"


# Install one on a companion
curl -X POST https://api.weside.ai/api/v1/companions/{companion_id}/skills \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skill_definition_id": 42}'

You can also list installed skills, update a skill’s config or toggle it on and off, and uninstall it — the same operations the app’s Skill view drives.

Limits & edge cases

Section titled “Limits & edge cases”
  • Authoring is manifest-first, not yet self-serve. The schema above is real and stable, but a public “publish your own skill” SDK and marketplace are still landing — today’s published skills are seeded on the platform. Build against the manifest shape; the publishing path is where this is heading.
  • Tools must already exist. A manifest can only bind a core tool the platform exposes or a composio action you’ve connected — it can’t define brand-new tool code.
  • Hooks are gated. Scheduled and event hooks run under the companion’s proactivity and anti-spam rules; a skill can’t bypass them to spam you.
  • Skills are per-companion. Installing on one companion doesn’t affect another.

Where next

Section titled “Where next”