Skills

Instead of loading all instructions into the system prompt, skills let the agent discover summaries and load full instructions only when needed. Each skill is a directory containing a SKILL.md file.

What Is a Skill?

A skill is a directory containing a SKILL.md file. The file holds instructions (markdown) and optional frontmatter for name and description.

.agents/skills/
├── code-review/
│   └── SKILL.md
├── deploy/
│   └── SKILL.md
└── debug/
    └── SKILL.md

The agent discovers skills from the filesystem in the sandbox. Skills can be cloned or installed during sandbox setup.

Configuring skills

Set skills on the agent or override per session:

import { agent } from "experimental-agent";

const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  skills: [{ type: "sandbox", path: ".agents/skills" }],
});

Or multiple sources:

const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  skills: [
    { type: "sandbox", path: ".agents/skills" },
    { type: "sandbox", path: "custom-skills" },
    {
      type: "git",
      repo: "https://github.com/acme/agent-skills.git",
      ref: "main",
      path: "skills",
      name: "release-playbook",
    },
  ],
});

Override per session:

await myAgent.session(chatId).update({
  skills: [{ type: "sandbox", path: "tenant-specific-skills" }],
});

How the Agent Uses Skills

1. Summaries in system prompt — The agent sees skill names and descriptions (from frontmatter) in its system prompt.
2. Skill tool — When the agent decides it needs detailed instructions, it calls the built-in Skill tool with a skill name.
3. Full content loaded — The Skill tool returns the full SKILL.md content for that skill.

The agent only loads full instructions when it decides they're relevant. This keeps the initial context small and reduces token usage.

The Skill Tool

The built-in Skill tool loads a skill's full SKILL.md content by name. It reads from the sandbox filesystem after configured sources are resolved/materialized. See Tools for the full built-in tool list.

Sandbox and Setup

Skills are loaded from the sandbox filesystem. If your skills live in a repo or package, clone or install them during sandbox setup:

sandbox: {
  type: "vercel",
  setup: {
    key: "skills-v1",
    run: async (sandbox) => {
      await sandbox.exec({ command: "git", args: ["clone", "https://github.com/org/skills-repo.git", ".agents/skills"] });
    },
  },
},

Next Steps

• Tools — Built-in tools including Skill
• Sandbox — Setup and filesystem access
• Sessions — Per-session options including skills