Workjet
Back to Workjet

Skills API

The Skills API provides full CRUD operations for managing skills, creating versions, and publishing to the Marketplace. All endpoints require authentication.

Base URL

https://api.workjet.dev/v1

Endpoints

List Skills

GET /skills

Returns all skills visible to the authenticated user (private + team + public).

Response

{
  "skills": [
    {
      "id": "skill_abc123",
      "name": "Summarize Document",
      "description": "Generate a concise summary of any document",
      "category": "productivity",
      "visibility": "team",
      "status": "published",
      "currentVersion": 3,
      "modelTier": "standard",
      "createdAt": "2026-03-15T10:30:00Z",
      "updatedAt": "2026-04-01T14:22:00Z"
    }
  ],
  "total": 1
}

Create Skill

POST /skills

Creates a new skill with an initial version (v1).

Request Body

Field Type Required Description
name string Yes Skill name
description string Yes Description of what the skill does
category string Yes Category (e.g., productivity, development, data)
systemPrompt string Yes The system prompt that defines the skill's behavior
modelTier string No Model tier: standard, premium, or enterprise. Default: standard
tools string[] No Array of required MCP connector IDs
visibility string No private, team, or public. Default: private

Example

curl -X POST https://api.workjet.dev/v1/skills \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wj_live_..." \
  -d '{
    "name": "Bug Report Writer",
    "description": "Generate structured bug reports from informal descriptions",
    "category": "development",
    "systemPrompt": "You are a QA engineer. Given an informal bug description, produce a structured bug report with: title, severity, steps to reproduce, expected behavior, actual behavior, and environment details.",
    "modelTier": "standard",
    "visibility": "team"
  }'

Get Skill

GET /skills/:id

Returns a single skill with its full details and version history.

Update Skill

PUT /skills/:id

Updates a skill's metadata (name, description, category, visibility). To update the system prompt or tools, create a new version instead.

Request Body

Same fields as Create, all optional. Only provided fields are updated.

Delete Skill

DELETE /skills/:id

Permanently deletes a skill and all its versions. This action cannot be undone.

Versions

Create Version

POST /skills/:id/versions

Creates a new immutable version of the skill with updated system prompt and/or tools.

Request Body

Field Type Required Description
systemPrompt string Yes The updated system prompt
tools string[] No Updated list of required MCP connector IDs
modelTier string No Updated model tier
notes string No Release notes for this version

Response

{
  "version": 4,
  "skillId": "skill_abc123",
  "systemPrompt": "Updated prompt...",
  "tools": ["github", "linear"],
  "modelTier": "premium",
  "notes": "Added Linear integration for ticket creation",
  "createdAt": "2026-04-14T09:00:00Z"
}

Publishing

Publish Skill

POST /skills/:id/publish

Publishes the skill to the Marketplace. The skill's visibility must be set to public before publishing.

Response

{
  "id": "skill_abc123",
  "status": "published",
  "publishedAt": "2026-04-14T09:05:00Z",
  "marketplaceUrl": "https://marketplace.workjet.dev/skills/skill_abc123"
}

Note: Publishing requires the skill to have at least one version and its visibility set to public. Attempting to publish a private or team-only skill returns a 400 error.

Next Steps