Why Skills?

From repeated tool payloads to reusable capability references

Before: Raw Tool Calling

Without skills, every request includes full tool definitions — 50+ lines of JSON schema repeated on every call, drifting between copies.

raw-tools.json

{
  "model": "openai/gpt-4.1",
  "messages": [{ "role": "user", "content": "Find contact and create ticket." }],
  "tools": [
    { "type": "function", "function": {
        "name": "lookup_contact",
        "description": "Find a CRM contact by email or name",
        "parameters": { "type": "object",
          "properties": { "query": { "type": "string" },
            "source": { "type": "string", "enum": ["crm", "directory", "all"] } },
          "required": ["query"] }
    }},
    { "type": "function", "function": {
        "name": "create_ticket",
        "description": "Open a support ticket",
        "parameters": { "type": "object",
          "properties": { "subject": { "type": "string" },
            "priority": { "type": "string", "enum": ["low", "medium", "high"] } },
          "required": ["subject", "priority"] }
    }}
  ]
}

After: Skills

Store definitions once as a schema bundle, then reference by ID. Four lines replace fifty.

skills-request.json

{
  "model": "openai/gpt-4.1",
  "messages": [{ "role": "user", "content": "Find contact and create ticket." }],
  "skills": [{ "id": "crm-tools" }]
}

Workflow simplification

No client-side retry loops — managed execution handles tool cycling server-side.
No per-provider schema workarounds — schema normalization adapts definitions automatically.
Consistent annotations — built-in skills return standardized formats across models.

Integration cost reduction

Without skills

Per-request overhead:
  1. Load tool definitions from config
  2. Serialize 2-20 KB of JSON schema per call
  3. Parse tool_calls, execute locally, send results back
  4. Handle provider-specific schema errors
  5. Repeat for each model switch