Skills

• Discovery (call start): only each skill’s name + description are loaded — about 30-50 tokens each — via a built-in use_skill tool. The full instructions are not in the prompt yet.
• Activation (the model calls use_skill): the chosen skill’s instructions are layered into the system prompt and its tools are unlocked — inline, in the same agent loop. There is no sub-agent spawn and no extra round-trip, so a skill adds no latency the way a delegated agent would.

​

When to use it

• Your agent handles several distinct procedures (refunds, scheduling, troubleshooting) and you don’t want every procedure’s full instructions in the prompt for every call.
• A procedure needs its own tools that should only be reachable once the agent has committed to that procedure.
• You want the model to decide which playbook fits, rather than cramming all of them into one long system prompt.

​

Quickstart

import { tool } from 'getpatter';
import type { Skill } from 'getpatter';

const refunds: Skill = {
  name: 'refunds',
  description: 'Process a customer refund end to end.',
  instructions:
    'Verify the order id. Confirm the amount with the caller. Then call ' +
    'process_refund. Never refund more than $500 without escalating with ' +
    'transfer_call.',
  tools: [
    tool({
      name: 'process_refund',
      description: 'Issue a refund for an order.',
      handler: async () => JSON.stringify({ status: 'refunded' }),
    }),
  ],
};

const agent = phone.agent({
  systemPrompt: 'You are a friendly support line for Acme.',
  skills: [refunds],
});

​

The Skill type

interface Skill {
  readonly name: string;            // enum value the model passes to use_skill
  readonly description: string;     // one-liner loaded eagerly (when to use it)
  readonly instructions: string;    // full playbook, loaded on activation
  readonly tools?: readonly Tool[]; // tools exposed only while active
}

​

Naming rules

• the reserved built-ins transfer_call, end_call, handoff_to, use_skill;
• your top-level tools;
• another skill’s tools.

​

Behaviour notes

• Idempotent: calling use_skill again for an already-active skill is a no-op (it returns already_active, no double-layering).
• Stackable: activating a second skill layers it on top of the first; both stay active.
• Realtime and Pipeline: skills work the same in both modes — Realtime pushes the new instructions/tools via a session update, Pipeline swaps them into the next turn.
• With handoffs: a handoff_to replaces the prompt, so it resets the active skills to the target agent’s skills.

​

Skills vs. the other primitives