Skip to navigation
AgentsSkills

Skills · Add a skill to an agent

View as Markdown

Writes a new workspace skill. The most direct way to change how an agent behaves without touching its prompt.

slug is generated from title when omitted. Choosing a slug that matches a built-in shadows that built-in, 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.

Request

This endpoint expects an object.
titlestringOptional
Section heading used when the skill is injected.
slugstringOptional

Stable identifier. Generated from the title when omitted. Reusing a built-in skill's slug shadows it, which requires extra.allow_skill_override on the agent.

content_textstringOptional
The skill itself, as prose the model reads. This is the field that changes behaviour.
doc_typestringOptional

Freeform label. Conventional values: skill, rule, knowledge, template, reference, custom.

injection_modeenumOptional

system_prompt folds the text into the prompt every run. context_only keeps it retrievable without spending prompt budget.

Allowed values:
is_enabledbooleanOptional
Attached but inert when false.
orderintegerOptional
Injection order. Appended last when omitted.

Response

The created skill.

Errors

403
Forbidden Error