Skip to main content
Agents

Skills

Skills are instructional knowledge packs that give your agent domain expertise. Instead of stuffing everything into the system prompt, skills are retrieved on demand via the get_skill tool.

How Skills Work

1

Enable skills on your agent

In the agent editor, go to the Skills tab and toggle on the skills you want available.

2

Agent discovers available skills

The orchestrator injects a skill discovery hint into the system prompt listing each skill's ID and description.

3

Agent calls get_skill when needed

The LLM decides when to retrieve skill content. The full instructions, examples, and guidelines are returned as a tool response.

Skills vs Tools

Skills and tools serve different purposes. Understanding the distinction is key to designing effective agents.

Skills

  • Instructional — text-based knowledge
  • Retrieved via get_skill tool call
  • Guidelines, best practices, domain expertise
  • Stored in agent.skills[]
  • Loaded on demand, not in every prompt

Tools

  • Executable — run code or call APIs
  • Called directly as OpenAI function calls
  • Calculator, Web Search, Code Executor
  • Stored in agent.builtinTools[]
  • Execute server-side, return structured data

Creating Custom Skills

You can create your own skills to give agents specialized knowledge. Each skill is a bundle of instructions, examples, and guidelines.

Dashboard → Agents → Skills → New Skill

Or click New Skill directly from the agent editor's Skills tab.

Skill Structure

json
{
  "id": "code-review-guidelines",
  "name": "Code Review Guidelines",
  "description": "Best practices for reviewing pull requests",
  "instructions": "When reviewing code, follow these principles:\n1. Check for correctness first\n2. Look for security vulnerabilities\n3. Evaluate readability and maintainability\n4. Verify test coverage...",
  "examples": [
    "Example: Spotting a SQL injection vulnerability...",
    "Example: Identifying a race condition..."
  ],
  "guidelines": [
    "Always explain WHY something is an issue, not just WHAT",
    "Suggest concrete fixes, not vague improvements"
  ]
}

The get_skill Tool

When an agent has skills enabled, the get_skill function is automatically added to its tool list. The agent calls it when it needs domain knowledge.

json
// The agent makes this tool call automatically:
{
  "type": "function",
  "function": {
    "name": "get_skill",
    "arguments": { "skill_id": "code-review-guidelines" }
  }
}

// The orchestrator returns the skill content:
{
  "id": "code-review-guidelines",
  "name": "Code Review Guidelines",
  "instructions": "When reviewing code, follow these principles...",
  "examples": [...],
  "guidelines": [...]
}

Per-agent allowlist

Each agent can only access skills that are explicitly enabled in its configuration. The get_skill call will fail withSKILL_NOT_ALLOWED if the agent tries to retrieve a skill outside its allowlist. This prevents prompt injection from accessing unauthorized knowledge.

Next: Built-in Tools

Calculator, Web Search, Code Executor, and more.