{"slug":"agents-skills-system","title":"Agents Skills System — Prefabs, SkillBase, Multi-Instance, and Discovery","tags":["signalwire","agents-sdk","skills","prefabs","skillbase"],"agent_summary":"Pre-built agent prefabs (ConciergeAgent, FAQBotAgent, InfoGathererAgent, ReceptionistAgent, SurveyAgent) and the custom SkillBase pattern. Covers `add_skill`, multi-instance keying, parameter schemas, REQUIRED_PACKAGES/ENV_VARS validation, and skill discovery directories.","trigger_phrases":["SignalWire skills system","ConciergeAgent FAQBotAgent","custom SignalWire skill","SkillBase REQUIRED_ENV_VARS","add_skill multi instance","register_skill add_skill_directory"],"runnable":true,"markdown":"\n# Agents Skills System\n\nA \"skill\" in the SignalWire Agents SDK is a reusable bundle of: prompt sections, SWAIG functions, parameter schemas, env-var/package validation, and lifecycle hooks. Skills come in two forms — **prefabs** that ship with the SDK, and **custom skills** you write by subclassing `SkillBase`.\n\n## Prefabs — ready-made agents\n\n```python\nfrom signalwire.prefabs import (\n ConciergeAgent, FAQBotAgent, InfoGathererAgent,\n ReceptionistAgent, SurveyAgent,\n)\n```\n\n### ConciergeAgent — venue/hospitality concierge\n\n```python\nagent = ConciergeAgent(\n venue_name=\"The Riverside Resort\",\n services=[\"room service\", \"spa treatments\", \"restaurant reservations\"],\n amenities={\n \"pool\": {\"hours\": \"6 AM - 10 PM\", \"location\": \"Ground Floor, East Wing\"},\n \"spa\": {\"hours\": \"9 AM - 9 PM\", \"location\": \"Level 3, East Wing\"},\n },\n hours_of_operation={\"front desk\": \"24 hours\", \"concierge\": \"7 AM - 11 PM\"},\n special_instructions=[\"Mention the daily happy hour at the pool bar (4-6 PM).\"],\n welcome_message=\"Welcome to The Riverside Resort! How may I assist you?\",\n)\n```\n\nBuilt-in tools: `check_availability(service, date, time)`, `get_directions(location)`.\n\n### FAQBotAgent — knowledge-base FAQ bot\n\n```python\nagent = FAQBotAgent(\n faqs=[\n {\"question\": \"What is the warranty period?\",\n \"answer\": \"All products come with a 2-year warranty.\",\n \"categories\": [\"warranty\"]},\n {\"question\": \"How do I return a product?\",\n \"answer\": \"Start a return within 30 days at returns.example.com.\",\n \"categories\": [\"returns\"]},\n ],\n suggest_related=True,\n persona=\"You are a helpful product specialist for TechGadgets Inc.\",\n)\n```\n\nBest for up to 50 FAQs. For larger knowledge bases, use the `native_vector_search` skill instead.\n\n### InfoGathererAgent — sequential question collection\n\n```python\nagent = InfoGathererAgent(\n questions=[\n {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n {\"key_name\": \"email\", \"question_text\": \"What is your email?\", \"confirm\": True},\n {\"key_name\": \"issue\", \"question_text\": \"Describe your issue.\"},\n ]\n)\n```\n\n`confirm: True` makes the agent read the answer back for critical fields. Answers land in `global_data` and are accessible from SWAIG handlers.\n\nDynamic mode — questions decided at request time:\n\n```python\ndef get_questions(query_params, body_params, headers):\n if query_params.get(\"type\") == \"support\":\n return [\n {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n {\"key_name\": \"issue\", \"question_text\": \"Describe your issue.\"},\n ]\n return [\n {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n {\"key_name\": \"message\", \"question_text\": \"How can I help?\"},\n ]\n\nagent = InfoGathererAgent()\nagent.set_question_callback(get_questions)\n```\n\n### ReceptionistAgent and SurveyAgent\n\n`ReceptionistAgent` — basic phone receptionist with routing. `SurveyAgent` — outbound or inbound surveys with structured response capture. Same constructor pattern as the others.\n\n## Adding skills to a custom agent — `add_skill`\n\n```python\nfrom signalwire import AgentBase\n\nagent = AgentBase(name=\"demo\")\nagent.add_skill(\"notify\")\nagent.add_skill(\"native_vector_search\", {\"index_path\": \"docs.index\"})\nagent.add_skill(\"datetime\")\n```\n\nEach `add_skill` call:\n\n1. Looks up the skill class.\n2. Runs `setup()` — validates env vars and packages, opens API clients.\n3. Calls `register_tools()` — adds SWAIG functions to the agent.\n4. Injects prompt sections from `_get_prompt_sections()` unless `skip_prompt: True`.\n\n## Multi-instance skills — `tool_name`\n\nSome skills can be added more than once (different config per instance). The `tool_name` parameter creates unique instance keys.\n\n```python\nagent.add_skill(\"notify\") # instance key: \"notify\"\nagent.add_skill(\"notify\", {\"tool_name\": \"email\"}) # instance key: \"notify_email\"\nagent.add_skill(\"notify\", {\"tool_name\": \"sms\"}) # instance key: \"notify_sms\"\n```\n\nEach instance gets its own SWAIG function namespace.\n\n## Writing a custom skill — `SkillBase`\n\n```python\nimport os\nfrom signalwire.core.skill_base import SkillBase\n\nclass WeatherSkill(SkillBase):\n SKILL_NAME = \"weather\"\n SKILL_DESCRIPTION = \"Provides weather information\"\n REQUIRED_PACKAGES = [\"requests\"]\n REQUIRED_ENV_VARS = [\"WEATHER_API_KEY\"]\n\n @classmethod\n def get_parameter_schema(cls):\n schema = super().get_parameter_schema()\n schema.update({\n \"units\": {\n \"type\": \"string\",\n \"description\": \"Temperature units\",\n \"default\": \"fahrenheit\",\n \"enum\": [\"fahrenheit\", \"celsius\"],\n },\n \"api_key\": {\n \"type\": \"string\",\n \"description\": \"Weather API key\",\n \"required\": True,\n \"hidden\": True,\n \"env_var\": \"WEATHER_API_KEY\",\n },\n })\n return schema\n\n def setup(self) -> bool:\n if not self.validate_packages():\n return False\n if not self.validate_env_vars():\n return False\n self.api_key = os.getenv(\"WEATHER_API_KEY\")\n return True\n\n def _get_prompt_sections(self):\n return [\n {\"title\": \"Weather\", \"body\": \"You can check weather using the get_weather tool.\"},\n {\"title\": \"Weather Guidelines\", \"bullets\": [\n \"Always confirm the location before checking.\",\n \"Report in the user's preferred units.\",\n ]},\n ]\n\n def register_tools(self):\n @self.agent.tool(description=\"Get current weather for a city\")\n def get_weather(args, raw_data=None):\n from signalwire import FunctionResult\n import requests\n r = requests.get(\"https://api.weatherapi.com/v1/current.json\",\n params={\"key\": self.api_key, \"q\": args.get(\"city\")})\n data = r.json()\n return FunctionResult(\n f\"Weather in {args.get('city')}: {data['current']['condition']['text']}, \"\n f\"{data['current']['temp_f']}F\"\n )\n```\n\n### Required SkillBase methods\n\n| Method | Required | Purpose |\n|---|---|---|\n| `setup()` | Yes | Validate env, packages; init clients. Return True on success. |\n| `register_tools()` | Yes | Register SWAIG functions on `self.agent`. |\n| `_get_prompt_sections()` | No | Return list of POM sections. Respects `skip_prompt`. |\n| `get_parameter_schema()` (class method) | No | Document parameters for UIs / discovery. |\n\n### Class attributes\n\n| Attribute | Notes |\n|---|---|\n| `SKILL_NAME` | String key used in `add_skill(\"name\")`. |\n| `SKILL_DESCRIPTION` | Human-readable summary. |\n| `REQUIRED_PACKAGES` | List of pip packages required at setup time. |\n| `REQUIRED_ENV_VARS` | List of env var names required. |\n\n### Validators on `SkillBase`\n\n```python\nself.validate_packages() # True/False; logs missing packages\nself.validate_env_vars() # True/False; logs missing env vars\n```\n\n## Built-in parameter fields\n\nEvery skill accepts these:\n\n| Parameter | Notes |\n|---|---|\n| `swaig_fields` | Extra SWAIG metadata merged into every tool definition this skill registers. |\n| `skip_prompt` | If True, suppress prompt-section injection. |\n| `tool_name` | Custom name for multi-instance skills. |\n\n## Skill discovery\n\nPoint an agent at a directory of skill modules to auto-register them:\n\n```python\nfrom signalwire import register_skill, add_skill_directory\n\n# Register a single skill class\nregister_skill(WeatherSkill)\n\n# Auto-discover everything in a directory (each .py file = one skill class)\nadd_skill_directory(\"/path/to/my-skills\")\n```\n\nUseful for packaging organisational tooling (CRM lookup, scheduling, knowledge bases) as reusable skill libraries.\n\n## Anti-patterns\n\n- Putting SWAIG handler imports at module top instead of inside `register_tools()` — slow startup, import errors leak before validation.\n- Skipping `REQUIRED_ENV_VARS` declaration — skill loads with missing config, fails at runtime.\n- Forgetting to return `True` from `setup()` — skill silently fails to load.\n- Mixing `add_skill` calls with manual `@agent.tool` decorators on the same domain — fights for tool name space.\n- Registering skills inside an FAQBotAgent or other prefab — prefabs lock down their tool space.\n\n## See also\n\n- [Python Agents SDK](/topic/signalwire-python-agents-sdk)\n- [SWAIG functions](/topic/swaig-functions)\n- [POM Builder](/topic/agents-pom-builder)\n- [MCP Gateway](/topic/agents-mcp-gateway)\n","html":"

Agents Skills System

\n

A \"skill\" in the SignalWire Agents SDK is a reusable bundle of: prompt sections, SWAIG functions, parameter schemas, env-var/package validation, and lifecycle hooks. Skills come in two forms — prefabs that ship with the SDK, and custom skills you write by subclassing SkillBase.

\n

Prefabs — ready-made agents

\n
from signalwire.prefabs import (\n    ConciergeAgent, FAQBotAgent, InfoGathererAgent,\n    ReceptionistAgent, SurveyAgent,\n)\n
\n

ConciergeAgent — venue/hospitality concierge

\n
agent = ConciergeAgent(\n    venue_name=\"The Riverside Resort\",\n    services=[\"room service\", \"spa treatments\", \"restaurant reservations\"],\n    amenities={\n        \"pool\": {\"hours\": \"6 AM - 10 PM\", \"location\": \"Ground Floor, East Wing\"},\n        \"spa\":  {\"hours\": \"9 AM - 9 PM\",  \"location\": \"Level 3, East Wing\"},\n    },\n    hours_of_operation={\"front desk\": \"24 hours\", \"concierge\": \"7 AM - 11 PM\"},\n    special_instructions=[\"Mention the daily happy hour at the pool bar (4-6 PM).\"],\n    welcome_message=\"Welcome to The Riverside Resort! How may I assist you?\",\n)\n
\n

Built-in tools: check_availability(service, date, time), get_directions(location).

\n

FAQBotAgent — knowledge-base FAQ bot

\n
agent = FAQBotAgent(\n    faqs=[\n        {\"question\": \"What is the warranty period?\",\n         \"answer\": \"All products come with a 2-year warranty.\",\n         \"categories\": [\"warranty\"]},\n        {\"question\": \"How do I return a product?\",\n         \"answer\": \"Start a return within 30 days at returns.example.com.\",\n         \"categories\": [\"returns\"]},\n    ],\n    suggest_related=True,\n    persona=\"You are a helpful product specialist for TechGadgets Inc.\",\n)\n
\n

Best for up to 50 FAQs. For larger knowledge bases, use the native_vector_search skill instead.

\n

InfoGathererAgent — sequential question collection

\n
agent = InfoGathererAgent(\n    questions=[\n        {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n        {\"key_name\": \"email\", \"question_text\": \"What is your email?\", \"confirm\": True},\n        {\"key_name\": \"issue\", \"question_text\": \"Describe your issue.\"},\n    ]\n)\n
\n

confirm: True makes the agent read the answer back for critical fields. Answers land in global_data and are accessible from SWAIG handlers.

\n

Dynamic mode — questions decided at request time:

\n
def get_questions(query_params, body_params, headers):\n    if query_params.get(\"type\") == \"support\":\n        return [\n            {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n            {\"key_name\": \"issue\", \"question_text\": \"Describe your issue.\"},\n        ]\n    return [\n        {\"key_name\": \"name\", \"question_text\": \"What is your name?\"},\n        {\"key_name\": \"message\", \"question_text\": \"How can I help?\"},\n    ]\n\nagent = InfoGathererAgent()\nagent.set_question_callback(get_questions)\n
\n

ReceptionistAgent and SurveyAgent

\n

ReceptionistAgent — basic phone receptionist with routing. SurveyAgent — outbound or inbound surveys with structured response capture. Same constructor pattern as the others.

\n

Adding skills to a custom agent — add_skill

\n
from signalwire import AgentBase\n\nagent = AgentBase(name=\"demo\")\nagent.add_skill(\"notify\")\nagent.add_skill(\"native_vector_search\", {\"index_path\": \"docs.index\"})\nagent.add_skill(\"datetime\")\n
\n

Each add_skill call:

\n
    \n
  1. Looks up the skill class.
    2. \n
  2. Runs setup() — validates env vars and packages, opens API clients.
    3. \n
  3. Calls register_tools() — adds SWAIG functions to the agent.
    4. \n
  4. Injects prompt sections from _get_prompt_sections() unless skip_prompt: True.
    5. \n
\n

Multi-instance skills — tool_name

\n

Some skills can be added more than once (different config per instance). The tool_name parameter creates unique instance keys.

\n
agent.add_skill(\"notify\")                            # instance key: \"notify\"\nagent.add_skill(\"notify\", {\"tool_name\": \"email\"})    # instance key: \"notify_email\"\nagent.add_skill(\"notify\", {\"tool_name\": \"sms\"})      # instance key: \"notify_sms\"\n
\n

Each instance gets its own SWAIG function namespace.

\n

Writing a custom skill — SkillBase

\n
import os\nfrom signalwire.core.skill_base import SkillBase\n\nclass WeatherSkill(SkillBase):\n    SKILL_NAME = \"weather\"\n    SKILL_DESCRIPTION = \"Provides weather information\"\n    REQUIRED_PACKAGES = [\"requests\"]\n    REQUIRED_ENV_VARS = [\"WEATHER_API_KEY\"]\n\n    @classmethod\n    def get_parameter_schema(cls):\n        schema = super().get_parameter_schema()\n        schema.update({\n            \"units\": {\n                \"type\": \"string\",\n                \"description\": \"Temperature units\",\n                \"default\": \"fahrenheit\",\n                \"enum\": [\"fahrenheit\", \"celsius\"],\n            },\n            \"api_key\": {\n                \"type\": \"string\",\n                \"description\": \"Weather API key\",\n                \"required\": True,\n                \"hidden\": True,\n                \"env_var\": \"WEATHER_API_KEY\",\n            },\n        })\n        return schema\n\n    def setup(self) -> bool:\n        if not self.validate_packages():\n            return False\n        if not self.validate_env_vars():\n            return False\n        self.api_key = os.getenv(\"WEATHER_API_KEY\")\n        return True\n\n    def _get_prompt_sections(self):\n        return [\n            {\"title\": \"Weather\", \"body\": \"You can check weather using the get_weather tool.\"},\n            {\"title\": \"Weather Guidelines\", \"bullets\": [\n                \"Always confirm the location before checking.\",\n                \"Report in the user's preferred units.\",\n            ]},\n        ]\n\n    def register_tools(self):\n        @self.agent.tool(description=\"Get current weather for a city\")\n        def get_weather(args, raw_data=None):\n            from signalwire import FunctionResult\n            import requests\n            r = requests.get(\"https://api.weatherapi.com/v1/current.json\",\n                             params={\"key\": self.api_key, \"q\": args.get(\"city\")})\n            data = r.json()\n            return FunctionResult(\n                f\"Weather in {args.get('city')}: {data['current']['condition']['text']}, \"\n                f\"{data['current']['temp_f']}F\"\n            )\n
\n

Required SkillBase methods

\n

| Method | Required | Purpose |\n|---|---|---|\n| setup() | Yes | Validate env, packages; init clients. Return True on success. |\n| register_tools() | Yes | Register SWAIG functions on self.agent. |\n| _get_prompt_sections() | No | Return list of POM sections. Respects skip_prompt. |\n| get_parameter_schema() (class method) | No | Document parameters for UIs / discovery. |

\n

Class attributes

\n

| Attribute | Notes |\n|---|---|\n| SKILL_NAME | String key used in add_skill(\"name\"). |\n| SKILL_DESCRIPTION | Human-readable summary. |\n| REQUIRED_PACKAGES | List of pip packages required at setup time. |\n| REQUIRED_ENV_VARS | List of env var names required. |

\n

Validators on SkillBase

\n
self.validate_packages()  # True/False; logs missing packages\nself.validate_env_vars()  # True/False; logs missing env vars\n
\n

Built-in parameter fields

\n

Every skill accepts these:

\n

| Parameter | Notes |\n|---|---|\n| swaig_fields | Extra SWAIG metadata merged into every tool definition this skill registers. |\n| skip_prompt | If True, suppress prompt-section injection. |\n| tool_name | Custom name for multi-instance skills. |

\n

Skill discovery

\n

Point an agent at a directory of skill modules to auto-register them:

\n
from signalwire import register_skill, add_skill_directory\n\n# Register a single skill class\nregister_skill(WeatherSkill)\n\n# Auto-discover everything in a directory (each .py file = one skill class)\nadd_skill_directory(\"/path/to/my-skills\")\n
\n

Useful for packaging organisational tooling (CRM lookup, scheduling, knowledge bases) as reusable skill libraries.

\n

Anti-patterns

\n\n

See also

\n\n"}