Agent skill ID (ask_...) to activate.
The agent skill after activation, with status set to "active".
Enable a skill on an agent
Attaches a skill config to an agent, creating an agent skill record and
returning it with an initial status of "inactive". Use the activate
endpoint to make the skill available during agent runs.
Requires an app-scoped API key. The agent and config must both belong
to the authenticated app. Supplying a config that does not exist within
the app returns 422. Returns 201 on success.
Request body.
Agent ID (agt_...) to attach the skill to.
Skill config ID (cfg_...) that defines the skill's behavior. Must belong to the authenticated app.
Optionalinstruction?: stringOptional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
Optionalmetadata?: Record<string, unknown>Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
The newly created agent skill record.
Deactivate an agent skill
Sets the status of the specified agent skill to "inactive", preventing
the skill from being invoked during future agent runs. The skill record
is preserved and can be reactivated at any time.
Requires an app-scoped API key. Deactivating a skill that is already
inactive is a no-op and returns the skill unchanged.
Agent skill ID (ask_...) to deactivate.
The agent skill after deactivation, with status set to "inactive".
Remove a skill from an agent Permanently removes the specified agent skill, detaching the skill config from the agent. This action cannot be undone. To temporarily stop a skill from being invoked without removing it, use the deactivate endpoint instead. Requires an app-scoped API key. Returns 204 No Content on success.
Agent skill ID (ask_...) to remove.
No content
Retrieve an agent skill Returns the agent skill identified by its ID. The skill must belong to the authenticated app's scope. Requires an app-scoped API key.
Agent skill ID (ask_...) to retrieve.
The requested agent skill.
List agent skills
Returns all agent skills belonging to the authenticated app. Results include
skills in any status ("active" or "inactive"). Use the agent filter to
narrow results to one or more specific agents.
Requires an app-scoped API key. Supplying one or more agent values that
cannot be resolved within the app returns 404.
Optionalparams: { agent?: string[] }Query parameters.
Optionalagent?: string[]Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (agt_...) or lookup keys. Omit to return skills across all agents in the app.
List of agent skills matching the query.
Update an agent skill
Updates one or more mutable fields on the specified agent skill. All
parameters are optional; supply only the fields you want to change.
When template is provided, the platform re-resolves that skill template
and re-points the skill's underlying config in place. The skill's current
status is preserved. Any instruction or metadata supplied alongside
template override the template's defaults.
Requires an app-scoped API key. The skill must belong to the authenticated
app's scope.
Agent skill ID (ask_...) to update.
Request body.
Optionalinstruction?: stringPlain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
Optionalmetadata?: Record<string, unknown>Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
Optionaltemplate?: stringAgent skill template config ID (cfg_...), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any instruction or metadata values provided alongside template override the template defaults.
The agent skill after the update has been applied.
Activate an agent skill Sets the status of the specified agent skill to
"active", allowing the skill to be invoked during agent runs. The skill must already exist on the agent (created via the enable endpoint) and belong to the authenticated app's scope. Requires an app-scoped API key. Activating a skill that is already active is a no-op and returns the skill unchanged.