Custom Skills (SKILL.md)

Create your own skills by writing SKILL.md markdown files.

Overview

YokeBot's skill system is extensible. You can define new skills by creating SKILL.md files that describe the tool's name, description, parameters, and execution behavior. The engine automatically discovers these files at startup.

SKILL.md Format

A SKILL.md file uses a structured markdown format with frontmatter-style metadata and a description body:

---
name: weather_lookup
description: Look up current weather conditions for a given city.
parameters:
  - name: city
    type: string
    required: true
    description: The city name to look up weather for.
  - name: units
    type: string
    required: false
    default: metric
    description: Temperature units (metric or imperial).
---

# Weather Lookup

This skill queries an external weather API and returns the current temperature,
humidity, wind speed, and conditions for a given city.

## Usage Notes

- City names should be unambiguous. Include the country code if needed (e.g., "London, UK").
- Results are cached for 30 minutes to reduce API calls.

File Placement

Place your SKILL.md files in the skills directory within the engine package:

packages/engine/skills/
  weather_lookup/
    SKILL.md
  my_other_skill/
    SKILL.md

Each skill gets its own directory. The engine scans all subdirectories of the skills folder for SKILL.md files.

Parameter Types

Type	Description	Example
string	Free text input.	"New York"
number	Numeric value (integer or float).	42
boolean	True or false.	true
enum	One of a predefined set of values.	"metric" \| "imperial"
array	A list of values.	["tag1", "tag2"]

Skill Execution Handler

For custom skills that need server-side logic beyond what the LLM can do, you can add an execution handler alongside the SKILL.md file. Create an index.ts file in the same directory:

// packages/engine/skills/weather_lookup/index.ts
import type { SkillHandler } from '@yokebot/engine'

export const handler: SkillHandler = async (params) => {
  const { city, units = 'metric' } = params
  const response = await fetch(`https://api.weather.example/v1?city=${city}&units=${units}`)
  const data = await response.json()
  return {
    temperature: data.temp,
    conditions: data.conditions,
    humidity: data.humidity,
  }
}

Testing Custom Skills

After creating a skill, restart the engine and check the logs for successful skill registration. Then assign the skill to an agent and test it via chat.

lightbulb

Use pnpm dev and check the terminal output for "[skills] Loaded: weather_lookup" to confirm your skill was discovered.