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 Endpoint Method Description /api/v1/skillsGET List all skills /api/v1/skills/{name}GET Get skill details /api/v1/skills/{name}/versionsGET Get skill version history
List Skills Returns all available skills, optionally filtered by category.
Query Parameters Parameter Type Required Description categorystring No Filter 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 Parameter Type Required Description namestring Yes Skill 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\n You 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 Parameter Type Required Description namestring Yes Skill 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 Field Type Required Description namestring Yes Skill identifier versionstring Yes Semantic version categorystring No Grouping category descriptionstring No Human-readable description requires_rolestring No Role preset to use requires_toolsarray No Required tools dangerousboolean No Requires elevated permissions enabledboolean No Whether skill is active budget_maxinteger No Max 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
