Skills give an agent reusable instructions, procedures, and domain knowledge.
Configured skills are sent inline when you create or update an agent; there is
no separate Skills resource endpoint.
Add each skill to the agent’s skills array with a stable name and the
complete Markdown file in content:
Use skills: [] when the agent has no configured skills.
Version behavior
Skills are part of an immutable agent version. Every update publishes a new
version.
Use PATCH to upsert only the supplied skills by name; skills you omit are
preserved. Use the full-replacement POST /v1/agents/{agentId} when you need to
remove a skill or replace the complete array. Include expectedVersion with
either method to reject the update if another caller published a version first.
See Partially update an agent
for collection merge semantics.
Response behavior
Agent and session responses expose configured skill names, not their Markdown
content:
Keep the source Markdown in your own configuration repository so you can include
it in later agent updates.
Learned skills
An agent can learn procedures while working in its persistent workspace. Learned
skills are scoped to the agent and stable subject. Public APIs to list, read,
update, and delete learned skills are coming soon.
The API described on this page only manages configured skills attached to agent
versions. Last modified on July 25, 2026
