SkillBase

SkillBase is the abstract base class for all agent skills. Skills are modular, reusable capabilities — such as weather lookup, web search, or calendar access — that can be added to any AgentBase agent with a single call to agent.add_skill().

Extend SkillBase to create custom skills. The SDK discovers skills automatically from the signalwire/skills/ directory and validates dependencies on load.

For the catalog of built-in skills and their configuration parameters, see the Skills page.

Class Attributes

Define these on your subclass to configure the skill:

SKILL_NAME

strRequired

Unique identifier for the skill (e.g., "weather", "web_search"). Used as the key when calling agent.add_skill().

SKILL_DESCRIPTION

strRequired

Human-readable description of the skill.

SKILL_VERSION

strDefaults to 1.0.0

Semantic version string.

REQUIRED_PACKAGES

list[str]Defaults to []

Python packages the skill needs. Checked on setup with validate_packages().

REQUIRED_ENV_VARS

list[str]Defaults to []

Environment variables the skill needs. Checked on setup with validate_env_vars().

SUPPORTS_MULTIPLE_INSTANCES

boolDefaults to false

When True, the same skill can be added to an agent multiple times with different configurations (distinguished by a tool_name parameter).

Instance Properties

agent

AgentBase

Reference to the parent agent.

params

dict[str, Any]

Configuration parameters (with swaig_fields removed).

logger

Logger

Skill-specific logger namespaced as signalwire.skills.<SKILL_NAME>.

swaig_fields

dict[str, Any]

SWAIG metadata extracted from params, automatically merged into tool definitions when using define_tool().

Methods

cleanup

Release resources when the skill is removed or the agent shuts down.

define_tool

get_global_data

Return data to merge into the agent’s global_data dictionary.

get_hints

Return speech recognition hints for this skill.

get_instance_key

Get the unique key used to track this skill instance.

get_parameter_schema

Return metadata about all parameters the skill accepts.

get_prompt_sections

Return POM prompt sections for the agent.

register_tools

setup

Initialize the skill and validate dependencies.

get_skill_data

Read this skill instance’s namespaced state.

update_skill_data

Write this skill instance’s namespaced state into a FunctionResult.

validate_env_vars

Check whether all required environment variables are set.

validate_packages

Check whether all required packages can be imported.

Examples

Custom skill

import os
from signalwire.core.skill_base import SkillBase
from signalwire import FunctionResult
class WeatherSkill(SkillBase):
    SKILL_NAME = "weather"
    SKILL_DESCRIPTION = "Provides weather information"
    SKILL_VERSION = "1.0.0"
    REQUIRED_PACKAGES = ["requests"]
    REQUIRED_ENV_VARS = ["WEATHER_API_KEY"]
    def setup(self) -> bool:
        if not self.validate_packages():
            return False
        if not self.validate_env_vars():
            return False
        self.api_key = os.getenv("WEATHER_API_KEY")
        return True
    def register_tools(self):
        self.define_tool(
            name="get_weather",
            description="Get current weather for a location",
            handler=self._get_weather,
            parameters={
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name or zip code"
                    }
                },
                "required": ["location"]
            }
        )
    def _get_weather(self, args, raw_data):
        import requests
        location = args.get("location")
        resp = requests.get(
            f"https://api.weather.com/v1/current?q={location}&key={self.api_key}"
        )
        data = resp.json()
        return FunctionResult(
            f"Weather in {location}: {data['condition']}, {data['temp']}F"
        )
    def get_hints(self):
        return ["weather", "temperature", "forecast"]
    def _get_prompt_sections(self):
        return [{
            "title": "Weather Information",
            "body": "You can check weather for any location."
        }]
    @classmethod
    def get_parameter_schema(cls):
        schema = super().get_parameter_schema()
        schema.update({
            "units": {
                "type": "string",
                "description": "Temperature units",
                "default": "fahrenheit",
                "enum": ["fahrenheit", "celsius"]
            }
        })
        return schema

Using a skill

from signalwire import AgentBase
agent = AgentBase(name="weather-agent")
agent.set_prompt_text("You are a helpful assistant.")
agent.add_skill("weather")
# Or with custom configuration
agent.add_skill("weather", {"units": "celsius"})
if __name__ == "__main__":
    agent.run()