riffer 0.32.1 → 0.34.0

data/lib/riffer/providers/mock.rb

@@ -16,6 +16,13 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     Riffer::Skills::MarkdownAdapter
   end
 
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "mock"
+  end
+
   # Array of recorded method calls for assertions.
   attr_reader :calls #: Array[Hash[Symbol, untyped]]
 
@@ -36,16 +43,18 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     @stubbed_responses = []
   end
 
-  # Stubs the next response; call repeatedly to queue several.
+  # Stubs the next response; call repeatedly to queue several. +finish_reason+
+  # defaults to +:tool_calls+ when tool calls are present, else +:stop+.
   #
   #   provider.stub_response("Hello")
   #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
   #   provider.stub_response("Final response", token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
+  #   provider.stub_response("Truncated...", finish_reason: :length)
   #
   #--
-  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
-  def stub_response(content, tool_calls: [], token_usage: nil)
-    @stubbed_responses << normalize_response(content: content, tool_calls: tool_calls, token_usage: token_usage)
+  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?) -> void
+  def stub_response(content, tool_calls: [], token_usage: nil, finish_reason: nil)
+    @stubbed_responses << normalize_response(content: content, tool_calls: tool_calls, token_usage: token_usage, finish_reason: finish_reason)
   end
 
   # Clears all stubbed responses.
@@ -73,7 +82,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       role: response[:role] || "assistant",
       content: response[:content] || "",
       tool_calls: formatted_tool_calls,
-      token_usage: response[:token_usage]
+      token_usage: response[:token_usage],
+      finish_reason: response[:finish_reason] || (formatted_tool_calls.empty? ? :stop : :tool_calls)
     }
   end
 
@@ -96,7 +106,17 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #--
   #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    response[:token_usage]
+    usage = response[:token_usage]
+    usage && apply_pricing(usage)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    return nil unless response.is_a?(Hash)
+
+    reason = response[:finish_reason]
+    reason ? Riffer::Providers::FinishReason.new(reason: reason) : nil
   end
 
   #--
@@ -112,7 +132,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     response = params[:response]
     full_content = response[:content] || ""
@@ -150,7 +170,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     end
 
     yielder << Riffer::StreamEvents::TextDone.new(full_content)
-    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: token_usage) if token_usage
+    yield_finish_reason(yielder, extract_finish_reason(response))
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: apply_pricing(token_usage)) if token_usage
   end
 
   #--
@@ -163,7 +184,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
       @current_index += 1
       response
     else
-      {role: "assistant", content: "Mock response"}
+      normalize_response(content: "Mock response")
     end
   end
 end

data/lib/riffer/providers/open_ai.rb

@@ -5,6 +5,13 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
 
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "openai"
+  end
+
   #--
   #: (**untyped) -> void
   def initialize(**options)
@@ -74,11 +81,59 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     usage = typed_response.usage
     return nil unless usage
 
-    Riffer::Providers::TokenUsage.new(
+    build_token_usage(usage)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage(usage)
+    apply_pricing(Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens,
       cache_read_tokens: usage.input_tokens_details&.cached_tokens
-    )
+    ))
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    build_finish_reason(response)
+  end
+
+  # The Responses API reports no finish_reason field, so one is derived.
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
+    status = typed_response.status
+    return nil unless status
+
+    case status.to_sym
+    when :completed
+      reason = extract_tool_calls(typed_response).empty? ? :stop : :tool_calls
+      Riffer::Providers::FinishReason.new(reason: reason, raw: "completed")
+    when :incomplete
+      incomplete_finish_reason(typed_response)
+    when :failed
+      Riffer::Providers::FinishReason.new(reason: :error, raw: "failed")
+    else
+      Riffer::Providers::FinishReason.new(reason: :other, raw: status.to_s)
+    end
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason
+  def incomplete_finish_reason(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
+    raw = typed_response.incomplete_details&.reason&.to_s
+
+    reason = case raw
+    when "max_output_tokens" then :length
+    when "content_filter" then :content_filter
+    else :other
+    end
+
+    Riffer::Providers::FinishReason.new(reason: reason, raw: raw || "incomplete")
   end
 
   #--
@@ -117,7 +172,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     current_state = {
       tool_info: {}
@@ -149,8 +204,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           handle_web_search_status(event, status: "completed", yielder: yielder)
         when :"response.output_item.done"
           handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
-        when :"response.completed"
-          handle_response_completed(event, state: current_state, yielder: yielder)
+        when :"response.completed", :"response.incomplete", :"response.failed"
+          handle_response_finished(event, state: current_state, yielder: yielder)
         end
       end
     ensure
@@ -162,7 +217,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_output_item_added_function_call(event, state:, yielder:)
     state[:tool_info][event.item.id] = {
       name: decode_tool_name(event.item.name, tools: @current_tools),
@@ -171,31 +226,31 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_output_text_delta(event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDelta.new(event.delta)
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_output_text_done(event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDone.new(event.text)
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_summary_text_delta(event, state:, yielder:)
     yielder << Riffer::StreamEvents::ReasoningDelta.new(event.delta)
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_summary_text_done(event, state:, yielder:)
     yielder << Riffer::StreamEvents::ReasoningDone.new(event.text)
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_function_call_arguments_delta(event, state:, yielder:)
     tracked = state[:tool_info][event.item_id] || {}
     yielder << Riffer::StreamEvents::ToolCallDelta.new(
@@ -206,7 +261,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_function_call_arguments_done(event, state:, yielder:)
     tracked = state[:tool_info][event.item_id] || {}
     yielder << Riffer::StreamEvents::ToolCallDone.new(
@@ -218,28 +273,27 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_response_completed(event, state:, yielder:)
-    usage = event.response&.usage
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
+  def handle_response_finished(event, state:, yielder:)
+    response = event.response
+    return unless response
+
+    yield_finish_reason(yielder, build_finish_reason(response))
+
+    usage = response.usage
     return unless usage
 
-    yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: usage.input_tokens,
-        output_tokens: usage.output_tokens,
-        cache_read_tokens: usage.input_tokens_details&.cached_tokens
-      )
-    )
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(usage))
   end
 
   #--
-  #: (untyped, status: String, yielder: Enumerator::Yielder) -> void
+  #: (untyped, status: String, yielder: Riffer::Providers::_EventSink) -> void
   def handle_web_search_status(_event, status:, yielder:)
     yielder << Riffer::StreamEvents::WebSearchStatus.new(status)
   end
 
   #--
-  #: (untyped, yielder: Enumerator::Yielder) -> void
+  #: (untyped, yielder: Riffer::Providers::_EventSink) -> void
   def handle_output_item_done_web_search(event, yielder:)
     action = event.item.action
     case action

data/lib/riffer/providers/open_router.rb

@@ -10,6 +10,22 @@ require "json"
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL = "https://openrouter.ai/api/v1" #: String
 
+  FINISH_REASONS = {
+    "stop" => :stop,
+    "length" => :length,
+    "tool_calls" => :tool_calls,
+    "function_call" => :tool_calls,
+    "content_filter" => :content_filter,
+    "error" => :error
+  }.freeze #: Hash[String, Symbol]
+
+  # The GenAI semconv well-known provider name.
+  #--
+  #: () -> String
+  def self.semconv_provider_name
+    "openrouter"
+  end
+
   #--
   #: (?api_key: String?, **untyped) -> void
   def initialize(api_key: nil, **options)
@@ -70,10 +86,35 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     usage = typed_response.usage
     return nil unless usage
 
-    Riffer::Providers::TokenUsage.new(
+    build_token_usage(usage)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::TokenUsage
+  def build_token_usage(usage)
+    apply_pricing(Riffer::Providers::TokenUsage.new(
       input_tokens: usage.prompt_tokens,
-      output_tokens: usage.completion_tokens
-    )
+      output_tokens: usage.completion_tokens,
+      cache_read_tokens: usage.prompt_tokens_details&.cached_tokens
+    ))
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def extract_finish_reason(response)
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    build_finish_reason(typed_response.choices.first&.finish_reason)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(finish_reason)
+    return nil unless finish_reason
+
+    raw = finish_reason.to_s
+    return nil if raw.empty?
+
+    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
   end
 
   #--
@@ -105,7 +146,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  #: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream(params, yielder)
     # OpenRouter omits usage from streams unless explicitly opted in.
     stream_options = (params[:stream_options] || {}).merge(include_usage: true)
@@ -114,7 +155,8 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     state = {
       text: +"",
       reasoning: +"",
-      tool_calls: {}
+      tool_calls: {},
+      finish_reason: nil
     } #: Hash[Symbol, untyped]
 
     # Use stream_raw (not stream) — the latter yields a higher-level
@@ -139,10 +181,11 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
 
     yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
     yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
+    yield_finish_reason(yielder, build_finish_reason(state[:finish_reason]))
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_stream_chunk(chunk, state:, yielder:)
     typed_chunk = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
     choice = typed_chunk.choices&.first
@@ -154,22 +197,19 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       handle_tool_call_deltas(delta, state: state, yielder: yielder)
     end
 
+    state[:finish_reason] = choice.finish_reason if choice&.finish_reason
+
     if choice && finish_reason_is_tool_calls?(choice)
       emit_tool_call_done_events(state: state, yielder: yielder)
     end
 
     return unless typed_chunk.usage
 
-    yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::Providers::TokenUsage.new(
-        input_tokens: typed_chunk.usage.prompt_tokens,
-        output_tokens: typed_chunk.usage.completion_tokens
-      )
-    )
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(token_usage: build_token_usage(typed_chunk.usage))
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_text_delta(delta, state:, yielder:)
     typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
     content = typed_delta.content
@@ -180,7 +220,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_delta(delta, state:, yielder:)
     # The openai gem's typed Delta model strips fields not in OpenAI's spec
     # (so +delta.reasoning+ raises NoMethodError), but the underlying data
@@ -193,7 +233,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_tool_call_deltas(delta, state:, yielder:)
     typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
     tool_calls = typed_delta.tool_calls
@@ -221,7 +261,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  #: (state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def emit_tool_call_done_events(state:, yielder:)
     state[:tool_calls].each do |index, entry|
       fallback = "tool_#{index}"

data/lib/riffer/providers/repository.rb

@@ -5,6 +5,8 @@
 module Riffer::Providers::Repository
   extend self
 
+  # @rbs @key_for: Hash[singleton(Riffer::Providers::Base), Symbol]?
+
   REPO = {
     amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
     anthropic: -> { Riffer::Providers::Anthropic },
@@ -22,4 +24,11 @@ module Riffer::Providers::Repository
   def find(identifier)
     REPO.fetch(identifier.to_sym, nil)&.call
   end
+
+  # Returns the registry identifier for a provider class, or nil when unregistered.
+  #--
+  #: (singleton(Riffer::Providers::Base)) -> Symbol?
+  def key_for(provider_class)
+    (@key_for ||= REPO.to_h { |key, factory| [factory.call, key] })[provider_class]
+  end
 end

data/lib/riffer/providers/token_usage.rb

@@ -1,27 +1,32 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents token usage data from an LLM API call.
+# Normalized token usage for an LLM API call. Buckets carry the same
+# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Number of tokens in the input/prompt.
+  # Number of tokens entering the context window, including cache reads and writes.
   attr_reader :input_tokens #: Integer
 
-  # Number of tokens in the output/response.
+  # Number of tokens generated by the model, including reasoning/thinking tokens.
   attr_reader :output_tokens #: Integer
 
-  # Number of tokens written to cache, when the provider reports it.
+  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
   attr_reader :cache_write_tokens #: Integer?
 
-  # Number of tokens read from cache, when the provider reports it.
+  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
   attr_reader :cache_read_tokens #: Integer?
 
+  # Cost of the call, set when the model is priced. For observability, not billing.
+  attr_reader :cost #: Float?
+
   #--
-  #: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?) -> void
-  def initialize(input_tokens:, output_tokens:, cache_write_tokens: nil, cache_read_tokens: nil)
+  #: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
+  def initialize(input_tokens:, output_tokens:, cache_write_tokens: nil, cache_read_tokens: nil, cost: nil)
     @input_tokens = input_tokens
     @output_tokens = output_tokens
     @cache_write_tokens = cache_write_tokens
     @cache_read_tokens = cache_read_tokens
+    @cost = cost
   end
 
   # Returns the total number of tokens (input + output).
@@ -41,17 +46,19 @@ class Riffer::Providers::TokenUsage
       input_tokens: input_tokens + other.input_tokens,
       output_tokens: output_tokens + other.output_tokens,
       cache_write_tokens: add_nullable(cache_write_tokens, other.cache_write_tokens),
-      cache_read_tokens: add_nullable(cache_read_tokens, other.cache_read_tokens)
+      cache_read_tokens: add_nullable(cache_read_tokens, other.cache_read_tokens),
+      cost: add_cost(cost, other.cost)
     )
   end
 
-  # Converts the token usage to a hash; cache tokens are omitted when nil.
+  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   #--
-  #: () -> Hash[Symbol, Integer]
+  #: () -> Hash[Symbol, (Integer | Float)]
   def to_h
-    hash = {input_tokens: input_tokens, output_tokens: output_tokens}
+    hash = {input_tokens: input_tokens, output_tokens: output_tokens} #: Hash[Symbol, (Integer | Float)]
     hash[:cache_write_tokens] = cache_write_tokens if cache_write_tokens
     hash[:cache_read_tokens] = cache_read_tokens if cache_read_tokens
+    hash[:cost] = cost if cost
     hash
   end
 
@@ -63,4 +70,13 @@ class Riffer::Providers::TokenUsage
     return nil if a.nil? && b.nil?
     (a || 0) + (b || 0)
   end
+
+  # nil is absorbing, not zero: one unpriced call makes the run total nil
+  # rather than silently under-reporting.
+  #--
+  #: (Float?, Float?) -> Float?
+  def add_cost(a, b)
+    return nil if a.nil? || b.nil?
+    a + b
+  end
 end

data/lib/riffer/skills/activate_tool.rb

@@ -13,16 +13,25 @@ class Riffer::Skills::ActivateTool < Riffer::Tool
     required :name, String, description: "The skill name to activate"
   end
 
-  # Activates a skill by name and returns its body.
+  # Activates a skill by name and returns its wrapped body, or a short pointer when the skill is already active.
   #--
   #: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call(context:, name:)
     skills_context = context&.skills
     return error("Skills not configured") unless skills_context
     return error("Unknown skill: '#{name}'") unless skills_context.model_invocable?(name)
+    return text(already_active_message(name)) if skills_context.activated?(name)
 
-    text(skills_context.activate(name))
+    text(skills_context.activation_prompt(name))
   rescue Riffer::ArgumentError => e
     error(e.message)
   end
+
+  private
+
+  #--
+  #: (String) -> String
+  def already_active_message(name)
+    "Skill '#{name}' is already active. Its instructions are already available in your context."
+  end
 end

data/lib/riffer/skills/adapter.rb

@@ -21,4 +21,19 @@ class Riffer::Skills::Adapter
   def render_catalog(skills)
     raise NotImplementedError, "#{self.class} must implement #render_catalog"
   end
+
+  # Renders an activated skill body wrapped in identifying tags.
+  #--
+  #: (Riffer::Skills::Frontmatter, String) -> String
+  def render_activation(skill, body)
+    %(<skill_content name="#{skill.name}">\n#{body}\n</skill_content>)
+  end
+
+  # The behavioral instructions rendered alongside the catalog.
+  #--
+  #: () -> String
+  def catalog_instructions
+    "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions. " \
+      "If a skill's instructions already appear in your context (inside <skill_content> tags), follow them instead of activating the skill again."
+  end
 end