# `Jido.AI.Skill.Activation`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/skill/activation.ex#L1)

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

# `activation_context`

```elixir
@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())
}
```

# `activate`

```elixir
@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!`

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

Activates a skill, raising on error.

# `activate_batch`

```elixir
@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?`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Lists all activated skills in the selected session.

## Examples

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*