Skip to main content

​
Overview

Skills are reusable capabilities that can be loaded by agents to perform specific tasks. Skills are defined in Markdown files with metadata and can be discovered from local directories or remote repositories.

​
List Skills

curl http://localhost:3000/api/skills

​
Endpoint

​
GET /api/skills
GET
List all available skills or get a specific skill by name

​
Query Parameters

​
name
string
If provided, returns a single skill with full content

​
Response

​
skills
array
Array of skill summary objects (when listing)
When querying by name, returns a single skill object with full content.

​
Skill Summary Object

​
name
string
required
Unique skill identifier
​
description
string
required
Detailed description of what the skill does
​
shortDescription
string
Brief one-line description
​
license
string
License information (e.g., “MIT”)
​
compatibility
array
Array of compatible agent types or systems

​
Full Skill Object

When querying by name, includes all summary fields plus:
​
content
string
required
Full skill content (Markdown)
​
metadata
object
Additional metadata from the skill definition

​
Response Example (List)

{
  "skills": [
    {
      "name": "git-workflow",
      "description": "Git branching and commit workflow for collaborative development",
      "shortDescription": "Git workflow management",
      "license": "MIT",
      "compatibility": ["DEVELOPER", "ROUTA"]
    },
    {
      "name": "code-review",
      "description": "Automated code review and quality checks",
      "shortDescription": "Code review automation",
      "license": "Apache-2.0",
      "compatibility": ["GATE", "DEVELOPER"]
    }
  ]
}

​
Response Example (Single Skill)

{
  "name": "git-workflow",
  "description": "Git branching and commit workflow for collaborative development",
  "content": "# Git Workflow\n\n## Overview\n\nThis skill provides...",
  "license": "MIT",
  "compatibility": ["DEVELOPER", "ROUTA"],
  "metadata": {
    "version": "1.0.0",
    "author": "Routa Team"
  }
}

​
Get Skill by Name

curl "http://localhost:3000/api/skills?name=git-workflow"

​
Query Parameters

​
name
string
required
Skill name to retrieve
​
repoPath
string
Optional repository path to search for skills (in addition to global skills)

​
Status Codes

Status CodeDescription
200Success
404Skill not found

​
Error Response

{
  "error": "Skill not found: git-workflow"
}

​
Reload Skills

curl -X POST http://localhost:3000/api/skills

​
Endpoint

​
POST /api/skills
POST
Reload skills from disk and database

​
Response

​
reloaded
boolean
required
Always true when successful
​
count
integer
required
Number of skills loaded

​
Response Example

{
  "reloaded": true,
  "count": 15
}

​
Discover Skills

curl "http://localhost:3000/api/skills/clone?repoPath=/path/to/repo"

​
Endpoint

​
GET /api/skills/clone
GET
Discover skills from a repository path

​
Query Parameters

​
repoPath
string
Path to repository to scan for skills

​
Response

Returns discovered skill definitions from the specified path.

​
Clone Skill Repository

curl -X POST http://localhost:3000/api/skills/clone \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/example/skills-repo.git",
    "skillsDir": "skills"
  }'

​
Endpoint

​
POST /api/skills/clone
POST
Clone a skill repository from a Git URL

​
Request Body

​
url
string
Git repository URL to clone
​
skillsDir
string
Directory within the repository containing skills

​
Response

Returns success status and cloned repository information.

​
Upload Skill Zip

curl -X POST http://localhost:3000/api/skills/upload \
  -F "[email protected]"

​
Endpoint

​
POST /api/skills/upload
POST
Upload skill(s) as a zip file

​
Request Body

Multipart form data with a single file field:
​
file
binary
required
Zip file containing skill definitions

​
Response

Returns success status and information about uploaded skills.

​
Skill Directory Structure

Skills are discovered from the following locations:
  1. Global Skills: ~/.config/opencode/skills/
  2. Project Skills: <project-root>/skills/
  3. Database Skills: Postgres database (for serverless deployments)

​
Skill File Format

Skills are Markdown files with YAML front matter: 
---
name: my-skill
description: A useful skill for agents
shortDescription: Brief description
license: MIT
compatibility:
  - DEVELOPER
  - ROUTA
version: 1.0.0
---

# Skill Content

Detailed instructions and documentation...

​
Serverless Environments

On serverless platforms (Vercel, AWS Lambda), skills are:
  1. Stored in the Postgres database
  2. Loaded on-demand from the database
  3. Can be uploaded via the upload endpoint
The filesystem may be read-only or empty in serverless environments.

​
Error Responses

​
404 Not Found

{
  "error": "Skill not found: git-workflow"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us