cmdc

defmodule CMDC.Skill.Selector do
  @moduledoc """
  Skill 选择器 behaviour — 为智能 Skill 筛选预留扩展点。

  默认情况下，CMDC 将所有已发现的 Skills 全量注入到系统提示词。
  当 Skill 数量增长时，全量注入会浪费 Token。Selector 允许外部系统
  （如 `cmdc_skill_engine`）根据任务内容智能选择最相关的 Skills。

  ## 使用方式

  在 Options / Config 中配置 `skill_selector`：

      CMDC.create_agent(
        model: "anthropic:claude-sonnet-4-5",
        skills_dirs: [".cmdc/skills"],
        skill_selector: MyApp.SkillSelector
      )

  ## 实现示例

      defmodule MyApp.SkillSelector do
        @behaviour CMDC.Skill.Selector

        @impl true
        def select(skills, query, _ctx) do
          # 简单关键词匹配示例；生产中可用 BM25 + LLM 精选
          Enum.filter(skills, fn skill ->
            String.contains?(String.downcase(skill.description), String.downcase(query))
          end)
        end
      end
  """

  @doc """
  从候选 Skills 中选择与当前任务最相关的子集。

  ## 参数

  - `skills` — 全部已发现的 `[%CMDC.Skill{}]`
  - `query` — 当前用户 prompt（用于匹配相关性）
  - `ctx` — Agent 执行上下文 `%CMDC.Context{}`

  ## 返回

  筛选后的 `[%CMDC.Skill{}]` 子集（顺序由实现决定）。
  返回空列表表示无匹配 Skill，不注入任何 Skill 到系统提示词。
  """
  @callback select(
              skills :: [CMDC.Skill.t()],
              query :: String.t(),
              ctx :: CMDC.Context.t()
            ) :: [CMDC.Skill.t()]
end