Skills API

Skills CRUD endpoints

Search Skills

Search for published skills on OpenSkill.

GET /api/skills

GET /api/skills?q=testing&tag=tdd&sort=downloads&limit=20

Parameter	Type	Description
q	string	Search query
tag	string	Filter by tag
sort	string	Sort order: relevance, downloads, newest (default: relevance)
page	number	Page number (default 1)
limit	number	Results per page (default 20, max 100)

Response:

200 OK

{
  "skills": [
    {
      "slug": "testing-helper",
      "name": "testing-helper",
      "description": "Generate comprehensive test suites",
      "version": "1.0.0",
      "author": { "username": "johndoe" },
      "tags": ["testing", "tdd"],
      "downloads": 1234,
      "createdAt": "2025-01-15T00:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Discover Skills

Discover skills from Git repositories and other sources.

GET /api/skills/discover

GET /api/skills/discover?q=react&source=github&sort=stars

Parameter	Type	Description
q	string	Search query
source	string	Filter by source (e.g., github)
tags	string	Comma-separated tag filter
sort	string	Sort order: relevance, stars, newest
page	number	Page number (default 1)
limit	number	Results per page (default 20, max 100)

Get Skill

Get full details for a specific skill by slug.

GET /api/skills/[slug]

GET /api/skills/testing-helper

Response:

200 OK

{
  "slug": "testing-helper",
  "name": "testing-helper",
  "description": "Generate comprehensive test suites",
  "version": "1.0.0",
  "content": "# Testing Helper\n\nWhen asked to write tests...",
  "author": { "username": "johndoe" },
  "tags": ["testing", "tdd"],
  "agents": ["claude", "cursor"],
  "downloads": 1234,
  "status": "published",
  "createdAt": "2025-01-15T00:00:00Z",
  "updatedAt": "2025-06-01T00:00:00Z"
}

Publish Init

Initialize a skill publish. Returns a presigned URL for uploading the skill file to S3. Requires authentication.

POST /api/skills/publish/init

{
  "slug": "testing-helper",
  "version": "1.0.0",
  "fileHash": "sha256:abc123...",
  "fileSize": 2048,
  "name": "testing-helper",
  "description": "Generate comprehensive test suites",
  "category": "testing",
  "tags": ["testing", "tdd"],
  "agents": ["claude", "cursor"]
}

Parameter	Type	Description
slug*	string	Unique skill slug
version*	string	Semantic version
fileHash*	string	SHA-256 hash of the skill file
fileSize*	number	File size in bytes
name*	string	Display name for the skill
description*	string	Brief description
category	string	Skill category
tags	string[]	Tags for categorization
agents	string[]	Compatible agents

Response:

200 OK

{
  "uploadUrl": "https://s3.amazonaws.com/...",
  "uploadId": "upl_abc123",
  "expiresIn": 3600
}

Publish Complete

Complete the publish after uploading the skill file to S3. The skill will be created as a draft.

POST /api/skills/publish/complete

{
  "uploadId": "upl_abc123",
  "slug": "testing-helper"
}

Parameter	Type	Description
uploadId*	string	Upload ID from publish/init
slug*	string	Skill slug

Response:

200 OK

{
  "success": true,
  "skill": {
    "slug": "testing-helper",
    "version": "1.0.0",
    "status": "draft"
  }
}

After completing publish, the skill is in draft status. Use osk publish <slug> to make it public.

Download Skill

Download a skill's content. Returns a presigned URL for downloading the skill file.

GET /api/skills/[slug]/download

GET /api/skills/testing-helper/download?version=1.0.0

Parameter	Type	Description
version	string	Specific version to download (optional, defaults to latest)

Response:

200 OK

{
  "downloadUrl": "https://s3.amazonaws.com/...",
  "version": "1.0.0",
  "fileHash": "sha256:abc123..."
}

Versions

List all published versions of a skill.

GET /api/skills/[slug]/versions

GET /api/skills/testing-helper/versions

Response:

200 OK

{
  "versions": [
    {
      "version": "1.0.0",
      "createdAt": "2025-01-15T00:00:00Z",
      "fileHash": "sha256:abc123..."
    },
    {
      "version": "0.9.0",
      "createdAt": "2025-01-01T00:00:00Z",
      "fileHash": "sha256:def456..."
    }
  ]
}

Audit Skill

Run a security audit on a skill. Supports auditing by content or by URL.

POST /api/skills/audit

{
  "content": "---\nname: my-skill\n---\n\n# My Skill\n..."
}

Parameter	Type	Description
content	string	Skill markdown content to audit (use this or url)
url	string	URL of skill to audit (use this or content)

Response:

200 OK

{
  "score": 95,
  "passed": true,
  "findings": [
    {
      "rule": "no-destructive-commands",
      "severity": "warning",
      "message": "Skill references 'rm' command",
      "line": 15
    }
  ]
}