Jido.AI.Skill.Activation (Jido AI v2.3.0)

First-class activation API for skills.

Manages skill activation lifecycle:

Prevents duplicate activation (idempotent within session)
Scopes activation by an explicit session ID or the caller process
Returns activation context for host/client injection
Tracks activated skills for session management

Activation Context

The context returned on activation includes:

skill - The full Jido.AI.Skill.Spec
skill_body - The rendered skill body text
root_dir - Skill root directory for resource resolution
resources - Listing of bundled resources

Usage

# Activate by name (looks up in discovery and registry)
{:ok, context} = Jido.AI.Skill.Activation.activate("code-review")

# Activate a spec directly
{:ok, metadata} = Jido.AI.Skill.Discovery.find("code-review")
{:ok, spec} = Jido.AI.Skill.Discovery.to_spec(metadata)
{:ok, context} = Jido.AI.Skill.Activation.activate(spec)

# Check if already activated
Jido.AI.Skill.Activation.activated?("code-review")

Summary

Functions

activate(skill, opts \\ [])

Activates a skill by name, spec, or module.

activate!(skill, opts \\ [])

Activates a skill, raising on error.

activate_batch(skills, opts \\ [])

Activates multiple skills in a batch.

activated?(name, opts \\ [])

Returns true if the named skill is activated in the selected session.

clear(opts \\ [])

Clears all activations for the selected session.

get_context(name, opts \\ [])

Returns the activation context for a skill without activating it.

list_activated(opts \\ [])

Lists all activated skills in the selected session.

Types

activation_context()

@type activation_context() :: %{
  skill: Jido.AI.Skill.Spec.t(),
  skill_body: String.t(),
  root_dir: String.t() | nil,
  resources: Jido.AI.Skill.Resources.resource_listing()
}

Functions

activate(skill, opts \\ [])

@spec activate(
  String.t() | Jido.AI.Skill.Spec.t() | module(),
  keyword()
) :: {:ok, activation_context()} | {:error, term()}

Activates a skill by name, spec, or module.

Returns activation context for use in host/client injection. Prevents duplicate activation within the same session. Pass :session_id when the session spans processes; otherwise the caller process is used.

Returns

{:ok, context} - Skill activated (or was already active)
{:error, reason} - Activation failed

Examples

{:ok, context} = Jido.AI.Skill.Activation.activate("code-review")
IO.puts(context.skill_body)

activate!(skill, opts \\ [])

@spec activate!(
  String.t() | Jido.AI.Skill.Spec.t() | module(),
  keyword()
) :: activation_context()

Activates a skill, raising on error.

activate_batch(skills, opts \\ [])

@spec activate_batch(
  [String.t() | Jido.AI.Skill.Spec.t() | module()],
  keyword()
) :: [ok: activation_context(), error: term()]

Activates multiple skills in a batch.

Returns results for each activation, with :ok or :error tuples.

Examples

results = Jido.AI.Skill.Activation.activate_batch(["code-review", "testing"])
# Returns: [{:ok, context1}, {:ok, context2}] or with errors

activated?(name, opts \\ [])

@spec activated?(
  String.t(),
  keyword()
) :: boolean()

Returns true if the named skill is activated in the selected session.

Examples

Jido.AI.Skill.Activation.activated?("code-review")

clear(opts \\ [])

@spec clear(keyword()) :: :ok | {:error, term()}

Clears all activations for the selected session.

Pass the same :session_id used for activation. Without one, the caller process is used.

get_context(name, opts \\ [])

@spec get_context(
  String.t(),
  keyword()
) :: {:ok, activation_context()} | {:error, :not_activated}

Returns the activation context for a skill without activating it.

Returns

{:ok, context} - Skill is activated, context returned
{:error, :not_activated} - Skill not activated

Examples

{:ok, context} = Jido.AI.Skill.Activation.get_context("code-review")

list_activated(opts \\ [])

@spec list_activated(keyword()) :: [String.t()]

Lists all activated skills in the selected session.

Examples

["code-review", "testing"] = Jido.AI.Skill.Activation.list_activated()