@spec activate(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentSkill.t()} | {:error, ArchAstro.Error.reason()}

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.

The agent skill after activation, with status set to "active".

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AgentSkills.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentSkill.t()} | {:error, ArchAstro.Error.reason()}

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.

The newly created agent skill record.

@spec deactivate(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentSkill.t()} | {:error, ArchAstro.Error.reason()}

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.

The agent skill after deactivation, with status set to "inactive".

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

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.

No content

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentSkill.t()} | {:error, ArchAstro.Error.reason()}

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.

The requested agent skill.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1AgentSkills.Params.t()
) ::
  {:ok, ArchAstro.Types.AgentSkillList.t()} | {:error, ArchAstro.Error.reason()}

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.

List of agent skills matching the query.

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1AgentSkillsAgentSkill.Input.t()
) :: {:ok, ArchAstro.Types.AgentSkill.t()} | {:error, ArchAstro.Error.reason()}

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.

The agent skill after the update has been applied.