***

title: SkillBase
slug: /reference/python/agents/skill-base
description: Abstract base class for creating reusable, pluggable agent skills.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[agentbase]: /docs/server-sdks/reference/python/agents/agent-base

[skills]: /docs/server-sdks/reference/python/agents/skills

[cleanup]: /docs/server-sdks/reference/python/agents/skill-base/cleanup

[definetool]: /docs/server-sdks/reference/python/agents/skill-base/define-tool

[getglobaldata]: /docs/server-sdks/reference/python/agents/skill-base/get-global-data

[gethints]: /docs/server-sdks/reference/python/agents/skill-base/get-hints

[getinstancekey]: /docs/server-sdks/reference/python/agents/skill-base/get-instance-key

[getparameterschema]: /docs/server-sdks/reference/python/agents/skill-base/get-parameter-schema

[getpromptsections]: /docs/server-sdks/reference/python/agents/skill-base/get-prompt-sections

[registertools]: /docs/server-sdks/reference/python/agents/skill-base/register-tools

[setup]: /docs/server-sdks/reference/python/agents/skill-base/setup

[skill-data]: /docs/server-sdks/reference/python/agents/skill-base/skill-data

[validate]: /docs/server-sdks/reference/python/agents/skill-base/validate

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`][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.

<Info>
  For the catalog of built-in skills and their configuration parameters, see
  the [Skills][skills] page.
</Info>

## **Class Attributes**

Define these on your subclass to configure the skill:

<ParamField path="SKILL_NAME" type="str" required={true} toc={true}>
  Unique identifier for the skill (e.g., `"weather"`, `"web_search"`). Used as
  the key when calling `agent.add_skill()`.
</ParamField>

<ParamField path="SKILL_DESCRIPTION" type="str" required={true} toc={true}>
  Human-readable description of the skill.
</ParamField>

<ParamField path="SKILL_VERSION" type="str" default="1.0.0" toc={true}>
  Semantic version string.
</ParamField>

<ParamField path="REQUIRED_PACKAGES" type="list[str]" default="[]" toc={true}>
  Python packages the skill needs. Checked on setup with `validate_packages()`.
</ParamField>

<ParamField path="REQUIRED_ENV_VARS" type="list[str]" default="[]" toc={true}>
  Environment variables the skill needs. Checked on setup with `validate_env_vars()`.
</ParamField>

<ParamField path="SUPPORTS_MULTIPLE_INSTANCES" type="bool" default="false" toc={true}>
  When `True`, the same skill can be added to an agent multiple times with
  different configurations (distinguished by a `tool_name` parameter).
</ParamField>

## **Instance Properties**

<ParamField path="agent" type="AgentBase" toc={true}>
  Reference to the parent agent.
</ParamField>

<ParamField path="params" type="dict[str, Any]" toc={true}>
  Configuration parameters (with `swaig_fields` removed).
</ParamField>

<ParamField path="logger" type="Logger" toc={true}>
  Skill-specific logger namespaced as `signalwire.skills.<SKILL_NAME>`.
</ParamField>

<ParamField path="swaig_fields" type="dict[str, Any]" toc={true}>
  SWAIG metadata extracted from params, automatically merged into tool
  definitions when using `define_tool()`.
</ParamField>

## **Methods**

<CardGroup cols={3}>
  <Card title="cleanup" href="/docs/server-sdks/reference/python/agents/skill-base/cleanup">
    Release resources when the skill is removed or the agent shuts down.
  </Card>

  <Card title="define_tool" href="/docs/server-sdks/reference/python/agents/skill-base/define-tool">
    Register a tool with automatic swaig\_fields merging.
  </Card>

  <Card title="get_global_data" href="/docs/server-sdks/reference/python/agents/skill-base/get-global-data">
    Return data to merge into the agent's global\_data dictionary.
  </Card>

  <Card title="get_hints" href="/docs/server-sdks/reference/python/agents/skill-base/get-hints">
    Return speech recognition hints for this skill.
  </Card>

  <Card title="get_instance_key" href="/docs/server-sdks/reference/python/agents/skill-base/get-instance-key">
    Get the unique key used to track this skill instance.
  </Card>

  <Card title="get_parameter_schema" href="/docs/server-sdks/reference/python/agents/skill-base/get-parameter-schema">
    Return metadata about all parameters the skill accepts.
  </Card>

  <Card title="get_prompt_sections" href="/docs/server-sdks/reference/python/agents/skill-base/get-prompt-sections">
    Return POM prompt sections for the agent.
  </Card>

  <Card title="register_tools" href="/docs/server-sdks/reference/python/agents/skill-base/register-tools">
    Register SWAIG tools with the parent agent.
  </Card>

  <Card title="setup" href="/docs/server-sdks/reference/python/agents/skill-base/setup">
    Initialize the skill and validate dependencies.
  </Card>

  <Card title="get_skill_data" href="/docs/server-sdks/reference/python/agents/skill-base/get-skill-data">
    Read this skill instance's namespaced state.
  </Card>

  <Card title="update_skill_data" href="/docs/server-sdks/reference/python/agents/skill-base/update-skill-data">
    Write this skill instance's namespaced state into a FunctionResult.
  </Card>

  <Card title="validate_env_vars" href="/docs/server-sdks/reference/python/agents/skill-base/validate-env-vars">
    Check whether all required environment variables are set.
  </Card>

  <Card title="validate_packages" href="/docs/server-sdks/reference/python/agents/skill-base/validate-packages">
    Check whether all required packages can be imported.
  </Card>
</CardGroup>

## **Examples**

### Custom skill

```python
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

```python
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()
```