# `Planck.Agent.SkillIndex`
[🔗](https://github.com/alexdesousa/planck/blob/v0.2.2/lib/planck/agent/skill_index.ex#L1)

Holds all skill-related state for a running agent.

Two concerns live here:

- **System prompt index** — `pool`, `ranked`, and `top_n` are frozen at
  session start and used by `SystemPrompt.build/1` on every turn without
  calling any external function (cache-friendly).
- **Tool dispatch** — `names` and `refresh_fn` are used by the `load_skill`
  and `list_skills` tools to resolve and hot-reload the skill pool.

# `t`

```elixir
@type t() :: %Planck.Agent.SkillIndex{
  index_refresh_fn: (-> {[Planck.Agent.Skill.t()], [String.t()]}) | nil,
  names: [String.t()],
  pool: [Planck.Agent.Skill.t()],
  ranked: [String.t()],
  refresh_fn: (-> [Planck.Agent.Skill.t()]) | nil,
  top_n: pos_integer()
}
```

- `:pool` — frozen list of `Skill.t()` for the system prompt index; set at
  session start, refreshed at compaction
- `:ranked` — skill names ordered by usage history (from SQLite); used by the
  index to determine the "last used" section
- `:top_n` — maximum number of ranked skills shown in the index
- `:names` — skill names declared in TEAM.json `"skills"` array; used by
  `AgentSpec.to_start_opts/2` for tool resolution
- `:refresh_fn` — returns the live skill pool; called by `load_skill` and
  `list_skills` tools only, never by the system prompt
- `:index_refresh_fn` — called after compaction to rebuild `pool` and
  `ranked`; returns `{[Skill.t()], [String.t()]}`. `nil` means the index
  stays frozen for the entire session.

# `from_opts`

```elixir
@spec from_opts(keyword()) :: t()
```

Build a `SkillIndex` from agent start opts.

# `new`

```elixir
@spec new() :: t()
```

Return an empty skill index.

# `refresh`

```elixir
@spec refresh(t()) :: t()
```

Refresh `pool` and `ranked` by calling `index_refresh_fn`.

Called after compaction — the right moment to pick up newly created skills
and updated usage rankings without busting the prefix cache on normal turns.
Returns the index unchanged when no `index_refresh_fn` is set.

---

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