Custom Skills

Build your own skills to give agents custom capabilities. Skills are TypeScript modules that define parameters, execution logic, and return structured results.

Skill definition API

Use defineSkill() to create a skill with typed parameters and execution logic:

typescript

import { defineSkill } from "hybrix-lab/skills"

export default defineSkill({
  id: "weather-lookup",
  label: "Weather Lookup",
  description: "Fetches current weather for a given city",

  parameters: {
    city: { type: "string", required: true, description: "City name" },
    units: { type: "string", required: false, default: "metric" },
  },

  async execute({ city, units }, context) {
    const res = await fetch(
      `https://api.weather.example/v1?q=${city}&units=${units}`
    )
    const data = await res.json()
    return {
      temperature: data.main.temp,
      condition: data.weather[0].description,
      humidity: data.main.humidity,
    }
  },
})

Execution context

The context parameter passed to execute() provides access to the agent runtime:

Property	Type	Description
context.agent	AgentConfig	The agent's configuration object
context.env	Record<string, string>	Environment variables
context.log	(msg: string) => void	Structured logger for debugging
context.store	KVStore	Persistent key-value store scoped to the skill
context.channel	ChannelInfo	Info about the channel that triggered the skill

Registering custom skills

Place your skill file in the skills/ directory and add it to your config:

json

{
  "skills": [
    { "path": "./skills/weather-lookup.ts" },
    { "path": "./skills/database-query.ts" }
  ]
}

Skills are hot-reloaded in development mode. Save the file and the agent picks up the new version instantly.

You can also publish skills to the Hybrix Market for others to install. See the Market docs for publishing guides.

Error handling

Throw an error from execute() to signal a failure. The agent receives the error message and can decide how to respond to the user.

typescript

async execute({ city }, context) {
  const res = await fetch(`https://api.weather.example/v1?q=${city}`)
  if (!res.ok) {
    throw new Error(`Weather API returned ${res.status} for city: ${city}`)
  }
  return await res.json()
}

Unhandled exceptions are caught by the runtime and logged automatically. The agent sees a generic “skill execution failed” message unless you throw with a specific message.

← Built-in Skills Shell Execution →