Skills

Skills are pluggable capabilities that add tools to your agent. Import a skill class, instantiate it with optional configuration, and pass the instance to addSkill(). Each skill registers one or more SWAIG functions automatically and injects prompt sections, hints, and global data.

import { AgentBase, DateTimeSkill, WebSearchSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'my-agent', route: '/' });
agent.setPromptText('You are a helpful assistant.');
// No-config skill
await agent.addSkill(new DateTimeSkill());
// Skill with parameters
await agent.addSkill(new WebSearchSkill({
  num_results: 5,
  safe_search: 'high',
}));
agent.run();

Skills Summary

Skill	Class	Tools	Env Vars Required	Multi-Instance
`datetime`	`DateTimeSkill`	2	No	No
`math`	`MathSkill`	1	No	No
`joke`	`JokeSkill`	1	No	No
`weather_api`	`WeatherApiSkill`	1	Yes	No
`web_search`	`WebSearchSkill`	1	Yes	Yes
`wikipedia_search`	`WikipediaSearchSkill`	1	No	No
`google_maps`	`GoogleMapsSkill`	2	Yes	No
`play_background_file`	`PlayBackgroundFileSkill`	1	No	Yes
`swml_transfer`	`SwmlTransferSkill`	1-2	No	Yes
`datasphere`	`DataSphereSkill`	1	Yes	Yes
`datasphere_serverless`	`DataSphereServerlessSkill`	1	Yes	Yes
`native_vector_search`	`NativeVectorSearchSkill`	1	No	Yes
`info_gatherer`	`InfoGathererSkill`	2	No	Yes
`api_ninjas_trivia`	`ApiNinjasTriviaSkill`	1	Yes	Yes
`spider`	`SpiderSkill`	3	No	Yes
`ask_claude`	`AskClaudeSkill`	1	Yes	No
`claude_skills`	`ClaudeSkillsSkill`	Dynamic	No	Yes
`custom_skills`	`CustomSkillsSkill`	Dynamic	No	No
`mcp_gateway`	`McpGatewaySkill`	1	No	No

Configuration

All skills accept configuration via a config object passed to the skill constructor. Skills with an env_var fallback on a parameter read from process.env when the parameter is not provided directly.

import { WebSearchSkill } from '@signalwire/sdk';
// Direct configuration
const skill = new WebSearchSkill({ num_results: 5, safe_search: 'high' });
// Environment variable fallback (api_key falls back to GOOGLE_SEARCH_API_KEY,
// search_engine_id falls back to GOOGLE_SEARCH_CX)
process.env.GOOGLE_SEARCH_API_KEY = 'YOUR_KEY';
process.env.GOOGLE_SEARCH_CX = 'YOUR_ENGINE_ID';
const skillWithEnv = new WebSearchSkill({ num_results: 5 });

SWAIG Field Overrides

Override SWAIG function metadata for any skill by including a swaig_fields key:

import { AgentBase, DateTimeSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new DateTimeSkill({
  swaig_fields: {
    fillers: { 'en-US': ['Let me check the time...', 'One moment...'] },
    secure: false,
  },
}));
agent.run();

Multi-Instance Skills

Skills that support multiple instances (SUPPORTS_MULTIPLE_INSTANCES = true) can be added to the same agent more than once with different tool_name values:

import { AgentBase, DataSphereSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new DataSphereSkill({
  tool_name: 'search_products',
  document_id: 'doc_products',
  count: 3,
}));
await agent.addSkill(new DataSphereSkill({
  tool_name: 'search_policies',
  document_id: 'doc_policies',
  count: 5,
}));
agent.run();

Base Parameters

Every skill inherits these parameters from SkillBase:

swaig_fields

object

Additional SWAIG fields to merge into each tool definition provided by this skill (e.g., fillers, secure).

skip_prompt

booleanDefaults to false

When true, suppress all prompt sections from this skill.

Extending SkillBase

Create custom skills by extending SkillBase and registering them with the SkillRegistry.

Defining a Custom Skill

import { SkillBase, FunctionResult } from '@signalwire/sdk';
import type {
  SkillToolDefinition,
  SkillPromptSection,
  ParameterSchemaEntry,
} from '@signalwire/sdk';
export class StockPriceSkill extends SkillBase {
  // Identity is declared with static class constants.
  static override SKILL_NAME = 'stock_price';
  static override SKILL_DESCRIPTION = 'Look up current stock prices.';
  static override SKILL_VERSION = '1.0.0';
  static override REQUIRED_ENV_VARS = ['STOCK_API_KEY'] as const;
  static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
    return {
      ...super.getParameterSchema(),
      api_key: {
        type: 'string',
        description: 'Stock API key.',
        hidden: true,
        env_var: 'STOCK_API_KEY',
        required: true,
      },
    };
  }
  override getTools(): SkillToolDefinition[] {
    return [
      {
        name: 'get_stock_price',
        description: 'Get the current price of a stock by ticker symbol.',
        parameters: {
          symbol: {
            type: 'string',
            description: 'Stock ticker symbol (e.g., "AAPL", "GOOG").',
          },
        },
        required: ['symbol'],
        handler: async (args: Record<string, unknown>) => {
          const symbol = args.symbol as string;
          // Your implementation here
          return new FunctionResult(
            'The current price of ' + symbol + ' is $150.00.',
          );
        },
      },
    ];
  }
  protected override _getPromptSections(): SkillPromptSection[] {
    return [
      {
        title: 'Stock Prices',
        body: 'You can look up current stock prices.',
        bullets: [
          'Use the get_stock_price tool when the user asks about a stock price.',
          'Provide the stock ticker symbol (e.g., AAPL for Apple).',
        ],
      },
    ];
  }
}

Registering with SkillRegistry

import { SkillRegistry } from '@signalwire/sdk';
import { StockPriceSkill } from './stock-price-skill.js';
const registry = SkillRegistry.getInstance();
registry.register(StockPriceSkill); // pass the class; name comes from SKILL_NAME

Using a Custom Skill

import { AgentBase } from '@signalwire/sdk';
import { StockPriceSkill } from './stock-price-skill.js';
const agent = new AgentBase({ name: 'finance-bot', route: '/' });
agent.setPromptText('You are a financial assistant.');
await agent.addSkill(new StockPriceSkill());
agent.run();