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

ETS-backed registry for runtime-loaded skills.

Stores skill specs in an ETS table for fast lookup by name. Supports loading skills from directories at startup.

Lifecycle

Jido.AI.Skill.Registry supports two startup modes:

Explicit startup via start_link/1 under your supervisor tree.
Lazy startup via ensure_started/0, which is called automatically by public API functions.

This ensures consistent startup behavior regardless of supervision order.

Summary

Functions

activated?(name, opts \\ [])

Checks if a skill has been activated in the selected session.

all()

Lists all registered skill specs.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear()

Clears all registered skills.

clear_activations(opts \\ [])

Removes every activation for the selected session, including durable entries.

deactivate(name, opts \\ [])

Deactivates a skill, removing it from the activation table.

durable?(name, opts \\ [])

Checks if a skill is marked as durable.

ensure_started()

Starts the registry unless it is already running.

get_activation_context(name, opts \\ [])

Gets the activation context for an activated skill.

list()

Lists all registered skill names.

list_activated(opts \\ [])

Lists all activated skill names in the selected session.

load_from_paths(paths)

Loads all SKILL.md files from the given paths.

lookup(name)

Looks up a skill by name.

mark_activated(name, context, opts \\ [])

Marks a skill as activated with its activation context.

mark_durable(name, opts \\ [])

Marks an activated skill as durable for lifecycle bookkeeping.

Registers a skill spec in the registry.

start_link(opts \\ [])

Starts the registry.

unmark_durable(name, opts \\ [])

Clears durable lifecycle bookkeeping for a skill activation.

unregister(name)

Unregisters a skill by name.

Functions

activated?(name, opts \\ [])

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

Checks if a skill has been activated in the selected session.

The optional :session_id defaults to the caller process.

all()

@spec all() :: [Jido.AI.Skill.Spec.t()]

Lists all registered skill specs.

The registry is lazily started on first access.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear()

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

Clears all registered skills.

The registry is lazily started on first access.

clear_activations(opts \\ [])

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

Removes every activation for the selected session, including durable entries.

Use this when a conversation or agent session ends. The optional :session_id defaults to the caller process.

deactivate(name, opts \\ [])

@spec deactivate(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Deactivates a skill, removing it from the activation table.

Fails if the skill is marked as durable.

durable?(name, opts \\ [])

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

Checks if a skill is marked as durable.

The optional :session_id defaults to the caller process.

ensure_started()

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

Starts the registry unless it is already running.

get_activation_context(name, opts \\ [])

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

Gets the activation context for an activated skill.

The optional :session_id defaults to the caller process.

Returns

{:ok, context} - Skill is activated, context returned
{:error, :not_activated} - Skill not found in activation table

list()

@spec list() :: [String.t()]

Lists all registered skill names.

The registry is lazily started on first access.

list_activated(opts \\ [])

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

Lists all activated skill names in the selected session.

The optional :session_id defaults to the caller process.

load_from_paths(paths)

@spec load_from_paths([String.t()]) :: {:ok, non_neg_integer()} | {:error, term()}

Loads all SKILL.md files from the given paths.

The registry is lazily started on first access.

lookup(name)

@spec lookup(String.t()) :: {:ok, Jido.AI.Skill.Spec.t()} | {:error, term()}

Looks up a skill by name.

mark_activated(name, context, opts \\ [])

@spec mark_activated(String.t(), map(), keyword()) :: :ok | {:error, term()}

Marks a skill as activated with its activation context.

Used by Jido.AI.Skill.Activation to track activated skills. The optional :session_id defaults to the caller process.

mark_durable(name, opts \\ [])

@spec mark_durable(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Marks an activated skill as durable for lifecycle bookkeeping.

Durable skills remain in the activation table until the registry is cleared. Jido.AI.Actions.Skill.LoadSkill also tags its conversation tool result so ReAct can preserve the actual instructions during compaction. Calling this registry function alone does not mutate conversation context.

register(spec)

@spec register(Jido.AI.Skill.Spec.t()) :: :ok | {:error, term()}

Registers a skill spec in the registry.

start_link(opts \\ [])

Starts the registry.

unmark_durable(name, opts \\ [])

@spec unmark_durable(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Clears durable lifecycle bookkeeping for a skill activation.

unregister(name)

@spec unregister(String.t()) :: :ok | {:error, term()}

Unregisters a skill by name.

The registry is lazily started on first access.