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).

​
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. Use the skill id returned by this API when configuring agents — via the Agents API or in the nuwacom app.