@callback child_spec(config :: map()) ::
  nil | Supervisor.child_spec() | [Supervisor.child_spec()]

Returns child specification(s) for supervised processes.

Called during AgentServer.init/1. Returned processes are monitored by the AgentServer and tracked in its state.

Parameters

• config - Per-agent configuration for this skill

Return Values

• nil - No child processes needed
• Supervisor.child_spec() - Single child process
• [Supervisor.child_spec()] - Multiple child processes

Example

def child_spec(config) do
  %{
    id: MyWorker,
    start: {MyWorker, :start_link, [config]}
  }
end

@callback handle_signal(signal :: term(), context :: map()) ::
  {:ok, term()} | {:ok, {:override, term()}} | {:error, term()}

Pre-routing hook called before signal routing in AgentServer.

Can inspect, log, or override which action runs for a signal.

Parameters

• signal - The incoming Jido.Signal struct
• context - Map with :agent, :agent_module, :skill, :skill_spec, :config

Returns

• {:ok, nil} or {:ok, :continue} - Continue to normal routing
• {:ok, {:override, action_spec}} - Bypass router, use this action instead
• {:error, reason} - Abort signal processing with error

Example

def handle_signal(signal, _context) do
  if signal.type == "admin.override" do
    {:ok, {:override, MyApp.AdminAction}}
  else
    {:ok, :continue}
  end
end

@callback mount(agent :: term(), config :: map()) :: {:ok, map() | nil} | {:error, term()}

Called when the skill is mounted to an agent during new/1.

Use this to initialize skill-specific state beyond schema defaults. This is a pure function - no side effects allowed.

Parameters

• agent - The agent struct (with state from previously mounted skills)
• config - Per-agent configuration for this skill

Returns

• {:ok, skill_state} - Map to merge into skill's state slice
• {:ok, nil} - No additional state (schema defaults only)
• {:error, reason} - Raises during agent creation

Example

def mount(_agent, config) do
  {:ok, %{initialized_at: DateTime.utc_now(), api_key: config[:api_key]}}
end

@callback router(config :: map()) :: term()

Returns the signal router for this skill.

The router determines how signals are routed to handlers.

@callback skill_spec(config :: map()) :: Jido.Skill.Spec.t()

Returns the skill specification with optional per-agent configuration.

This is the primary interface for getting skill metadata and configuration.

@callback subscriptions(config :: map(), context :: map()) :: [
  {module(), keyword() | map()}
]

Returns sensor subscriptions for this skill.

Called during AgentServer.post_init/1 to determine which sensors should be started for this skill. Each sensor is started with the provided configuration.

Parameters

• config - Per-agent configuration for this skill
• context - Map containing:
  • :agent_ref - The agent reference (name or PID)
  • :agent_id - The agent's unique identifier
  • :agent_module - The agent module
  • :skill_spec - The skill specification
  • :jido_instance - The Jido instance name

Returns

A list of {sensor_module, sensor_config} tuples where:

• sensor_module - A module implementing sensor behavior
• sensor_config - Keyword list or map of sensor configuration

Example

def subscriptions(_config, context) do
  [
    {MyApp.Sensors.FileSensor, [path: "/tmp/watch", target: context.agent_ref]},
    {MyApp.Sensors.TimerSensor, %{interval: 5000, target: context.agent_ref}}
  ]
end

@callback transform_result(
  action :: module() | String.t(),
  result :: term(),
  context :: map()
) :: term()

Transform the agent returned from AgentServer.call/3.

Called after signal processing on the synchronous call path only. Does not affect cast/2 or internal state - only the returned agent.

Parameters

• action - The signal type or action module that was executed
• result - The agent struct to transform
• context - Map with :agent, :agent_module, :skill, :skill_spec, :config

Returns

The transformed agent struct (or original if no transformation needed).

Example

def transform_result(_action, agent, _context) do
  # Add metadata to returned agent
  new_state = Map.put(agent.state, :last_call_at, DateTime.utc_now())
  %{agent | state: new_state}
end