Skip to main content
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

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

​
Available endpoints

​
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 and Update 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 returns the current body as instructions. The list endpoint omits it for performance; fetch a single skill to read it.
On update, instructions fully replaces the current body. Read the current value first via Get a skill if you want to append rather than replace. Omitting instructions keeps the current body (a pure rename only updates the frontmatter).

​
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 switches a skill off for the whole space without deleting it — the skill and its files stay untouched.
  • 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.
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.

​
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 returns every file with its path, size (bytes), and mimeType.
  • 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 writes a text file. Parent folders are created implicitly by the path; the provided content fully replaces any existing file.
  • 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.
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 with instructions instead — it keeps the frontmatter consistent automatically.

​
Pagination

List skills is paginated. Control the page with two optional query parameters: 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

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

​
Use skills with agents

Agents can have specific skills attached: pass the skill ids returned by this API in the skillIds array when creating or updating an agent. See the Agents API overview for the full semantics (exclusive loading, full replace, draft/publish).