> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuwacom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills API Overview

> Create and manage skills in your nuwacom workspace programmatically

The Skills API lets you create and manage skills in your nuwacom workspace programmatically, for example to keep skill instructions in sync with an external source, provision skills from your own tooling, or discover the skill IDs needed to attach skills to agents.

A skill is a reusable instruction package for the AI: a name, a short description, and markdown instructions the AI loads on demand when they are relevant to the task at hand.

## Before you start

* **API key**: All endpoints require a Bearer token. Admins can create API keys in the workspace settings under the **API Keys** section.
* **Space scope**: Skills always belong to a space, so all endpoints are nested under the space path (`/api/v1/spaces/{spaceId}/skills`). The caller's role in that space must grant read permission for the Skills feature to list or read skills, and write permission to create, update, or delete them.
* **User-created skills only**: Built-in nuwacom skills and skill templates are not exposed through this API. The API returns and manages only user-created skills (created manually, via upload, GitHub import, or AI generation).
* **No draft state**: Unlike agents, skills have no draft/published distinction — changes are live immediately.

## Base URL

```
https://{customer-tenant}.nuwacom.ai
```

Replace `{customer-tenant}` with your workspace's tenant name.

## Available endpoints

| Method   | Endpoint                                    | Description                                                |
| -------- | ------------------------------------------- | ---------------------------------------------------------- |
| `GET`    | `/api/v1/spaces/{spaceId}/skills`           | [List skills](/api-reference/skills/list-skills)           |
| `POST`   | `/api/v1/spaces/{spaceId}/skills`           | [Create a new skill](/api-reference/skills/create-a-skill) |
| `GET`    | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Get skill details](/api-reference/skills/get-a-skill)     |
| `PATCH`  | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Update a skill](/api-reference/skills/update-a-skill)     |
| `DELETE` | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Delete a skill](/api-reference/skills/delete-a-skill)     |

## Instructions and SKILL.md

Under the hood a skill is stored as a `SKILL.md` file: a YAML frontmatter block with the skill's `name` and `description`, followed by the markdown instructions. The API abstracts this away:

* The `instructions` field on [Create](/api-reference/skills/create-a-skill) and [Update](/api-reference/skills/update-a-skill) is the **body** of the `SKILL.md` — write plain markdown, without frontmatter.
* The frontmatter is generated automatically from `name` and `description` and kept in sync when you change them.
* [Get a skill](/api-reference/skills/get-a-skill) returns the current body as `instructions`. The list endpoint omits it for performance; fetch a single skill to read it.

<Note>
  On update, `instructions` **fully replaces** the current body. Read the current value first via [Get a skill](/api-reference/skills/get-a-skill) if you want to append rather than replace. Omitting `instructions` keeps the current body (a pure rename only updates the frontmatter).
</Note>

## Pagination

[List skills](/api-reference/skills/list-skills) is paginated. Control the page with two optional query parameters:

| Parameter | Type    | Description                                                           |
| --------- | ------- | --------------------------------------------------------------------- |
| `limit`   | integer | Maximum number of skills to return (1–100). Defaults to `50`.         |
| `offset`  | integer | Number of skills to skip from the start of the list. Defaults to `0`. |

The response is an envelope: the skills are in `data`, alongside pagination metadata (`total`, `limit`, `offset`, `hasMore`). Page through the full list by increasing `offset` by `limit` until `hasMore` is `false`.

## Example: create a skill

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/skills \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meeting Notes",
    "description": "Formats meeting notes in the company template",
    "instructions": "When asked to write meeting notes:\n\n1. Start with date, participants, and agenda.\n2. Summarize decisions as bullet points.\n3. End with an action-item table (owner, task, due date)."
  }'
```

The response contains the new skill's `id`. The skill is active immediately and the AI can load it whenever its description matches the task.

## Field limits

| Field          | Limit                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `name`         | 1–64 characters; letters, digits, spaces, and hyphens; must start and end with a letter or digit. |
| `description`  | 1–1,024 characters.                                                                               |
| `instructions` | Up to 50,000 characters of markdown.                                                              |

## Use skills with agents

Agents can have specific skills attached. Use the skill `id` returned by this API when configuring agents — via the [Agents API](/api-reference/agents/list-agents) or in the nuwacom app.