Jido.AI.Skill.Activation (Jido AI v2.4.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
resource_policy - Policy captured at activation time
resource_provider - Optional provider binding for runtime resources

Filesystem skills list bundled resources from their skill root. Runtime specs may pass a :resource_provider binding in options; that provider is used for listing during activation and stored for fresh load_skill_resource calls.

Usage

# Activate a registered skill by name
{:ok, context} = Jido.AI.Skill.Activation.activate("code-review")

# Search trusted paths only when you give both options
{:ok, context} =
  Jido.AI.Skill.Activation.activate("code-review",
    paths: ["priv/skills"],
    trust: true
  )

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

Summary

Types

activation_context()

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()
    | Jido.AI.Skill.ResourceProvider.resource_listing(),
  resource_policy: Jido.AI.Skill.ResourcePolicy.t(),
  resource_provider: Jido.AI.Skill.ResourceProvider.binding() | nil,
  resource_backend: :filesystem | :provider | :none,
  provider_resource_ids: MapSet.t(String.t())
}

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.

Name activation first checks the registry. It does not scan the filesystem unless :paths and :trust are both present. A metadata-only catalog spec is loaded and strictly validated from its source file at activation time.

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()