Skills Hub API

Endpoints for publishing, searching, and installing skills. Publishing requires Pro or Studio tier. Searching and downloading is available to all authenticated users.

Publish a Skill

Upload a skill package to the Skills Hub.

POST /v1/skills/publish
Authorization: Bearer <jwt>
Content-Type: multipart/form-data

Form fields:

Field	Type	Required	Description
package	file	Yes	Skill package (tar.gz)
visibility	string	No	public (default), private, or org

Response: 201 Created

{
  "data": {
    "name": "code-reviewer",
    "display_name": "Code Reviewer",
    "version": "1.2.0",
    "visibility": "public",
    "published_at": "2024-01-15T10:30:00Z"
  }
}

Errors:

Code	Condition
TIER_REQUIRED	User is on Core tier
QUOTA_EXCEEDED	Pro user has reached the 50-skill publishing limit
VALIDATION_ERROR	Invalid manifest or package format
CONFLICT	Skill name already exists (by another author)

Publishing Limits

Tier	Limit
Pro	50 published skills
Studio	Unlimited

Search Skills

Search for skills by query. Available to all authenticated users.

GET /v1/skills/search?q=<query>
Authorization: Bearer <jwt>

Query parameters:

Parameter	Required	Description
q	Yes	Search query
page	No	Page number (default: 1)
limit	No	Results per page (default: 20, max: 100)

Response: 200 OK

{
  "data": {
    "results": [
      {
        "name": "code-reviewer",
        "display_name": "Code Reviewer",
        "description": "Automated code review with security and performance checks",
        "author": "nexus-team",
        "version": "1.2.0",
        "download_count": 1250,
        "visibility": "public",
        "tags": ["code-review", "security", "quality"],
        "published_at": "2024-01-10T00:00:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

Results are ranked by relevance and download count. The search matches against skill name, display name, description, and tags.

Get Skill Details

GET /v1/skills/:name
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "name": "code-reviewer",
    "display_name": "Code Reviewer",
    "description": "Automated code review with security and performance checks",
    "author": "nexus-team",
    "version": "1.2.0",
    "download_count": 1250,
    "visibility": "public",
    "tags": ["code-review", "security", "quality"],
    "manifest": {
      "entry_point": "prompt.md",
      "permissions": ["file_read", "text_search"]
    },
    "versions": ["1.0.0", "1.1.0", "1.2.0"],
    "published_at": "2024-01-10T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Download Skill

Download the skill package for local installation.

GET /v1/skills/:name/download
Authorization: Bearer <jwt>

Query parameters:

Parameter	Required	Description
version	No	Specific version to download (default: latest)

Response: 200 OK

Returns the skill package as a tar.gz file with Content-Type: application/gzip.

List My Published Skills

GET /v1/skills/my
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "skills": [
      {
        "name": "my-skill",
        "display_name": "My Skill",
        "version": "1.0.0",
        "visibility": "public",
        "download_count": 42,
        "published_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Unpublish a Skill

Remove a skill from the Skills Hub.

DELETE /v1/skills/:name
Authorization: Bearer <jwt>

Response: 204 No Content

Only the skill's author can unpublish it. Existing installations on user machines are not affected.