Skip to navigation

Skills · Add or replace a skill

View as Markdown

Creates the skill, or replaces it whole — the same write the agent’s settings page makes. Send description and body separately; the server composes the SKILL.md frontmatter from them.

Using a built-in skill’s slug writes a workspace override that shadows it, which is refused unless the agent has extra.allow_skill_override.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agent_idstringRequired

Agent UUID or slug — both are accepted. From agents_listAgents.

slugstringRequired

Lowercase letters, numbers and hyphens, e.g. weekly-report. Also the frontmatter name.

Request

This endpoint expects an object.
titlestringRequired
Display name, e.g. "Weekly report".
descriptionstringRequired<=1024 characters

When to use the skill — triggering conditions only, starting “Use when…”. It is the one part of a skill always in the agent’s context, and what the settings page shows as “When to use this skill”. The server writes it into the SKILL.md frontmatter; do not repeat a frontmatter block in body.

bodystringRequired
The skill's instructions, as markdown the model reads. No frontmatter.
injection_modeenumOptionalDefaults to context_only

system_prompt folds the skill into every turn. context_only keeps it on demand: the agent opens it only when the description matches.

Allowed values:
is_enabledbooleanOptionalDefaults to true
Attached but inert when false.
referenceslist of objectsOptional

Files under the skill’s references/, mounted at /skills/<slug>/references/<filename>. The write is a whole snapshot: a reference left out is deleted.

Response

The saved skill, read back.

Errors

400
Bad Request Error
403
Forbidden Error