Skills

Skills solve a prompt-budget problem. A capable agent might need ten detailed procedures — card activation, refund flow, escalation script — but stuffing all ten into the instructions bloats every turn and dilutes the persona. A skill keeps only its name and one-line description resident in the prompt (the menu); the full body loads just-in-time when the conversation actually goes there.

Skills follow the Agent Skills standard: a SKILL.md document with frontmatter (name, description) and a markdown body. They never appear on the wire as a separate concept — the SDK compiles them into an instructions suffix (the menu) plus one load_skill client tool. When the model recognizes it needs a skill, it calls load_skill, receives the body as the tool result, and the procedure stays in context for the rest of the call.

Attaching skills

Python — point at a directory of SKILL.md files, or pass Skill objects inline:

from pathlib import Path
from cosmo_ai import CosmoRealtime

client = CosmoRealtime(api_key=os.environ["COSMO_API_KEY"])
agent = client.agent(
    instructions="You are Alex at Acme.",
    skills=Path("./skills"),          # each subdirectory holds a SKILL.md
)

from cosmo_ai.skills import Skill

card_activation = Skill(
    name="card-activation",
    description="Walk a customer through activating a new card.",
    body=CARD_ACTIVATION_PLAYBOOK,
)
agent = client.agent(instructions="…", skills=[card_activation])

TypeScript — the browser has no filesystem, so load the text yourself and pass Skill objects or parse documents with parseSkillMd:

import { parseSkillMd } from 'cosmo-ai';

const skillText = await fetch('/skills/card-activation.md').then(r => r.text());
const agent = client.agent({
  instructions: '…',
  skills: [parseSkillMd(skillText, { defaultName: 'card-activation' })],
});

Swift — same shape: Skill values on the session config (see the SkillsExample target in the Swift package for a complete program).

Malformed documents (missing frontmatter, missing required fields) and duplicate skill names fail when the agent is built — SkillParseError — not mid-call.

Writing a good skill

---
name: card-activation
description: Walk a customer through activating a new card.
---

## Steps
1. Confirm the last four digits of the card.
2. …

• The description is the routing signal — it's all the model sees before deciding to load. Write it like a when-to-use line, not a title.
• The body is a procedure the model follows once loaded. Keep it imperative and self-contained.
• Once loaded, a skill stays in context for the rest of the session; there is no unload.

Skills vs. instructions vs. tools

Skill loads are ordinary tool calls, so they show up in the tool-call / tool-result event stream and can be observed (or even denied) with hooks matching load_skill.