Skills API Reference

REST API endpoints for managing skills and agent-skill assignments. All endpoints require authentication and appropriate permissions.

Authentication

All requests require a valid JWT token in the Authorization header or session cookie. See Authentication for details.

Permissions

Permission	Required For
`skills:read`	List, get, search skills
`skills:write`	Assign, unassign, update assignments

Endpoints

List Skills

GET /api/skills

Returns all skills available to the authenticated tenant.

Query Parameters:

Parameter	Type	Default	Description
`category`	string	—	Filter by category (e.g., `engineering`, `sales`)
`status`	string	`active`	Filter by status: `active`, `archived`, `all`
`limit`	number	`100`	Max results to return

Response:

{
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "terraform",
      "slug": "terraform",
      "description": "Expert Terraform/OpenTofu Infrastructure as Code...",
      "category": "engineering",
      "toolIds": ["mcp-terraform-plan", "mcp-terraform-apply"],
      "config": {},
      "listingRef": null,
      "listingVersion": null,
      "locked": false,
      "currentVersion": "1.0.0",
      "status": "active",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-02-01T14:30:00Z",
      "source": "custom",
      "assignedAgentsCount": 3
    }
  ],
  "total": 42
}

source field: "custom" for tenant-created skills, "store" for skills purchased from the Store.

Get Skill Categories

GET /api/skills/categories

Returns distinct categories used by the tenant's skills.

Response:

{
  "categories": ["engineering", "sales", "support", "finance"]
}

Get Skill Details

GET /api/skills/:id

Returns full skill details including assigned agents.

Response:

{
  "skill": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "terraform",
    "slug": "terraform",
    "description": "Expert Terraform/OpenTofu Infrastructure as Code...",
    "category": "engineering",
    "toolIds": [],
    "config": {},
    "listingRef": null,
    "listingVersion": null,
    "locked": false,
    "currentVersion": "1.0.0",
    "status": "active",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-02-01T14:30:00Z",
    "source": "custom"
  },
  "assignedAgents": [
    {
      "agentId": "agent-123",
      "agentName": "DevOps Agent",
      "enabled": true,
      "assignedAt": "2026-01-20T09:00:00Z"
    }
  ]
}

Errors:

Status	Body	Cause
404	`{ "error": "Skill not found" }`	Skill ID doesn't exist or belongs to another tenant

Get Skill's Assigned Agents

GET /api/skills/:id/agents

Returns all agents using this skill.

Response:

{
  "agents": [
    {
      "id": "assignment-uuid",
      "agentId": "agent-123",
      "agentName": "DevOps Agent",
      "agentStatus": "active",
      "enabled": true,
      "config": {},
      "priority": 1,
      "assignedAt": "2026-01-20T09:00:00Z",
      "assignedBy": "user-456"
    }
  ]
}

Assign Skill to Agent

POST /api/skills/:id/assign

Assigns a skill to an agent. The skill and agent must belong to the same tenant.

Request Body:

{
  "agentId": "agent-123",
  "config": { "priority": 1 },
  "priority": 1
}

Field	Type	Required	Description
`agentId`	string	Yes	Agent UUID
`config`	object	No	Per-assignment configuration
`priority`	number	No	Priority (higher = more likely to use). Default: `0`

Response (201):

{
  "assignment": {
    "id": "assignment-uuid",
    "tenantId": "tenant-uuid",
    "skillId": "skill-uuid",
    "agentId": "agent-123",
    "skillVersion": "1.0.0",
    "listingRef": null,
    "enabled": true,
    "config": {},
    "priority": 1,
    "assignedAt": "2026-02-14T12:00:00Z",
    "assignedBy": "user-456"
  }
}

Errors:

Status	Body	Cause
400	`{ "error": "Skill already assigned to this agent" }`	Duplicate assignment
404	`{ "error": "Skill not found" }`	Invalid skill ID
404	`{ "error": "Agent not found" }`	Invalid agent ID

Unassign Skill from Agent

DELETE /api/skills/:id/unassign/:agentId

Removes a skill assignment from an agent.

Response:

{
  "success": true
}

Update Assignment

PATCH /api/skills/:id/assignments/:agentId

Update assignment configuration (enable/disable, change priority, modify config).

Request Body:

{
  "enabled": false,
  "config": { "customSetting": "value" },
  "priority": 2
}

All fields are optional. Only provided fields are updated.

Field	Type	Description
`enabled`	boolean	Toggle skill on/off without removing
`config`	object	Per-assignment configuration
`priority`	number	Assignment priority

Response:

{
  "success": true
}

Get Agent's Skills

GET /api/skills/agent/:agentId

Returns all skills assigned to a specific agent.

Response:

{
  "skills": [
    {
      "assignmentId": "assignment-uuid",
      "skillId": "skill-uuid",
      "name": "terraform",
      "slug": "terraform",
      "description": "Expert Terraform/OpenTofu...",
      "category": "engineering",
      "listingRef": null,
      "enabled": true,
      "config": {},
      "priority": 1,
      "assignedAt": "2026-01-20T09:00:00Z"
    }
  ]
}

MCP Tool: `skill_query`

Agents use this MCP tool to load skill content during conversations.

Tool Definition:

{
  "name": "skill_query",
  "description": "Load instructions from an assigned skill. Use when you need domain expertise.",
  "parameters": {
    "skillId": {
      "type": "string",
      "description": "Skill ID to query (from available skills list)"
    },
    "query": {
      "type": "string",
      "description": "The question or topic"
    },
    "context": {
      "type": "string",
      "description": "Additional context to improve relevance"
    },
    "referenceFile": {
      "type": "string",
      "description": "Specific reference file to load (e.g., 'ESCALATION-MATRIX.md')"
    }
  }
}

Response:

{
  "skill": {
    "id": "ticket-triage",
    "name": "ticket-triage",
    "description": "ITIL-based ticket triage...",
    "category": "support"
  },
  "instructions": "# Support Ticket Triage\n\n## Decision Tree\n...",
  "references": [
    {
      "filename": "ESCALATION-MATRIX.md",
      "content": "# Escalation Matrix\n\n..."
    }
  ],
  "availableReferences": [
    "ESCALATION-MATRIX.md",
    "SLA-DEFINITIONS.md",
    "CATEGORY-ROUTING.md"
  ],
  "availableScripts": [
    "classify-ticket.py"
  ]
}

MCP Tool: `skill_discover`

Browse the full skill catalog. Unlike skill_query (which only works with assigned skills), this tool shows all available skills.

Tool Definition:

{
  "name": "skill_discover",
  "description": "Browse the full skill catalog to find skills you don't have yet.",
  "parameters": {
    "category": {
      "type": "string",
      "description": "Filter by category (sales, engineering, etc.)"
    },
    "query": {
      "type": "string",
      "description": "Keyword search across skill names and descriptions"
    }
  }
}

Response:

{
  "skills": [
    {
      "id": "coding-agent",
      "name": "coding-agent",
      "description": "Full-stack software development capabilities...",
      "category": "engineering",
      "version": "1.0.0",
      "author": "meetloyd",
      "assignedToMe": false
    }
  ],
  "total": 42
}

Returns metadata only — no instructions. Each skill includes assignedToMe to indicate current assignment status.

MCP Tool: `skill_request`

Request assignment of a skill. Creates a human-in-the-loop task for admin approval.

Tool Definition:

{
  "name": "skill_request",
  "description": "Request assignment of a skill from the catalog.",
  "parameters": {
    "skillId": {
      "type": "string",
      "description": "The skill ID to request",
      "required": true
    },
    "reason": {
      "type": "string",
      "description": "Why you need this skill",
      "required": true
    }
  }
}

Response:

{
  "taskId": "task_abc123",
  "status": "pending",
  "message": "Skill assignment request created. An administrator will review and approve."
}

MCP Tool: `connector_discover`

Discover connected and available integrations, with skill recommendations per connector.

Tool Definition:

{
  "name": "connector_discover",
  "description": "Discover available and connected integrations.",
  "parameters": {
    "category": {
      "type": "string",
      "description": "Filter by category (productivity, crm, developer, etc.)"
    }
  }
}

Response:

{
  "connected": [
    { "id": "github", "name": "GitHub", "category": "developer" }
  ],
  "available": [
    { "id": "slack", "name": "Slack", "category": "communication" }
  ],
  "suggestedSkills": [
    { "integrationId": "github", "suggestedSkills": ["coding-agent", "webapp-testing"] }
  ]
}

MCP Tool: `connector_request`

Request setup of a missing integration. Creates a task for an admin.

Tool Definition:

{
  "name": "connector_request",
  "description": "Request setup of a missing integration.",
  "parameters": {
    "integrationId": {
      "type": "string",
      "description": "The integration slug (e.g., 'github', 'slack')",
      "required": true
    },
    "reason": {
      "type": "string",
      "description": "Why you need this integration",
      "required": true
    }
  }
}

Response:

{
  "taskId": "task_xyz789",
  "status": "pending",
  "message": "Integration setup request created for GitHub. An administrator will review."
}

Error Codes

Status	Description
200	Success
201	Created (assignment)
400	Bad request (validation error, duplicate assignment)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not found (skill or agent doesn't exist in tenant)
422	Unprocessable entity (schema validation failed)

Authentication​

Permissions​

Endpoints​

List Skills​

Get Skill Categories​

Get Skill Details​

Get Skill's Assigned Agents​

Assign Skill to Agent​

Unassign Skill from Agent​

Update Assignment​

Get Agent's Skills​

MCP Tool: skill_query​

MCP Tool: skill_discover​

MCP Tool: skill_request​

MCP Tool: connector_discover​

MCP Tool: connector_request​

Error Codes​

Authentication

Permissions

Endpoints

List Skills

Get Skill Categories

Get Skill Details

Get Skill's Assigned Agents

Assign Skill to Agent

Unassign Skill from Agent

Update Assignment

Get Agent's Skills

MCP Tool: `skill_query`

MCP Tool: `skill_discover`

MCP Tool: `skill_request`

MCP Tool: `connector_discover`

MCP Tool: `connector_request`

Error Codes