Skills

Skills are reusable blocks of instructions that give your agent deeper context on specific topics — API details, behavioral rules, step-by-step procedures, or anything else it needs to know.

What skills are

Think of skills as extra pages in an instruction manual. The system prompt tells the agent who it is and how to behave in general. Skills give it detailed knowledge on specific topics — like how to call a particular API, how to handle refunds, or what tone to use when writing marketing copy.

You can define the same skill content for any agent that needs it. When you update the file content in your sandbox config and redeploy, new sandboxes pick up the change automatically.

How skills work with the system prompt

The system prompt is your agent's core identity — it's sent with every message. Skills provide additional context that the agent can reference when it needs to.

The key pattern: in your system prompt, you tell the agent when to use each skill. The skill itself contains the detailed instructions for that situation.

System prompt:
  "You are a support agent for Acme Inc.
   When the user asks about returns, follow the Returns Policy skill.
   When the user asks about billing, follow the Billing FAQ skill."

Skills attached:
  ├─ Returns Policy    (detailed refund steps, eligibility rules, edge cases)
  └─ Billing FAQ       (plan tiers, upgrade flow, invoice questions)

This way your system prompt stays short and focused, while the agent still has access to deep context whenever a specific topic comes up.

What to put in a skill

Skills can contain any kind of instructions or reference material. Common use cases:

  • API documentation — endpoints, parameters, authentication, example requests and responses. Tell the agent how to call your APIs or third-party services.
  • Procedures — step-by-step instructions for handling specific situations (e.g. processing a refund, escalating a ticket, onboarding a new user).
  • Behavioral rules — tone, formatting, what to say and what to avoid in specific contexts.
  • Domain knowledge — product specs, pricing tables, feature comparisons, FAQs — anything the agent might need to reference.
  • Tool calling instructions — how to use specific tools, what parameters to pass, when to use which tool, and what to do with the results.

Skills vs system prompts

Both influence how the agent behaves, but they serve different roles:

System prompt

  • One per agent
  • Sent with every message
  • Defines identity, tone, and general rules
  • Not shareable between agents

Skill

  • Many per agent
  • Referenced on demand
  • Provides detailed context on specific topics
  • Shareable across multiple agents
Rule of thumb: If you'd put it in the agent's “about me”, it belongs in the system prompt. If it's reference material the agent needs for specific tasks, make it a skill.

See System Prompts for more on how to write effective system prompts.

Example

A skill that teaches the agent how to handle order lookups via an API:

# Order Lookup

## When to use
The user asks about their order status, shipment tracking, or delivery date.

## API endpoint
GET https://api.acme.com/v1/orders/{order_id}
Authorization: Bearer {API_KEY}

## Response fields
- status: pending | shipped | delivered | cancelled
- tracking_url: shipment tracking link (null if not shipped)
- estimated_delivery: ISO date string

## How to respond
1. Ask the user for their order number if they haven't provided it
2. Call the API with the order ID
3. If status is "shipped", include the tracking link
4. If status is "pending", tell them the estimated ship date
5. Never share raw API responses — summarize in plain language

Create a skill

Skills are filesystem-backed. To create one, write a SKILL.md file into /home/user/.claude/skills/SKILL_NAME/SKILL.md through Sandbox({ files }).

That is the only setup required. Skills in .claude/skills are discovered automatically, and the runtime already allows the Skill tool by default.
src/agent.ts
import { agent, Sandbox } from "@21st-sdk/agent"

const ORDER_LOOKUP_SKILL = `---
name: Order Lookup
description: Handle order status, tracking, and delivery questions
---

# When to use
Use this skill when the user asks about order status, shipment tracking, delivery dates, or delayed packages.

# Required input
- order number

# Steps
1. If the user did not provide an order number, ask for it first.
2. Call GET https://api.acme.com/v1/orders/{orderId}.
3. Summarize the result in plain language.
4. If the order is shipped, include the tracking URL.
5. If the order is cancelled, explain the refund timeline.

# Response fields
- status: pending | shipped | delivered | cancelled
- tracking_url: string | null
- estimated_delivery: ISO date string
`

export default agent({
  runtime: "claude-code",
  model: "claude-sonnet-4-6",
  systemPrompt: `You are a support agent for Acme Inc.
Use the Order Lookup skill when the user asks about order status, tracking, or delivery dates.
Ask for the order number before using the skill if it is missing.`,
  sandbox: Sandbox({
    files: {
      "/home/user/.claude/skills/order-lookup/SKILL.md": ORDER_LOOKUP_SKILL,
    },
  }),
})

Every new sandbox for that deployed agent will start with this skill file present, so Claude Code can discover it automatically.

Skills — 21st Agents Docs