# `Pixir.Skills`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/skills.ex#L1)

Progressive-disclosure Skill discovery and loading (ADR 0010).

Skills are instruction packages rooted outside the ordinary Workspace file tool
authority. This module is the narrow Skills surface: list bounded metadata first,
then load a selected `SKILL.md` or supporting file from registered roots.

# `skill`

```elixir
@type skill() :: %{
  :name => String.t(),
  :description => String.t(),
  :scope => String.t(),
  :source => String.t(),
  :root => String.t(),
  :dir => String.t(),
  :path => String.t(),
  :short_path => String.t(),
  optional(:disable_model_invocation) => boolean()
}
```

# `workflow_template`

```elixir
@type workflow_template() :: %{
  id: String.t(),
  template_id: String.t(),
  version: pos_integer(),
  name: String.t(),
  description: String.t(),
  skill: String.t(),
  scope: String.t(),
  source: String.t(),
  path: String.t(),
  short_path: String.t(),
  parameters: map(),
  workflow: map()
}
```

# `activation_data`

```elixir
@spec activation_data(skill(), String.t(), String.t()) :: map()
```

Build durable activation data for a loaded main `SKILL.md`.

# `activations_for_prompt`

```elixir
@spec activations_for_prompt(String.t(), String.t(), keyword()) :: [map()]
```

Resolve explicit user-invoked Skills to activation data.

# `discover`

```elixir
@spec discover(
  String.t(),
  keyword()
) :: {:ok, %{skills: [skill()], warnings: [map()]}}
```

Discover registered Skills for a workspace, resolving duplicate names by scope.

# `get`

```elixir
@spec get(String.t(), String.t(), keyword()) :: {:ok, skill()} | {:error, map()}
```

Resolve a Skill name from the selected discovery set.

# `index_hash`

```elixir
@spec index_hash(
  String.t(),
  keyword()
) :: String.t()
```

Stable hash for the bounded Skills index rendered into a Turn prompt.

This is intentionally a deterministic pure helper returning `String.t()` directly.
It unwraps `Pixir.Provider.Cache.stable_hash/1` because index rendering already
controls the input shape. Fallible public operations keep the usual
`{:ok, term} | {:error, term}` shape.

# `instantiate_workflow_template`

```elixir
@spec instantiate_workflow_template(String.t(), map(), String.t(), keyword()) ::
  {:ok, %{template: map(), workflow: map()}} | {:error, map()}
```

Instantiate a Skill Workflow Template into a concrete Workflow spec.

The instantiated workflow is still executed by `Pixir.Workflows`; this function only
validates template arguments and substitutes placeholders in the template resource.

# `invoked_names`

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

Find explicit `$skill-name` and leading `/skill-name` mentions in user text.

# `main_file?`

```elixir
@spec main_file?(String.t()) :: boolean()
```

Whether a viewed path is the Skill's main instruction file.

# `render_activation`

```elixir
@spec render_activation(map()) :: String.t()
```

Render a durable activation as a Provider input fragment.

# `render_index`

```elixir
@spec render_index(
  String.t(),
  keyword()
) :: String.t()
```

Render a compact Skills index for the Turn system prompt.

# `view`

```elixir
@spec view(String.t(), String.t(), String.t(), keyword()) ::
  {:ok,
   %{
     skill: skill(),
     path: String.t(),
     abs_path: String.t(),
     content: String.t()
   }}
  | {:error, map()}
```

Read `SKILL.md` or a supporting file from a registered Skill.

# `workflow_template`

```elixir
@spec workflow_template(String.t(), String.t(), keyword()) ::
  {:ok, workflow_template()} | {:error, map()}
```

Resolve a Workflow Template by `skill/template`, `skill:template`, or unique id.

# `workflow_templates`

```elixir
@spec workflow_templates(
  String.t(),
  keyword()
) :: {:ok, %{templates: [workflow_template()], warnings: [map()]}}
```

Discover Workflow Templates shipped by registered Skills.

Templates live under `workflows/*.json` inside a Skill. Discovery reads only template
metadata/resources and never executes Skill scripts or records Skill Activations.

---

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