Skills API

Endpoints for creating, searching, versioning, and distributing skills.

Skills#

Skill CRUD endpoints for listing, creating, reading, updating, deleting, and forking skills.

GET/api/v1/skills

List and search skills. Supports filtering by query string, scope, tag, and type. Results can be sorted and paginated.

Auth: Optional

Response

{
  "data": [
    {
      "id": "uuid",
      "scope": "backend",
      "slug": "code-reviewer",
      "displayName": "Code Reviewer",
      "description": "Automated code review skill",
      "visibility": "public",
      "tags": ["review", "quality"],
      "skillType": "command",
      "downloads": 1250,
      "stars": 42,
      "latestVersion": "1.3.0",
      "createdAt": "2025-06-01T12:00:00Z",
      "updatedAt": "2025-09-15T08:30:00Z"
    }
  ],
  "cursor": "uuid-of-last-item"
}

Supported query parameters:

Parameter	Type	Description
`q`	string	Full-text search query.
`scope`	string	Filter by scope (team slug).
`tag`	string	Filter by tag.
`type`	string	Filter by skill type (command, context, template, composite).
`sort`	string	Sort order: `downloads`, `updated`, `name`, `stars`, or `relevance`.
`cursor`	uuid	Cursor for pagination.
`limit`	number	Page size (default 20, max 100).

POST/api/v1/skills

Create a new skill. The scope must correspond to a team the authenticated user belongs to.

Auth: Required (write)

Request Body

{
  "scope": "backend",
  "slug": "code-reviewer",
  "displayName": "Code Reviewer",
  "description": "Automated code review skill for pull requests",
  "visibility": "public",
  "tags": ["review", "quality"]
}

Response

{
  "id": "uuid",
  "scope": "backend",
  "slug": "code-reviewer",
  "displayName": "Code Reviewer",
  "description": "Automated code review skill for pull requests",
  "visibility": "public",
  "tags": ["review", "quality"],
  "skillType": "command",
  "downloads": 0,
  "stars": 0,
  "latestVersion": null,
  "createdAt": "2025-09-20T10:00:00Z",
  "updatedAt": "2025-09-20T10:00:00Z"
}

GET/api/v1/skills/:scope/:slug

Get full details for a specific skill. Public skills are accessible without authentication; private skills require membership in the owning team.

Auth: Optional (respects visibility)

Response

{
  "id": "uuid",
  "scope": "backend",
  "slug": "code-reviewer",
  "displayName": "Code Reviewer",
  "description": "Automated code review skill for pull requests",
  "readme": "# Code Reviewer\n\nThis skill reviews pull requests...",
  "visibility": "public",
  "tags": ["review", "quality"],
  "skillType": "command",
  "downloads": 1250,
  "stars": 42,
  "deprecated": false,
  "deprecatedMessage": null,
  "latestVersion": "1.3.0",
  "createdAt": "2025-06-01T12:00:00Z",
  "updatedAt": "2025-09-15T08:30:00Z"
}

PATCH/api/v1/skills/:scope/:slug

Update a skill's metadata. Only provided fields are modified.

Auth: Required (write)

Request Body

{
  "displayName": "Code Reviewer Pro",
  "description": "Enhanced code review skill with style checking",
  "readme": "# Code Reviewer Pro\n\nUpdated documentation...",
  "visibility": "public",
  "tags": ["review", "quality", "style"],
  "deprecated": false,
  "deprecatedMessage": null
}

DELETE/api/v1/skills/:scope/:slug

Soft-delete a skill. The skill will be hidden from search results and cannot receive new versions. This operation can be reversed by an admin.

Auth: Required (admin)

POST/api/v1/skills/:scope/:slug/fork

Fork a skill into a different scope. Creates a copy of the skill and its latest published version under the target scope.

Auth: Required (write)

Request Body

{
  "targetScope": "frontend",
  "targetSlug": "code-reviewer-fork"
}

Response

{
  "id": "uuid",
  "scope": "frontend",
  "slug": "code-reviewer-fork",
  "displayName": "Code Reviewer",
  "forkedFrom": {
    "scope": "backend",
    "slug": "code-reviewer"
  },
  "createdAt": "2025-09-20T10:00:00Z"
}

Versions#

Version management endpoints for listing, uploading, and finalizing skill versions. Publishing a version is a two-step process: first prepare the upload to receive a presigned URL, then finalize to make the version available.

GET/api/v1/skills/:scope/:slug/versions

List all versions of a skill. Optionally filter by status.

Auth: Optional

Response

{
  "data": [
    {
      "id": "uuid",
      "version": "1.3.0",
      "status": "published",
      "changelog": "Added style checking support",
      "entryPoint": "SKILL.md",
      "skillType": "command",
      "fileCount": 5,
      "archiveSize": 12480,
      "createdAt": "2025-09-15T08:30:00Z"
    }
  ],
  "cursor": "uuid-of-last-item"
}

Supported query parameters:

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `published`, or `yanked`.
`cursor`	uuid	Cursor for pagination.
`limit`	number	Page size (default 20, max 100).

POST/api/v1/skills/:scope/:slug/versions

Prepare a version upload. Validates the manifest and file tree, then returns a presigned upload URL for the archive.

Auth: Required (write)

Request Body

{
  "version": "1.4.0",
  "fileTree": [
    { "path": "SKILL.md", "size": 2048, "sha256": "abc123..." },
    { "path": "examples/basic.md", "size": 512, "sha256": "def456..." }
  ],
  "archiveSha256": "789abc...",
  "archiveSize": 15360,
  "entryPoint": "SKILL.md",
  "skillType": "command",
  "installPath": ".claude/commands/",
  "manifestJson": {
    "name": "code-reviewer",
    "version": "1.4.0",
    "description": "Automated code review skill",
    "allowed-tools": "Read,Grep,Glob",
    "user-invocable": true
  },
  "minClaudeCodeVersion": "1.0.0"
}

Response

{
  "uploadUrl": "https://s3.example.com/presigned-upload-url",
  "versionId": "uuid"
}

Info

After receiving the uploadUrl, upload the archive via a PUT request directly to the presigned URL. Then call the finalize endpoint to complete the process.

POST/api/v1/skills/:scope/:slug/versions/:version/finalize

Finalize a prepared version. Set the status to 'published' to make it available for download, or 'draft' to keep it private.

Auth: Required (write)

Request Body

{
  "status": "published",
  "changelog": "Added style checking and improved performance"
}

Response

{
  "id": "uuid",
  "version": "1.4.0",
  "status": "published",
  "changelog": "Added style checking and improved performance",
  "createdAt": "2025-09-20T10:00:00Z"
}

GET/api/v1/skills/:scope/:slug/download

Download the archive for a specific version. Returns a JSON response containing a presigned S3 download URL and archive metadata. Accepts a semver string or a channel name.

Auth: Optional

Response

{
  "downloadUrl": "https://s3.example.com/presigned-download-url",
  "archiveSha256": "abc123...",
  "archiveSizeBytes": 15360,
  "version": "1.3.0"
}

Supported query parameters:

Parameter	Type	Description
`version`	string	Semver string (e.g. `1.3.0`) or channel name (e.g. `latest`, `stable`). Defaults to `latest`.

Channels#

Channels are named pointers to specific versions. They allow consumers to track a stability tier (e.g. latest, stable, canary) rather than pinning to a specific version number.

GET/api/v1/skills/:scope/:slug/channels

List all channels for a skill.

Auth: Optional

Response

{
  "data": [
    { "name": "latest", "version": "1.4.0", "updatedAt": "2025-09-20T10:00:00Z" },
    { "name": "stable", "version": "1.3.0", "updatedAt": "2025-09-15T08:30:00Z" }
  ]
}

PUT/api/v1/skills/:scope/:slug/channels/:name

Create or update a channel, pointing it to a specific published version.

Auth: Required (write)

Request Body

{
  "version": "1.2.0"
}

Response

{
  "name": "stable",
  "version": "1.2.0",
  "updatedAt": "2025-09-20T10:00:00Z"
}

DELETE/api/v1/skills/:scope/:slug/channels/:name

Delete a channel. The 'latest' channel cannot be deleted.

Auth: Required (admin)

Warning

The latest channel is managed automatically and cannot be deleted. Attempting to delete it will return a 400 error.

Stars#

Star and unstar skills to bookmark them. Starring is idempotent — starring an already-starred skill is a no-op.

PUT/api/v1/skills/:scope/:slug/star

Star a skill. This operation is idempotent.

Auth: Required (write)

DELETE/api/v1/skills/:scope/:slug/star

Remove a star from a skill.

Auth: Required (write)

Diff#

Compare two versions of a skill to see what changed between them.

GET/api/v1/skills/:scope/:slug/diff

Compare two versions of a skill. Returns a summary of changes and per-file diffs.

Auth: Optional

Response

{
  "from": "1.2.0",
  "to": "1.3.0",
  "summary": {
    "added": 1,
    "modified": 2,
    "removed": 0
  },
  "files": [
    {
      "path": "SKILL.md",
      "status": "modified",
      "additions": 12,
      "deletions": 3
    },
    {
      "path": "examples/advanced.md",
      "status": "added",
      "additions": 45,
      "deletions": 0
    },
    {
      "path": "examples/basic.md",
      "status": "modified",
      "additions": 5,
      "deletions": 2
    }
  ]
}

Supported query parameters:

Parameter	Type	Description
`from`	string	Source version (semver).
`to`	string	Target version (semver).