Skip to main content

​
Overview

The Skills API allows you to list available skills, retrieve skill details, and check version history. Skills are markdown-based workflow definitions that drive single-agent execution with predefined system prompts and configurations.

​
Endpoints

EndpointMethodDescription
/api/v1/skillsGETList all skills
/api/v1/skills/{name}GETGet skill details
/api/v1/skills/{name}/versionsGETGet skill version history

​
List Skills

GET /api/v1/skills
Returns all available skills, optionally filtered by category.

​
Query Parameters

ParameterTypeRequiredDescription
categorystringNoFilter by category (e.g., research, development, analysis)

​
Response

{
  "skills": [
    {
      "name": "deep-research",
      "version": "1.0.0",
      "category": "research",
      "description": "Comprehensive research with citations and verification",
      "requires_tools": ["web_search", "web_fetch"],
      "dangerous": false,
      "enabled": true
    },
    {
      "name": "code-review",
      "version": "1.0.0",
      "category": "development",
      "description": "Review code for bugs and improvements",
      "requires_tools": ["file_read"],
      "dangerous": false,
      "enabled": true
    }
  ],
  "count": 2,
  "categories": ["research", "development", "analysis"]
}

​
Example

# List all skills
curl http://localhost:8080/api/v1/skills \
  -H "X-API-Key: sk_test_123456"

# Filter by category
curl "http://localhost:8080/api/v1/skills?category=research" \
  -H "X-API-Key: sk_test_123456"

​
Get Skill

GET /api/v1/skills/{name}
Returns detailed information about a specific skill, including its content and metadata.

​
Path Parameters

ParameterTypeRequiredDescription
namestringYesSkill name (e.g., deep-research)

​
Response

{
  "skill": {
    "name": "deep-research",
    "version": "1.0.0",
    "category": "research",
    "description": "Comprehensive research with citations and verification",
    "content": "# Deep Research Skill\n\nYou are a research agent...",
    "requires_role": "research",
    "requires_tools": ["web_search", "web_fetch"],
    "dangerous": false,
    "enabled": true,
    "budget_max": 50000
  },
  "metadata": {
    "source_path": "config/skills/research/deep-research.md",
    "content_hash": "sha256:abc123...",
    "loaded_at": "2025-01-20T10:00:00Z"
  }
}

​
Example

curl http://localhost:8080/api/v1/skills/deep-research \
  -H "X-API-Key: sk_test_123456"

​
Error Responses

404 Not Found: 
{
  "error": "Skill not found"
}

​
Get Skill Versions

GET /api/v1/skills/{name}/versions
Returns all available versions of a skill.

​
Path Parameters

ParameterTypeRequiredDescription
namestringYesSkill name (e.g., deep-research)

​
Response

{
  "name": "deep-research",
  "versions": [
    {
      "name": "deep-research",
      "version": "1.0.0",
      "category": "research",
      "description": "Comprehensive research with citations",
      "requires_tools": ["web_search", "web_fetch"],
      "dangerous": false,
      "enabled": true
    },
    {
      "name": "deep-research",
      "version": "0.9.0",
      "category": "research",
      "description": "Beta research skill",
      "requires_tools": ["web_search"],
      "dangerous": false,
      "enabled": false
    }
  ],
  "count": 2
}

​
Example

curl http://localhost:8080/api/v1/skills/deep-research/versions \
  -H "X-API-Key: sk_test_123456"

​
Using Skills in Tasks

To use a skill when submitting a task, include the skill parameter: 
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Research the latest developments in quantum computing",
    "skill": "deep-research"
  }'

​
Version Selection

Specify a version using name@version syntax: 
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Review this pull request",
    "skill": "code-review@1.0.0"
  }'
Skills expand into system prompt overrides and optional role assignments. They provide a way to define reusable workflows without modifying code.

​
Skill Structure

Skills are defined as markdown files with YAML frontmatter: 
---
name: my-skill
version: "1.0.0"
category: development
description: "Description of what this skill does"
requires_role: developer
requires_tools:
  - file_read
  - file_write
dangerous: false
enabled: true
budget_max: 50000
---

# Skill Instructions

You are a specialized agent that...

## Guidelines

1. First, analyze the request
2. Then, execute the appropriate actions
3. Finally, report the results

​
Frontmatter Fields

FieldTypeRequiredDescription
namestringYesSkill identifier
versionstringYesSemantic version
categorystringNoGrouping category
descriptionstringNoHuman-readable description
requires_rolestringNoRole preset to use
requires_toolsarrayNoRequired tools
dangerousbooleanNoRequires elevated permissions
enabledbooleanNoWhether skill is active
budget_maxintegerNoMax token budget

​
Dangerous Skills

Skills marked as dangerous: true require special authorization:
  • Admin or Owner role, OR
  • Explicit skills:dangerous scope in API key
# Dangerous skill invocation (requires authorization)
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Execute system maintenance",
    "skill": "system-admin"
  }'
Dangerous skills can execute privileged operations. Only grant skills:dangerous scope to trusted API keys.

Submit Task

Use skills when submitting tasks

Custom Tools

Add tools for skills to use