Skills

Packaged capabilities the model reaches for only when relevant. A skill uses progressive disclosure: only its short description is always in context; the full instructions load only when the model decides to use it. Keeps prompts small while giving agents deep, on-demand know-how.

The description is load-bearing — it's the runtime gate the model reads to decide whether to use the skill. Write it as "Use this when…". (Contrast an Instruction, whose text is always applied.)

Create a skill

import { Theazo } from 'theazo'

const theazo = new Theazo({ apiKey: process.env.THEAZO_API_KEY })

const skill = await theazo.skills.create({
  name: 'Refund processor',
  description: 'Use when a customer asks for a refund or return.', // the gate
  instructions: 'Verify the order is within 30 days, then call issue_refund with the order id.',
  toolIds: ['tool_issue_refund'],
})

Field	Type	Required	Description
`name`	`string`	yes	Human label, unique within (platform, kind).
`description`	`string`	yes	The runtime gate — tells the model WHEN to use this skill. Required.
`enabled`	`boolean`	—	Default true.
`instructions`	`string`	yes	What to do once invoked (loaded on use).
`toolIds`	`string[]`	—	Tool/MCP ids this skill may call. Default [].

Attach it to an agent

await theazo.agents.attach(agentDefinitionId, {
  customizationId: skill.id,
})

How it runs

Each attached skill is advertised to the model as a lightweight tool — just its description, so it costs almost nothing to keep in context. When the model decides the skill is relevant and calls it, its instructions are returned and loaded into the conversation. That's the "progressive disclosure": cheap to advertise, full detail only on use.

In the current release, a skill's toolIds are informational — the listed tools are available to the agent but access isn't yet scoped to only that skill. Scoping is planned.

SDK methods

theazo.skills.create(opts)SkillCreate a skill.

theazo.skills.list()Skill[]List all skills on the platform.

theazo.skills.get(id)SkillFetch one by id.

theazo.skills.update(id, opts)SkillUpdate description, instructions, or tools.

theazo.skills.delete(id)voidDelete. Blocked (409) if still attached.