Skills API Reference
The Skills API lets you manage skills and agent-skill assignments programmatically. Skills are domain expertise packages that give agents specialized capabilities.
What the Skills API Does
- List and search available skills by category
- View skill details and assigned agents
- Assign and unassign skills to/from agents
- Toggle skill assignments on/off without removing them
- Discover the full skill catalog (including unassigned skills)
- Request skill assignments (creates HITL approval tasks)
Permissions
| Permission | Required For |
|---|---|
skills:read | List, get, search skills |
skills:write | Assign, unassign, update assignments |
Agent MCP Tools for Skills
Agents interact with skills through four MCP tools during conversations:
| Tool | Purpose |
|---|---|
| skill_query | Load instructions from an assigned skill for domain expertise |
| skill_discover | Browse the full skill catalog to find new skills |
| skill_request | Request assignment of a skill (creates HITL approval task) |
| connector_discover | Discover connected and available integrations with skill recommendations |
REST Endpoints
List Skills
GET /api/skills
Returns all skills available to your tenant. Filter by category, status (active/archived/all), and limit.
Each skill includes its 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 your tenant's skills (e.g., engineering, sales, support, finance).
Get Skill Details
GET /api/skills/:id
Returns full skill details including all assigned agents with their assignment status and configuration.
Get Skill's Assigned Agents
GET /api/skills/:id/agents
Returns all agents using this skill, with assignment details (enabled/disabled, priority, config, assigned by).
Assign Skill to Agent
POST /api/skills/:id/assign
Assigns a skill to an agent. Both must belong to the same tenant.
| Field | Type | Required | Description |
|---|---|---|---|
agentId | string | Yes | Agent UUID |
config | object | No | Per-assignment configuration |
priority | number | No | Higher = more likely to use (default: 0) |
Returns 201 on success, 400 if already assigned, 404 if skill or agent not found.
Unassign Skill from Agent
DELETE /api/skills/:id/unassign/:agentId
Removes a skill assignment.
Update Assignment
PATCH /api/skills/:id/assignments/:agentId
Update assignment configuration. All fields optional:
| Field | Type | Description |
|---|---|---|
enabled | boolean | Toggle skill on/off without removing |
config | object | Per-assignment configuration |
priority | number | Assignment priority |
Get Agent's Skills
GET /api/skills/agent/:agentId
Returns all skills assigned to a specific agent with assignment details.
MCP Tool Details
skill_query
Loads skill instructions for an assigned skill. Parameters: skillId, query, context, and optional referenceFile to load a specific reference document. Returns the skill metadata, instructions, matching references, and lists of available reference files and scripts.
skill_discover
Browses the full catalog. Parameters: category (filter) and query (keyword search). Returns metadata only (no instructions). Each skill includes assignedToMe to indicate current assignment status.
skill_request
Requests assignment of a skill from the catalog. Parameters: skillId (required) and reason (required). Creates a HITL task for admin approval.
connector_discover
Discovers connected and available integrations. Parameter: category (filter). Returns connected integrations, available integrations, and suggested skills per connector.
connector_request
Requests setup of a missing integration. Parameters: integrationId (required) and reason (required). Creates a task for admin review.
Error Codes
| Status | Description |
|---|---|
| 200 | Success |
| 201 | Created (assignment) |
| 400 | Bad request (validation error, duplicate assignment) |
| 401 | Unauthorized |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not found (skill or agent doesn't exist in tenant) |
See also: Skills Overview | Skills Architecture