> ## 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) |
| `POST` | `/api/v1/spaces/{spaceId}/skills/{skillId}/enable` | [Enable a skill](/api-reference/skills/enable-a-skill) |
| `POST` | `/api/v1/spaces/{spaceId}/skills/{skillId}/disable` | [Disable a skill](/api-reference/skills/disable-a-skill) |
| `GET` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files` | [List skill files](/api-reference/skills/list-skill-files) |
| `GET` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Get a skill file](/api-reference/skills/get-a-skill-file) |
| `PUT` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Create or replace a skill file](/api-reference/skills/create-or-replace-a-skill-file) |
| `DELETE` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Delete a skill file](/api-reference/skills/delete-a-skill-file) |

## 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>

## Activation

Every skill carries an `enabled` flag in its API responses: the **space-wide** activation state. Enabled skills are loaded by the AI whenever their description matches the task; disabled skills are ignored. Skills start out enabled.

* [Disable a skill](/api-reference/skills/disable-a-skill) switches a skill off for the whole space without deleting it — the skill and its files stay untouched.
* [Enable a skill](/api-reference/skills/enable-a-skill) switches it back on.

A space can have at most **40 active skills**; enabling beyond that limit returns `409` — disable another skill first.

<Note>
  The API manages the space-wide state (admin semantics — API keys have no personal user context). Individual users can still override it for themselves in the nuwacom app; those personal preferences are not visible through this API.
</Note>

## Skill files

Besides its `SKILL.md`, a skill can carry additional files — reference documents, scripts, or templates the AI reads on demand when the instructions point to them. The file endpoints manage these files:

* [List skill files](/api-reference/skills/list-skill-files) returns every file with its `path`, `size` (bytes), and `mimeType`.
* [Get a skill file](/api-reference/skills/get-a-skill-file) returns a file's text content. Reference files by their relative `path` within the skill folder — nested paths like `reference/format.md` go directly into the URL.
* [Create or replace a skill file](/api-reference/skills/create-or-replace-a-skill-file) writes a text file. Parent folders are created implicitly by the path; the provided `content` fully replaces any existing file.
* [Delete a skill file](/api-reference/skills/delete-a-skill-file) removes a file. `SKILL.md` cannot be deleted — every skill needs one.

**Text files only**: the file endpoints handle text formats (markdown, scripts, JSON/YAML, CSV, SVG, and similar). Binary assets such as images and fonts can currently only be uploaded in the nuwacom app.

<Note>
  You *can* write `SKILL.md` through the file endpoints, which replaces the whole file including its frontmatter (a valid frontmatter `description` is synced back into the skill's metadata). Prefer [Update a skill](/api-reference/skills/update-a-skill) with `instructions` instead — it keeps the frontmatter consistent automatically.
</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: pass the skill `id`s returned by this API in the `skillIds` array when [creating](/api-reference/agents/create-an-agent) or [updating](/api-reference/agents/update-an-agent) an agent. See the [Agents API overview](/admin/api/agents-overview#skills) for the full semantics (exclusive loading, full replace, draft/publish).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.