riffer 0.24.2 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c289127e9ee54b63afe3ca65349054459f906553e37d39cf5001c6876ee6b1e9
-  data.tar.gz: 22e8286f74b98f23d00e49c6c337bcba9c68f452763be082533fb0f082688632
+  metadata.gz: 4097cc002e3ac3c06c0e354fddd33de5c5fb7b51ed53c6080478de972125b8b7
+  data.tar.gz: eed8cf5ed60830b206e00ef62640aa691aa9b32140c2ec5852b69d39fb775e5f
 SHA512:
-  metadata.gz: f2e75464955df9f0fd7dd1d57eef8b54a763d77d8d80ba46ff0bc2c3e11c8fa258de633ff5288551be299d8a92b10c99419ab95acdcb86683f9fb1ca0331ead2
-  data.tar.gz: ce4a3e9ee805e074142a02a84ceb6089be539fb22d0a4d141de4eef43d8b9a0843f931ab05298571c79e933f1d1a6336c4f8b3ea443da403485e46a001d4dc45
+  metadata.gz: f6d511f5de22e4a04521ac1c12e26aa7f508a6b0c2649e124447995c64a4b3d66a9a6cace08869db7f66c129bb38aa1f169fde5c42e3a6b8612be07b81e320d7
+  data.tar.gz: 03c5075c171920a16245b73ab1925a4013f029d5aabe686fdd3a904886c8113837c11a8584f4b1243517c7935f1ae8216882101d63803c1ad25c209353a64612

data/.agents/architecture.md

@@ -40,7 +40,7 @@ Adapters for LLM APIs. The base class uses a template-method pattern — `genera
 
 Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
 
-Each provider declares a preferred skill adapter via `self.skills_adapter` (Markdown for most, XML for Anthropic).
+Each provider declares a preferred skill adapter via `self.skills_adapter(model = nil)`. Default is Markdown; Anthropic returns XML; Amazon Bedrock returns XML when the model identifier matches an Anthropic model (e.g. `anthropic.claude-…` or `us.anthropic.claude-…`); Mock returns XML when the model name contains `claude`. The agent passes the resolved model identifier so proxy providers (Bedrock, Mock) can pick the right adapter without per-agent overrides.
 
 ### Skills (`lib/riffer/skills/`)
 

data/.bundle/config

@@ -0,0 +1,4 @@
+---
+BUNDLE_LOCKFILE_CHECKSUMS: "false"
+BUNDLE_PATH: "/home/runner/work/riffer/riffer/vendor/bundle"
+BUNDLE_DEPLOYMENT: "true"

data/.release-please-config.json

@@ -1,10 +1,12 @@
 {
   "release-type": "ruby",
+  "bump-minor-pre-major": true,
   "packages": {
     ".": {
       "release-type": "ruby",
       "package-name": "riffer",
-      "version-file": "lib/riffer/version.rb"
+      "version-file": "lib/riffer/version.rb",
+      "bump-minor-pre-major": true
     }
   }
 }

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.24.2"
+  ".": "0.26.0"
 }

data/.ruby-version

@@ -1 +1 @@
-3.4.8
+4.0.3

data/AGENTS.md

@@ -4,7 +4,7 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
 ## Quick Reference
 
-- **Ruby**: 3.3.0+
+- **Ruby**: 3.3.0+ (CI: 3.3, 3.4, 4.0)
 - **Lint + Test**: `bundle exec rake`
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.0](https://github.com/janeapp/riffer/compare/riffer/v0.25.0...riffer/v0.26.0) (2026-04-29)
+
+
+### Features
+
+* model-aware skills adapter selection ([#232](https://github.com/janeapp/riffer/issues/232)) ([74a5323](https://github.com/janeapp/riffer/commit/74a5323945f3f6f30538d472400cc5fe27b588da))
+
+## [0.25.0](https://github.com/janeapp/riffer/compare/riffer/v0.24.2...riffer/v0.25.0) (2026-04-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* Removed Riffer::Skills::Adapter#activate_tool. Set the activation tool via Riffer.config.skills.default_activate_tool, or per-agent with `skills do; activate_tool MyTool; end`.
+* Riffer::Skills::Adapter.new now requires skill_activate_tool:. The agent wires this up; only matters if you construct an adapter yourself. Custom adapters that override #initialize must call super.
+
+### Features
+
+* class-level tool resolution; lift activation tool to global config ([#230](https://github.com/janeapp/riffer/issues/230)) ([936c4ba](https://github.com/janeapp/riffer/commit/936c4baa6beff4f2cd6c87bfe90be8c20a7f30e1))
+
 ## [0.24.2](https://github.com/janeapp/riffer/compare/riffer/v0.24.1...riffer/v0.24.2) (2026-04-23)
 
 

data/README.md

@@ -6,7 +6,7 @@ The all-in-one Ruby framework for building AI-powered applications and agents.
 
 ## Requirements
 
-- Ruby 3.3 or later
+- Ruby 3.3, 3.4, or 4.0
 
 ## Installation
 

data/docs/10_CONFIGURATION.md

@@ -54,6 +54,34 @@ end
 
 Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
+### Skills
+
+Skills-related global configuration lives under `config.skills`.
+
+#### Default activation tool
+
+Override the tool the LLM calls to activate a skill. Defaults to `Riffer::Skills::ActivateTool`:
+
+```ruby
+Riffer.configure do |config|
+  config.skills.default_activate_tool = MyCustomActivateTool
+end
+```
+
+Per-agent override is available inside the `skills` block via `activate_tool MyCustomActivateTool`. See [Skills — Custom Activation Tool](13_SKILLS.md#custom-activation-tool).
+
+#### Default backend
+
+Set an app-wide default skills backend. Used by any agent that declares a `skills` block without specifying its own `backend`:
+
+```ruby
+Riffer.configure do |config|
+  config.skills.default_backend = Riffer::Skills::FilesystemBackend.new(".skills")
+end
+```
+
+Accepts a `Riffer::Skills::Backend` instance or a `Proc` that receives `context` and returns a backend. Defaults to `nil` — agents that don't set their own backend get no skills, matching pre-existing behavior. Per-agent backends override this default.
+
 ### Message ID Strategy
 
 Opt in to stable identifiers on every message for logging, persistence, or replay:

data/docs/13_SKILLS.md

@@ -70,7 +70,7 @@ end
 
 ### Custom Adapter
 
-The adapter controls how the skill catalog is rendered in the system prompt and which tool the LLM calls to activate a skill. The adapter is auto-selected by provider (Markdown for most, XML for Anthropic). Override with:
+The adapter controls how the skill catalog is rendered in the system prompt and which tool the LLM calls to activate a skill. The adapter is auto-selected by provider, with model-aware fallback for proxy providers — Markdown for most providers, XML for Anthropic, and XML for Anthropic models routed through Amazon Bedrock (e.g. `us.anthropic.claude-sonnet-4-6`). Override with:
 
 ```ruby
 skills do
@@ -125,24 +125,48 @@ end
 
 ## Custom Adapters
 
-Subclass `Riffer::Skills::Adapter` to customize how the skill catalog is rendered and which tool the LLM uses to activate skills:
+Subclass `Riffer::Skills::Adapter` to customize how the skill catalog is rendered in the system prompt:
 
 ```ruby
 class CustomAdapter < Riffer::Skills::Adapter
   def render_catalog(skills)
     # Return String (skill catalog for the system prompt)
-    # Use `activate_tool.name` to reference the activation tool
+    # Use `skill_activate_tool.name` to reference the activation tool the LLM should call
   end
+end
+```
+
+The activation tool is set on the adapter at construction (`Riffer::Skills::Adapter.new(skill_activate_tool: ...)`) and exposed via the `skill_activate_tool` reader. The agent wires this up automatically — custom adapters that override `initialize` must call `super`.
+
+The built-in adapters are `Riffer::Skills::MarkdownAdapter` (default) and `Riffer::Skills::XmlAdapter` (used by Anthropic).
 
-  def activate_tool
-    # Return a Riffer::Tool subclass
-    # Defaults to Riffer::Skills::ActivateTool
-    Riffer::Skills::ActivateTool
+## Custom Activation Tool
+
+The activation tool is global. Set it once via `Riffer.config.skills.default_activate_tool` to apply across all agents, or override per-agent inside the `skills` block.
+
+The recommended approach is to subclass `Riffer::Skills::ActivateTool` so the identifier, description, params, and timeout are inherited — you only override the behavior you need to change:
+
+```ruby
+# Wrap the default behavior with telemetry
+class InstrumentedActivateTool < Riffer::Skills::ActivateTool
+  def call(context:, name:)
+    Telemetry.measure("skill_activate", skill: name) { super }
+  end
+end
+
+# Global default
+Riffer.config.skills.default_activate_tool = InstrumentedActivateTool
+
+# Per-agent override
+class MyAgent < Riffer::Agent
+  skills do
+    backend Riffer::Skills::FilesystemBackend.new(".skills")
+    activate_tool InstrumentedActivateTool
   end
 end
 ```
 
-The built-in adapters are `Riffer::Skills::MarkdownAdapter` (default) and `Riffer::Skills::XmlAdapter` (used by Anthropic).
+If you need a different parameter shape entirely, subclass `Riffer::Tool` directly and provide your own `identifier`, `description`, `params`, and `call`.
 
 ## Accessing Skills in Tools
 

data/lib/riffer/agent.rb

@@ -132,6 +132,46 @@ class Riffer::Agent
     @tools_config = tools_or_lambda
   end
 
+  # Returns the tool classes the LLM should see for this agent.
+  #
+  # Class-level companion to the instance #resolved_tools. Resolves the
+  # Proc form of +uses_tools+ and appends the skill activation tool when
+  # a +skills+ block is configured. Does not read the skills backend —
+  # the LLM-facing tool schema reflects class-level intent, not the
+  # runtime state of any backend.
+  #
+  # When +uses_tools+ is a Proc, +context+ is forwarded to it.
+  #
+  # The activation tool class is resolved from the agent's
+  # <tt>skills do; activate_tool ...; end</tt> override when set, otherwise
+  # from <tt>Riffer.config.skills.default_activate_tool</tt>.
+  #
+  # Raises Riffer::ArgumentError on tool name conflicts with the skill
+  # activation tool.
+  #
+  #--
+  #: (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+  def self.resolved_tool_classes(context: nil)
+    base = resolve_uses_tools_config(context)
+    return base unless skills
+
+    skill_activate_tool_class = skills.activate_tool || Riffer.config.skills.default_activate_tool
+    if base.any? { |t| t.name == skill_activate_tool_class.name }
+      raise Riffer::ArgumentError, "Tool name conflict with skill tools: #{skill_activate_tool_class.name}"
+    end
+    base + [skill_activate_tool_class]
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+  def self.resolve_uses_tools_config(context)
+    config = uses_tools
+    return [] if config.nil?
+    return config unless config.is_a?(Proc)
+    config.arity.zero? ? config.call : config.call(context)
+  end
+  private_class_method :resolve_uses_tools_config
+
   # Gets or sets the tool runtime for this agent.
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
@@ -717,25 +757,7 @@ class Riffer::Agent
   #--
   #: () -> Array[singleton(Riffer::Tool)]
   def resolved_tools
-    @resolved_tools ||= begin
-      config = self.class.uses_tools
-
-      tools = if config.nil?
-        []
-      elsif config.is_a?(Proc)
-        (config.arity == 0) ? config.call : config.call(@context)
-      else
-        config
-      end
-
-      if @skills_state
-        activate_tool = @skills_state.adapter.activate_tool
-        raise Riffer::ArgumentError, "Tool name conflict with skill tools: #{activate_tool.name}" if tools.any? { |t| t.name == activate_tool.name }
-        tools + [activate_tool]
-      else
-        tools
-      end
-    end
+    @resolved_tools ||= self.class.resolved_tool_classes(context: @context)
   end
 
   #--
@@ -769,7 +791,7 @@ class Riffer::Agent
   def resolve_skills(context = @context)
     return nil unless self.class.skills
 
-    backend = self.class.skills.backend
+    backend = self.class.skills.backend || Riffer.config.skills.default_backend
     return nil unless backend
 
     backend = backend.is_a?(Proc) ? backend.call(context) : backend
@@ -777,9 +799,14 @@ class Riffer::Agent
     return nil if skills_list.empty?
 
     skills = skills_list.to_h { |s| [s.name, s] }
-    adapter_class = self.class.skills.adapter || provider_class.skills_adapter
+    adapter_class = self.class.skills.adapter || provider_class.skills_adapter(@model_name)
+    skill_activate_tool_class = self.class.skills.activate_tool || Riffer.config.skills.default_activate_tool
 
-    skills_context = Riffer::Skills::Context.new(backend: backend, skills: skills, adapter: adapter_class.new)
+    skills_context = Riffer::Skills::Context.new(
+      backend: backend,
+      skills: skills,
+      adapter: adapter_class.new(skill_activate_tool: skill_activate_tool_class)
+    )
     ctx = (context || {}).merge(skills: skills_context)
 
     activate = self.class.skills.activate
@@ -802,7 +829,10 @@ class Riffer::Agent
   #--
   #: () -> Riffer::Messages::Assistant?
   def extract_final_response
+    # TODO: Replace with rfind when minimum Ruby is 4.0+
+    # rubocop:disable Style/ReverseFind
     @messages.reverse.find { |msg| msg.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
+    # rubocop:enable Style/ReverseFind
   end
 
   #--

data/lib/riffer/config.rb

@@ -22,6 +22,57 @@ class Riffer::Config
   OpenAI = Struct.new(:api_key, keyword_init: true)
   Evals = Struct.new(:judge_model, keyword_init: true)
 
+  # Skills-related global configuration.
+  #
+  # See <tt>Riffer.config.skills.default_activate_tool</tt> and
+  # <tt>Riffer.config.skills.default_backend</tt>.
+  class Skills
+    # Default skill activation tool class.
+    #
+    # The tool class the LLM calls to activate a skill. Defaults to
+    # <tt>Riffer::Skills::ActivateTool</tt>. Per-agent override is available
+    # via <tt>skills do; activate_tool ...; end</tt>.
+    attr_reader :default_activate_tool #: singleton(Riffer::Tool)
+
+    # Default skills backend.
+    #
+    # Used by agents that declare a +skills+ block without specifying a
+    # backend. Accepts a Riffer::Skills::Backend instance or a Proc.
+    # Defaults to +nil+ (no global default).
+    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)?
+
+    #--
+    #: () -> void
+    def initialize
+      @default_activate_tool = Riffer::Skills::ActivateTool
+      @default_backend = nil
+    end
+
+    # Sets the default skill activation tool class.
+    #
+    # Raises +Riffer::ArgumentError+ if the value is not a Riffer::Tool subclass.
+    #
+    #--
+    #: (singleton(Riffer::Tool)) -> void
+    def default_activate_tool=(value)
+      raise Riffer::ArgumentError, "default_activate_tool must be a Riffer::Tool subclass" unless value.is_a?(Class) && value < Riffer::Tool
+      @default_activate_tool = value
+    end
+
+    # Sets the default skills backend.
+    #
+    # Raises +Riffer::ArgumentError+ if the value is not a
+    # Riffer::Skills::Backend instance, a Proc, or +nil+.
+    #
+    #--
+    #: ((Riffer::Skills::Backend | Proc)?) -> void
+    def default_backend=(value)
+      valid = value.nil? || value.is_a?(Riffer::Skills::Backend) || value.is_a?(Proc)
+      raise Riffer::ArgumentError, "default_backend must be a Riffer::Skills::Backend instance, Proc, or nil" unless valid
+      @default_backend = value
+    end
+  end
+
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
   # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
@@ -61,6 +112,10 @@ class Riffer::Config
     @tool_runtime = value
   end
 
+  # Skills-related global configuration. Returns a Riffer::Config::Skills
+  # object — see <tt>Riffer.config.skills.default_activate_tool</tt>.
+  attr_reader :skills #: Riffer::Config::Skills
+
   # Strategy for auto-generating message ids. One of +:none+ (default, no id),
   # +:uuid+ (UUIDv4), or +:uuidv7+ (time-ordered UUIDv7).
   #
@@ -94,6 +149,7 @@ class Riffer::Config
     @openai = OpenAI.new
     @evals = Evals.new
     @tool_runtime = Riffer::ToolRuntime::Inline.new
+    @skills = Skills.new
     @message_id_strategy = :none
   end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -9,6 +9,24 @@ require "base64"
 #
 # See https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
+  # Matches Anthropic models on Bedrock: bare ids like
+  # +anthropic.claude-3-5-sonnet-20241022-v2:0+ and cross-region prefixed
+  # ids like +us.anthropic.claude-sonnet-4-6+.
+  ANTHROPIC_MODEL_PATTERN = /(?:^|\.)anthropic\./ #: Regexp
+
+  # Returns the preferred skill adapter for the given Bedrock model.
+  #
+  # Bedrock hosts models from multiple vendors. Anthropic models prefer
+  # XML-rendered catalogs; everything else falls back to the default
+  # Markdown adapter.
+  #
+  #--
+  #: (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter(model = nil)
+    return Riffer::Skills::XmlAdapter if model && ANTHROPIC_MODEL_PATTERN.match?(model)
+    Riffer::Skills::MarkdownAdapter
+  end
+
   # Initializes the Amazon Bedrock provider.
   #
   #--

data/lib/riffer/providers/anthropic.rb

@@ -12,8 +12,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   # Returns the XML skill adapter for Anthropic/Claude.
   #
   #--
-  #: () -> singleton(Riffer::Skills::Adapter)
-  def self.skills_adapter
+  #: (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter(model = nil)
     Riffer::Skills::XmlAdapter
   end
 

data/lib/riffer/providers/base.rb

@@ -24,11 +24,15 @@ class Riffer::Providers::Base
 
   # Returns the preferred skill adapter for this provider.
   #
-  # Override in subclasses for provider-specific formats.
+  # Override in subclasses for provider-specific formats. Subclasses may
+  # introspect +model+ (the resolved model identifier, e.g. the part after
+  # +provider/+) to pick an adapter that matches the underlying model
+  # family — useful for proxy providers like Amazon Bedrock that host
+  # models from multiple vendors.
   #
   #--
-  #: () -> singleton(Riffer::Skills::Adapter)
-  def self.skills_adapter
+  #: (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter(model = nil)
     Riffer::Skills::MarkdownAdapter
   end
 

data/lib/riffer/providers/mock.rb

@@ -5,6 +5,21 @@
 #
 # No external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
+  # Returns the preferred skill adapter for the given mock model.
+  #
+  # Mock is used to stand in for any real provider in tests, so the model
+  # string itself is the only signal we have. When the model name contains
+  # +claude+ (e.g. +mock/claude-sonnet-4-6+), pick the XML adapter to
+  # mirror what a real Claude-backed provider would do; otherwise fall
+  # back to Markdown.
+  #
+  #--
+  #: (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter(model = nil)
+    return Riffer::Skills::XmlAdapter if model&.include?("claude")
+    Riffer::Skills::MarkdownAdapter
+  end
+
   # Array of recorded method calls for assertions.
   attr_reader :calls #: Array[Hash[Symbol, untyped]]
 

data/lib/riffer/skills/adapter.rb

@@ -3,16 +3,31 @@
 
 # Base class defining the interface for skill adapters.
 #
-# A skill adapter encapsulates the provider-specific behavior for skills:
-# how the skill catalog is rendered in the system prompt, and which tool
-# the LLM calls to activate a skill.
+# A skill adapter encapsulates the provider-specific catalog rendering for
+# skills — how the available-skills section appears in the system prompt.
 #
-# Subclass and override +render_catalog+ and optionally +activate_tool+
-# to customize behavior.
+# Subclass and override +render_catalog+. The activation tool is set at
+# construction time and is exposed via +#skill_activate_tool+ for use in
+# rendered output.
 #
 # See Riffer::Skills::MarkdownAdapter for the default implementation.
 # See Riffer::Skills::XmlAdapter for the Anthropic/Claude variant.
 class Riffer::Skills::Adapter
+  # The activation tool class for this adapter.
+  attr_reader :skill_activate_tool #: singleton(Riffer::Tool)
+
+  # Creates a new adapter.
+  #
+  # [skill_activate_tool] the activation tool class — referenced by name
+  #                       in the rendered catalog so the LLM knows which
+  #                       tool to call.
+  #
+  #--
+  #: (skill_activate_tool: singleton(Riffer::Tool)) -> void
+  def initialize(skill_activate_tool:)
+    @skill_activate_tool = skill_activate_tool
+  end
+
   # Renders a skill catalog section for the system prompt.
   #
   # [skills] array of Frontmatter objects to render.
@@ -24,14 +39,4 @@ class Riffer::Skills::Adapter
   def render_catalog(skills)
     raise NotImplementedError, "#{self.class} must implement #render_catalog"
   end
-
-  # Returns the tool class used to activate skills.
-  #
-  # Override to provide a custom activation tool.
-  #
-  #--
-  #: () -> singleton(Riffer::Tool)
-  def activate_tool
-    Riffer::Skills::ActivateTool
-  end
 end

data/lib/riffer/skills/config.rb

@@ -19,6 +19,7 @@ class Riffer::Skills::Config
     @backend = nil
     @adapter = nil
     @activate = nil
+    @activate_tool = nil
   end
 
   # Gets or sets the skills backend.
@@ -59,4 +60,21 @@ class Riffer::Skills::Config
     return @activate if value.nil?
     @activate = value
   end
+
+  # Gets or sets the per-agent override for the skill activation tool class.
+  #
+  # Returns the configured override when set, or +nil+ when unset. The
+  # global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
+  # is applied by the agent at resolution time (see
+  # Riffer::Agent.resolved_tool_classes), not by this getter.
+  #
+  # The override must be a subclass of Riffer::Tool.
+  #
+  #--
+  #: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
+  def activate_tool(value = nil)
+    return @activate_tool if value.nil?
+    raise Riffer::ArgumentError, "activate_tool must be a Riffer::Tool subclass" unless value.is_a?(Class) && value < Riffer::Tool
+    @activate_tool = value
+  end
 end

data/lib/riffer/skills/context.rb

@@ -24,7 +24,8 @@ class Riffer::Skills::Context
   #
   # [backend] the skills backend for reading skill bodies.
   # [skills] skill catalog indexed by name.
-  # [adapter] the adapter used to render skill content.
+  # [adapter] the adapter used to render skill content. The adapter
+  #           carries the activation tool class via its initializer.
   #
   #--
   #: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void

data/lib/riffer/skills/markdown_adapter.rb

@@ -18,7 +18,7 @@ class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
     lines = []
     lines << "## Available Skills"
     lines << ""
-    lines << "When a user's request matches a skill description below, call the `#{activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
+    lines << "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."
     lines << ""
     skills.each do |skill|
       lines << "- **#{skill.name}**: #{skill.description}"

data/lib/riffer/skills/xml_adapter.rb

@@ -17,7 +17,7 @@ class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
     lines = []
-    lines << "When a user's request matches a skill description below, call the `#{activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
+    lines << "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."
     lines << ""
     lines << "<available_skills>"
     skills.each do |skill|

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.24.2" #: String
+  VERSION = "0.26.0" #: String
 end

data/sig/generated/riffer/agent.rbs

@@ -88,6 +88,31 @@ class Riffer::Agent
   # : (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
   def self.uses_tools: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
 
+  # Returns the tool classes the LLM should see for this agent.
+  #
+  # Class-level companion to the instance #resolved_tools. Resolves the
+  # Proc form of +uses_tools+ and appends the skill activation tool when
+  # a +skills+ block is configured. Does not read the skills backend —
+  # the LLM-facing tool schema reflects class-level intent, not the
+  # runtime state of any backend.
+  #
+  # When +uses_tools+ is a Proc, +context+ is forwarded to it.
+  #
+  # The activation tool class is resolved from the agent's
+  # <tt>skills do; activate_tool ...; end</tt> override when set, otherwise
+  # from <tt>Riffer.config.skills.default_activate_tool</tt>.
+  #
+  # Raises Riffer::ArgumentError on tool name conflicts with the skill
+  # activation tool.
+  #
+  # --
+  # : (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+  def self.resolved_tool_classes: (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+
+  # --
+  # : (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+  def self.resolve_uses_tools_config: (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
+
   # Gets or sets the tool runtime for this agent.
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,

data/sig/generated/riffer/config.rbs

@@ -63,6 +63,47 @@ class Riffer::Config
                 | ({ ?judge_model: untyped }) -> instance
   end
 
+  # Skills-related global configuration.
+  #
+  # See <tt>Riffer.config.skills.default_activate_tool</tt> and
+  # <tt>Riffer.config.skills.default_backend</tt>.
+  class Skills
+    # Default skill activation tool class.
+    #
+    # The tool class the LLM calls to activate a skill. Defaults to
+    # <tt>Riffer::Skills::ActivateTool</tt>. Per-agent override is available
+    # via <tt>skills do; activate_tool ...; end</tt>.
+    attr_reader default_activate_tool: singleton(Riffer::Tool)
+
+    # Default skills backend.
+    #
+    # Used by agents that declare a +skills+ block without specifying a
+    # backend. Accepts a Riffer::Skills::Backend instance or a Proc.
+    # Defaults to +nil+ (no global default).
+    attr_reader default_backend: (Riffer::Skills::Backend | Proc)?
+
+    # --
+    # : () -> void
+    def initialize: () -> void
+
+    # Sets the default skill activation tool class.
+    #
+    # Raises +Riffer::ArgumentError+ if the value is not a Riffer::Tool subclass.
+    #
+    # --
+    # : (singleton(Riffer::Tool)) -> void
+    def default_activate_tool=: (singleton(Riffer::Tool)) -> void
+
+    # Sets the default skills backend.
+    #
+    # Raises +Riffer::ArgumentError+ if the value is not a
+    # Riffer::Skills::Backend instance, a Proc, or +nil+.
+    #
+    # --
+    # : ((Riffer::Skills::Backend | Proc)?) -> void
+    def default_backend=: ((Riffer::Skills::Backend | Proc)?) -> void
+  end
+
   VALID_MESSAGE_ID_STRATEGIES: untyped
 
   # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
@@ -98,6 +139,10 @@ class Riffer::Config
   # : ((singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)) -> void
   def tool_runtime=: (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc) -> void
 
+  # Skills-related global configuration. Returns a Riffer::Config::Skills
+  # object — see <tt>Riffer.config.skills.default_activate_tool</tt>.
+  attr_reader skills: Riffer::Config::Skills
+
   # Strategy for auto-generating message ids. One of +:none+ (default, no id),
   # +:uuid+ (UUIDv4), or +:uuidv7+ (time-ordered UUIDv7).
   #

data/sig/generated/riffer/providers/amazon_bedrock.rbs

@@ -6,6 +6,21 @@
 #
 # See https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
+  # Matches Anthropic models on Bedrock: bare ids like
+  # +anthropic.claude-3-5-sonnet-20241022-v2:0+ and cross-region prefixed
+  # ids like +us.anthropic.claude-sonnet-4-6+.
+  ANTHROPIC_MODEL_PATTERN: Regexp
+
+  # Returns the preferred skill adapter for the given Bedrock model.
+  #
+  # Bedrock hosts models from multiple vendors. Anthropic models prefer
+  # XML-rendered catalogs; everything else falls back to the default
+  # Markdown adapter.
+  #
+  # --
+  # : (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
+
   # Initializes the Amazon Bedrock provider.
   #
   # --

data/sig/generated/riffer/providers/anthropic.rbs

@@ -11,8 +11,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   # Returns the XML skill adapter for Anthropic/Claude.
   #
   # --
-  # : () -> singleton(Riffer::Skills::Adapter)
-  def self.skills_adapter: () -> singleton(Riffer::Skills::Adapter)
+  # : (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
   # Initializes the Anthropic provider.
   #

data/sig/generated/riffer/providers/base.rbs

@@ -22,11 +22,15 @@ class Riffer::Providers::Base
 
   # Returns the preferred skill adapter for this provider.
   #
-  # Override in subclasses for provider-specific formats.
+  # Override in subclasses for provider-specific formats. Subclasses may
+  # introspect +model+ (the resolved model identifier, e.g. the part after
+  # +provider/+) to pick an adapter that matches the underlying model
+  # family — useful for proxy providers like Amazon Bedrock that host
+  # models from multiple vendors.
   #
   # --
-  # : () -> singleton(Riffer::Skills::Adapter)
-  def self.skills_adapter: () -> singleton(Riffer::Skills::Adapter)
+  # : (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
   # Generates text using the provider.
   #

data/sig/generated/riffer/providers/mock.rbs

@@ -4,6 +4,18 @@
 #
 # No external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
+  # Returns the preferred skill adapter for the given mock model.
+  #
+  # Mock is used to stand in for any real provider in tests, so the model
+  # string itself is the only signal we have. When the model name contains
+  # +claude+ (e.g. +mock/claude-sonnet-4-6+), pick the XML adapter to
+  # mirror what a real Claude-backed provider would do; otherwise fall
+  # back to Markdown.
+  #
+  # --
+  # : (?String?) -> singleton(Riffer::Skills::Adapter)
+  def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
+
   # Array of recorded method calls for assertions.
   attr_reader calls: Array[Hash[Symbol, untyped]]
 

data/sig/generated/riffer/skills/adapter.rbs

@@ -2,16 +2,29 @@
 
 # Base class defining the interface for skill adapters.
 #
-# A skill adapter encapsulates the provider-specific behavior for skills:
-# how the skill catalog is rendered in the system prompt, and which tool
-# the LLM calls to activate a skill.
+# A skill adapter encapsulates the provider-specific catalog rendering for
+# skills — how the available-skills section appears in the system prompt.
 #
-# Subclass and override +render_catalog+ and optionally +activate_tool+
-# to customize behavior.
+# Subclass and override +render_catalog+. The activation tool is set at
+# construction time and is exposed via +#skill_activate_tool+ for use in
+# rendered output.
 #
 # See Riffer::Skills::MarkdownAdapter for the default implementation.
 # See Riffer::Skills::XmlAdapter for the Anthropic/Claude variant.
 class Riffer::Skills::Adapter
+  # The activation tool class for this adapter.
+  attr_reader skill_activate_tool: singleton(Riffer::Tool)
+
+  # Creates a new adapter.
+  #
+  # [skill_activate_tool] the activation tool class — referenced by name
+  #                       in the rendered catalog so the LLM knows which
+  #                       tool to call.
+  #
+  # --
+  # : (skill_activate_tool: singleton(Riffer::Tool)) -> void
+  def initialize: (skill_activate_tool: singleton(Riffer::Tool)) -> void
+
   # Renders a skill catalog section for the system prompt.
   #
   # [skills] array of Frontmatter objects to render.
@@ -21,12 +34,4 @@ class Riffer::Skills::Adapter
   # --
   # : (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog: (Array[Riffer::Skills::Frontmatter]) -> String
-
-  # Returns the tool class used to activate skills.
-  #
-  # Override to provide a custom activation tool.
-  #
-  # --
-  # : () -> singleton(Riffer::Tool)
-  def activate_tool: () -> singleton(Riffer::Tool)
 end

data/sig/generated/riffer/skills/config.rbs

@@ -45,4 +45,17 @@ class Riffer::Skills::Config
   # --
   # : (?(Array[String] | Proc)?) -> (Array[String] | Proc)?
   def activate: (?(Array[String] | Proc)?) -> (Array[String] | Proc)?
+
+  # Gets or sets the per-agent override for the skill activation tool class.
+  #
+  # Returns the configured override when set, or +nil+ when unset. The
+  # global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
+  # is applied by the agent at resolution time (see
+  # Riffer::Agent.resolved_tool_classes), not by this getter.
+  #
+  # The override must be a subclass of Riffer::Tool.
+  #
+  # --
+  # : (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
+  def activate_tool: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
 end

data/sig/generated/riffer/skills/context.rbs

@@ -23,7 +23,8 @@ class Riffer::Skills::Context
   #
   # [backend] the skills backend for reading skill bodies.
   # [skills] skill catalog indexed by name.
-  # [adapter] the adapter used to render skill content.
+  # [adapter] the adapter used to render skill content. The adapter
+  #           carries the activation tool class via its initializer.
   #
   # --
   # : (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.24.2
+  version: 0.26.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.35.0
+        version: 1.36.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.35.0
+        version: 1.36.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -221,6 +221,7 @@ files:
 - ".agents/rbs-inline.md"
 - ".agents/rdoc.md"
 - ".agents/testing.md"
+- ".bundle/config"
 - ".release-please-config.json"
 - ".release-please-manifest.json"
 - ".ruby-version"
@@ -449,7 +450,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: The all-in-one Ruby framework for building AI-powered applications and agents.
 test_files: []