# Agent Skills

> The Agent Skills operations of the Hub REST API (9 operations).

URL: https://docs.synap.live/docs/reference/hub-api/agent-skills · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /agent-skills/list

List all agent skills

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `topic` | query | string |  |  |
| `q` | query | string |  |  |
| `tag` | query | string |  |  |
| `workspaceId` | query | string |  |  |
| `system` | query | string |  | 'true' to list only seeded system/* instruction skills |
| `limit` | query | string |  |  |
| `offset` | query | string |  |  |

Responses:

- `200`: Skills
- `403`: Forbidden

## GET /agent-skills/get

Get a single agent skill by slug

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | query | string | yes |  |
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Skill
- `404`: Not found

## POST /agent-skills/create

Create a agent skill

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes |  |
| `name` | string | yes |  |
| `description` | string |  |  |
| `topics` | array<string> |  |  |
| `body` | string | yes |  |
| `source` | string |  |  |
| `author` | string |  |  |
| `version` | string |  |  |
| `tags` | array<string> |  |  |

Responses:

- `200`: Created skill
- `409`: Slug conflict

## PATCH /agent-skills/update

Update a agent skill by slug

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | query | string | yes |  |

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string |  |  |
| `description` | string |  |  |
| `body` | string |  |  |

Responses:

- `200`: Updated skill
- `404`: Not found

## DELETE /agent-skills/delete

Delete a agent skill by id

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | query | string | yes |  |

Responses:

- `200`: Deleted
- `403`: Forbidden

## GET /agent-skills/executable

List executable skills (skills table)

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `userId` | query | string |  |  |
| `workspaceId` | query | string |  |  |
| `status` | query | SkillStatus |  |  |
| `approved` | query | "true" \| "false" |  |  |

Responses:

- `200`: Executable skills
- `403`: Forbidden
- `500`: Internal error

## POST /agent-skills/executable

Create an executable skill (skills table)

Request body (`application/json`): CreateSkillRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string | yes |  |
| `name` | string | yes |  |
| `description` | string |  |  |
| `code` | string | yes |  |
| `parameters` | object |  |  |
| `category` | SkillCategory |  |  |
| `workspaceId` | string |  |  |

Responses:

- `200`: Created executable skill
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /agent-skills/executable/{id}

Get one executable skill by id (skills table)

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `userId` | query | string |  |  |

Responses:

- `200`: Executable skill
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /agent-skills/import

Import a skill with associated documents (JSON payload)

Accepts a JSON body with skill metadata and an array of reference documents. Creates a pod-wide instruction skill and linked document rows. TODO: support ZIP (.skill file) upload with YAML frontmatter parsing.

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string | yes |  |
| `skill` | object | yes |  |
| `documents` | array<object> |  |  |

Responses:

- `200`: Imported skill + documents
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error