agent-harness 0.17.2 → 0.17.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15e1c2315d17c1250d547c58c3f04b2d9daf491a3b56fcb23e58b824a68e6a1
-  data.tar.gz: 42bd06fe77703e25a8c61ec8667de90d1b3e84e483d1651b36c0e0013cdc610a
+  metadata.gz: 5eee3cd4f4e77fe648ed70a6c31c29af4959b90d7fb848534ecdf75558811d0f
+  data.tar.gz: 8eca8a991857a8518bc9b192d78984bb459470725da9727ac830fd42eaf2a91b
 SHA512:
-  metadata.gz: ba35bf2c9b5e6de554664cfbf1dacbb70d0d9ceb017c6fc1be8bb8c63b73ab295b1d01e28de3650ac74d08d4908650dd11dfc267099482e2ea933a24ae33d5e9
-  data.tar.gz: c8fcf04ce5c2ab05c2007fc6642457adbe2bafb48cc11e0290b97834d269c4fbe8be411d9227aceef8315975d97a9ff38d8beae270d34365f07f2e851c883ddb
+  metadata.gz: b3d2b6cd29f4b9607b52b935d323db5217514c3e32b213f222c3fd2b4731e2407315854bdbbdd2e4857c84302b4ae21e844e611bff11e24f051a28f035da93db
+  data.tar.gz: 979df7fc6616509e14593d0fee2f189ec4a5d7b3c34d071fe755fab31115bf932f90484f3e1483dbabad956383c8bc1528174ec08791bc32a186d814295d87ef

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.17.2"
+  ".": "0.17.3"
 }

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.17.3](https://github.com/viamin/agent-harness/compare/agent-harness/v0.17.2...agent-harness/v0.17.3) (2026-05-06)
+
+
+### Bug Fixes
+
+* 161: Support provider-agnostic skills system ([#204](https://github.com/viamin/agent-harness/issues/204)) ([20a6ed5](https://github.com/viamin/agent-harness/commit/20a6ed5a8e6701ad7730d88b8037145d86b39c37))
+
 ## [0.17.2](https://github.com/viamin/agent-harness/compare/agent-harness/v0.17.1...agent-harness/v0.17.2) (2026-05-05)
 
 

data/lib/agent_harness/configuration.rb

@@ -420,7 +420,10 @@ module AgentHarness
     end
 
     def mapping_for(provider)
-      deep_dup(@provider_mappings[provider.to_sym])
+      provider_key = provider.to_sym
+      mapping = @provider_mappings[provider_key]
+      mapping ||= @provider_mappings[normalize_provider_family(provider_key)]
+      deep_dup(mapping)
     end
 
     def to_h
@@ -429,6 +432,15 @@ module AgentHarness
 
     private
 
+    def normalize_provider_family(provider)
+      case provider
+      when :claude then :anthropic
+      when :gemini then :google
+      when :cursor, :github_copilot, :codex, :opencode, :openai_compatible then :openai
+      else provider
+      end
+    end
+
     def deep_dup(value)
       case value
       when Array

data/lib/agent_harness/provider_runtime.rb

@@ -174,6 +174,43 @@ module AgentHarness
         chat_tools.nil?
     end
 
+    def to_h
+      {
+        model: model,
+        base_url: base_url,
+        api_provider: api_provider,
+        env: env.empty? ? nil : env.dup,
+        flags: flags.empty? ? nil : flags.dup,
+        unset_env: unset_env.empty? ? nil : unset_env.dup,
+        metadata: metadata.empty? ? nil : metadata.dup,
+        chat_base_url: chat_base_url,
+        chat_model: chat_model,
+        chat_api_key: chat_api_key,
+        chat_max_tokens: chat_max_tokens,
+        chat_tools: chat_tools&.dup
+      }.compact
+    end
+
+    def merge(other)
+      other_runtime = ProviderRuntime.wrap(other)
+      return self if other_runtime.nil? || other_runtime.empty?
+
+      ProviderRuntime.new(
+        model: other_runtime.model || model,
+        base_url: other_runtime.base_url || base_url,
+        api_provider: other_runtime.api_provider || api_provider,
+        env: env.merge(other_runtime.env),
+        flags: flags + other_runtime.flags,
+        unset_env: unset_env + other_runtime.unset_env,
+        metadata: metadata.merge(other_runtime.metadata),
+        chat_base_url: other_runtime.chat_base_url || chat_base_url,
+        chat_model: other_runtime.chat_model || chat_model,
+        chat_api_key: other_runtime.chat_api_key || chat_api_key,
+        chat_max_tokens: other_runtime.chat_max_tokens.nil? ? chat_max_tokens : other_runtime.chat_max_tokens,
+        chat_tools: merge_chat_tools(chat_tools, other_runtime.chat_tools)
+      )
+    end
+
     private_class_method def self.hash_value(hash, key)
       sym_value = hash[key]
       str_value = hash[key.to_s]
@@ -185,6 +222,27 @@ module AgentHarness
 
     private
 
+    def merge_chat_tools(base_tools, override_tools)
+      return override_tools unless base_tools
+      return base_tools unless override_tools
+
+      merged = base_tools + override_tools
+      names = merged.map { |t| tool_name(t) }.compact
+      duplicates = names.group_by { |n| n }.select { |_, v| v.size > 1 }.keys
+      unless duplicates.empty?
+        raise AgentHarness::ConfigurationError,
+          "Duplicate chat tool names across merged runtimes: #{duplicates.join(", ")}"
+      end
+      merged
+    end
+
+    def tool_name(tool)
+      return unless tool.is_a?(Hash)
+
+      tool[:name] || tool["name"] ||
+        tool.dig(:function, :name) || tool.dig("function", "name")
+    end
+
     def validate_optional_string!(name, value)
       return if value.nil?
       return if value.is_a?(String)

data/lib/agent_harness/providers/adapter.rb

@@ -950,6 +950,15 @@ module AgentHarness
         false
       end
 
+      # Check if provider message mode can inject available tool definitions
+      # through the +tools:+ option. Providers that use +tools:+ strictly for
+      # disallow lists should leave this as +false+.
+      #
+      # @return [Boolean] true if skill tools can be merged into message mode
+      def supports_message_tool_injection?
+        false
+      end
+
       # Check if provider supports text-only mode via direct HTTP transport.
       #
       # Providers that return +true+ will route +mode: :text+ requests

data/lib/agent_harness/providers/aider.rb

@@ -211,6 +211,9 @@ module AgentHarness
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         runtime = options[:provider_runtime]
 
         options = normalize_mcp_servers(options)
@@ -255,7 +258,7 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -267,6 +270,9 @@ module AgentHarness
         log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
 
@@ -277,7 +283,7 @@ module AgentHarness
           env: build_env(options),
           preparation: build_execution_preparation(options)
         }
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)

data/lib/agent_harness/providers/anthropic.rb

@@ -378,7 +378,10 @@ module AgentHarness
 
       def send_message(prompt:, **options)
         if options[:mode] == :text
-          return send_text_message(prompt, **options.except(:mode))
+          options = normalize_provider_runtime(options)
+          skill_context = resolve_skills(options)
+          prompt = apply_skills_to_prompt(prompt, skill_context)
+          return send_text_message(prompt, **skill_context[:options].except(:mode, :skills))
         end
 
         super

data/lib/agent_harness/providers/base.rb

@@ -129,6 +129,9 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
 
         # Capture execution options (callbacks, observer) before extensions
         # processing deep-dups the options hash, which would replace identity-
@@ -191,7 +194,8 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
-      rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ExtensionCompatibilityError, ConfigurationError, McpConfigurationError, McpUnsupportedError,
+        McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -221,6 +225,9 @@ module AgentHarness
         end
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
 
         extension_context = apply_extensions_to_prompt(prompt, options)
         prompt = extension_context.prompt
@@ -236,7 +243,8 @@ module AgentHarness
           env: build_env(options),
           preparation: build_execution_preparation(options)
         }
-      rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ExtensionCompatibilityError, ConfigurationError, McpConfigurationError, McpUnsupportedError,
+        McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -276,20 +284,30 @@ module AgentHarness
         end
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options, mode: :chat)
+        options = skill_context[:options]
         options = normalize_sub_agent(options)
         runtime = options[:provider_runtime]
         conversation ||= messages
         raise ArgumentError, "conversation or messages is required" unless conversation
-        tools = runtime.chat_tools if tools.nil? && runtime&.chat_tools
+        use_runtime_chat_tools = tools.nil?
+        tools = runtime.chat_tools if use_runtime_chat_tools && runtime&.chat_tools
 
         transport = resolve_chat_transport(options)
         messages = format_messages_for_transport(conversation, transport)
+        messages = apply_skills_to_messages(messages, skill_context)
+        skill_tools = if use_runtime_chat_tools
+          skill_context[:tools]
+        else
+          merge_skill_chat_tools(skill_context[:tools], skill_context[:runtime_tools])
+        end
+        tools = merge_skill_chat_tools(tools, skill_tools)
         extension_context = apply_extensions_to_chat(messages, tools, options)
         messages = extension_context.messages
         tools = extension_context.tools
         options = extension_context.options
         messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
-        validate_chat_mcp_servers!(options[:mcp_servers])
+        validate_chat_mcp_servers!(options)
         transport_opts = chat_transport_options(runtime, options)
         transport_opts[:on_chat_chunk] = on_chat_chunk if on_chat_chunk
         transport_opts[:observer] = observer if observer
@@ -308,7 +326,7 @@ module AgentHarness
         log_debug("send_chat_message_complete", duration: response.duration, tokens: response.tokens)
 
         response
-      rescue ExtensionCompatibilityError, ProviderError, AuthenticationError, RateLimitError, TimeoutError
+      rescue ExtensionCompatibilityError, ConfigurationError, ProviderError, AuthenticationError, RateLimitError, TimeoutError
         raise
       rescue => e
         last_msg = conversation&.last || messages&.last
@@ -525,22 +543,49 @@ module AgentHarness
         options.merge(provider_runtime: ProviderRuntime.wrap(raw))
       end
 
+      def resolve_skills(options, mode: :message)
+        skill_refs = options[:skills]
+        cwd = options.fetch(:cwd, Dir.pwd)
+        home = options.fetch(:home, Dir.home)
+        skills = Skills.resolve_all(skill_refs, cwd: cwd, home: home)
+        return {skills: [], options: options, instructions: nil, tools: [], runtime_tools: []} if skills.empty?
+
+        skill_runtime = skills.map { |skill| ProviderRuntime.wrap(skill.provider_override_for(self.class.provider_name)) }
+          .compact
+          .reduce(nil) { |merged, sr| merged ? merged.merge(sr) : sr }
+
+        runtime = skill_runtime&.merge(options[:provider_runtime]) || options[:provider_runtime]
+        merged_options = options.merge(provider_runtime: runtime)
+        merged_options = merge_skill_message_tools(merged_options, skills) if mode == :message
+        merged_options = merge_skill_mcp_servers(merged_options, skills)
+
+        {
+          skills: skills,
+          options: merged_options,
+          instructions: skills.map(&:instructions).join("\n\n"),
+          tools: resolve_skill_chat_tools(skills),
+          runtime_tools: Array(skill_runtime&.chat_tools)
+        }
+      end
+
       def normalize_mcp_servers(options)
-        if options.key?(:mcp_servers)
-          servers = options[:mcp_servers]
+        base_servers = if options.key?(:mcp_servers)
+          options[:mcp_servers]
         else
           # Configuration stores mcp_servers as a Hash keyed by name; extract values.
           config_servers = @configuration.mcp_servers
-          servers = config_servers.is_a?(Hash) ? config_servers.values : config_servers
+          config_servers.is_a?(Hash) ? config_servers.values : config_servers
         end
-        return options if servers.nil?
+        skill_servers = Array(options[:skill_mcp_servers])
+        return options.except(:skill_mcp_servers) if base_servers.nil? && skill_servers.empty?
 
-        unless servers.is_a?(Array)
+        unless base_servers.nil? || base_servers.is_a?(Array)
           raise McpConfigurationError,
-            "mcp_servers must be an Array of Hash or McpServer, got #{servers.class}"
+            "mcp_servers must be an Array of Hash or McpServer, got #{base_servers.class}"
         end
 
-        return options if servers.empty?
+        servers = Array(base_servers) + skill_servers
+        return options.except(:skill_mcp_servers) if servers.empty?
 
         normalized = servers.map do |server|
           if server.is_a?(McpServer)
@@ -560,7 +605,7 @@ module AgentHarness
             "Duplicate MCP server names detected: #{duplicate_names.join(", ")}"
         end
 
-        options.merge(mcp_servers: normalized)
+        options.except(:skill_mcp_servers).merge(mcp_servers: normalized)
       end
 
       def normalize_sub_agent(options)
@@ -584,6 +629,28 @@ module AgentHarness
         [translated_sub_agent[:runtime_instructions], "User task:\n#{prompt}"].join("\n\n")
       end
 
+      def apply_skills_to_prompt(prompt, skill_context)
+        instructions = skill_context[:instructions]
+        return prompt if instructions.nil? || instructions.empty?
+
+        [instructions, prompt].join("\n\n")
+      end
+
+      def apply_skills_to_messages(messages, skill_context)
+        instructions = skill_context[:instructions]
+        return messages if instructions.nil? || instructions.empty?
+
+        # Prepend skill instructions to the first system message if one exists,
+        # rather than inserting a separate system turn that could be overridden.
+        if messages.any? && messages.first[:role] == "system"
+          merged = messages.dup
+          merged[0] = merged[0].merge(content: prepend_text_to_message_content(merged[0][:content], instructions))
+          merged
+        else
+          [{role: "system", content: instructions}] + messages
+        end
+      end
+
       def apply_sub_agent_to_messages(messages, translated_sub_agent)
         return messages unless translated_sub_agent
 
@@ -659,8 +726,12 @@ module AgentHarness
         end
       end
 
-      def validate_chat_mcp_servers!(mcp_servers)
-        return if mcp_servers.nil? || mcp_servers.empty?
+      def validate_chat_mcp_servers!(options)
+        # Chat mode only needs to reject MCP servers introduced by the
+        # current request. Global configuration may still define default MCP
+        # servers for non-chat flows and should not make every chat call fail.
+        mcp_servers = Array(options[:mcp_servers]) + Array(options[:skill_mcp_servers])
+        return if mcp_servers.empty?
 
         # Chat transports do not support request-scoped MCP servers.
         # Raise early so extensions with MCP requirements are not silently ignored.
@@ -717,6 +788,149 @@ module AgentHarness
         merged
       end
 
+      def merge_skill_message_tools(options, skills)
+        return options if skills.empty?
+        return options if options[:tools] == :none
+
+        skill_tools = skills.flat_map { |skill| skill.tools.map { |tool| resolve_skill_message_tool(tool) } }.compact
+        return options if skill_tools.empty?
+
+        unless supports_message_tool_injection?
+          tool_names = skill_tools.map { |t| t.is_a?(Hash) ? extract_tool_name(t) : t }.compact
+          skill_names = skills.select { |s| s.tools.any? }.map(&:name)
+          raise ConfigurationError,
+            "Skills #{skill_names.join(", ")} define message-mode tools (#{tool_names.join(", ")}) " \
+            "but provider #{self.class.provider_name} does not support message-mode tool injection"
+        end
+
+        current_tools = options[:tools]
+        merged_tools = Array(current_tools) + skill_tools
+        duplicates = merged_tools.group_by(&:itself).select { |_, entries| entries.size > 1 }.keys
+        unless duplicates.empty?
+          raise ConfigurationError, "Tool name conflict between explicit and skill tools: #{duplicates.join(", ")}"
+        end
+
+        options.merge(tools: merged_tools)
+      end
+
+      def merge_skill_mcp_servers(options, skills)
+        skill_servers = skills.flat_map do |skill|
+          skill.mcp_servers.map { |server| [skill.name, server] }
+        end
+        return options if skill_servers.empty?
+
+        existing_servers = normalized_mcp_server_sources(options)
+        duplicates = duplicate_skill_mcp_server_names(existing_servers, skill_servers)
+        unless duplicates.empty?
+          conflicts = duplicates.map do |name, owners|
+            formatted_owners = owners.map { |owner| (owner == :explicit) ? "explicit" : "skill: #{owner}" }.join(", ")
+            "#{name} (#{formatted_owners})"
+          end
+          raise ConfigurationError,
+            "MCP server name conflict across explicit and skill servers: #{conflicts.join(", ")}"
+        end
+
+        options.merge(skill_mcp_servers: deep_dup(skill_servers.map(&:last)))
+      end
+
+      def resolve_skill_chat_tools(skills)
+        skills.flat_map do |skill|
+          skill.tools.map { |tool| normalize_skill_chat_tool_for_provider(resolve_skill_tool_mapping(tool)) }
+        end
+      end
+
+      def merge_skill_chat_tools(tools, skill_tools)
+        return tools if skill_tools.empty?
+
+        merged = Array(tools) + skill_tools
+        names = merged.map { |tool| extract_tool_name(tool) }.compact
+        duplicates = names.group_by { |name| name }.select { |_, entries| entries.size > 1 }.keys
+        unless duplicates.empty?
+          raise ConfigurationError, "Tool name conflict between explicit and skill tools: #{duplicates.join(", ")}"
+        end
+
+        merged
+      end
+
+      def resolve_skill_message_tool(tool)
+        resolved = resolve_skill_tool_mapping(tool)
+        return resolved if resolved.is_a?(String)
+        return extract_tool_name(resolved) if resolved.is_a?(Hash)
+
+        raise ConfigurationError, "Unsupported skill tool mapping for message mode: #{resolved.inspect}"
+      end
+
+      def normalize_skill_chat_tool_for_provider(tool)
+        normalized_tool = tool.is_a?(Hash) ? tool : {name: tool.to_s}
+        normalize_extension_tool_for_provider(normalized_tool)
+      end
+
+      def duplicate_skill_mcp_server_names(existing_servers, skill_servers)
+        owners_by_name = Hash.new { |hash, key| hash[key] = [] }
+        existing_servers.each do |server|
+          name = server_name(server)
+          owners_by_name[name] << :explicit if name
+        end
+
+        skill_servers.each do |(skill_name, server)|
+          name = server_name(server)
+          owners_by_name[name] << skill_name if name
+        end
+
+        owners_by_name.each_with_object({}) do |(name, owners), duplicates|
+          duplicates[name] = owners if owners.uniq.size > 1
+        end
+      end
+
+      def normalized_mcp_server_sources(options)
+        if options.key?(:mcp_servers)
+          Array(options[:mcp_servers])
+        else
+          config_servers = @configuration.mcp_servers
+          config_servers = config_servers.values if config_servers.is_a?(Hash)
+          Array(config_servers)
+        end
+      end
+
+      def server_name(server)
+        if server.is_a?(McpServer)
+          server.name
+        else
+          server[:name] || server["name"]
+        end
+      end
+
+      def resolve_skill_tool_mapping(tool)
+        case tool
+        when Symbol, String
+          if @configuration.tool_registry.registered?(tool)
+            mapping = @configuration.tool_registry.fetch(tool).mapping_for(self.class.provider_name)
+            mapping.nil? ? tool.to_s : mapping
+          else
+            tool.to_s
+          end
+        when Hash
+          deep_dup(tool)
+        else
+          raise ConfigurationError, "Unsupported tool reference #{tool.inspect} in skill definition"
+        end
+      end
+
+      def prepend_text_to_message_content(content, text)
+        case content
+        when nil
+          text
+        when String
+          "#{text}\n\n#{content}"
+        when Array
+          [{type: "text", text: "#{text}\n\n"}] + deep_dup(content)
+        when Hash
+          [{type: "text", text: "#{text}\n\n"}, deep_dup(content)]
+        else
+          raise ConfigurationError, "Unsupported system message content type for skill instructions: #{content.class}"
+        end
+      end
+
       def extract_tool_name(tool)
         tool[:name] || tool["name"] ||
           tool.dig(:function, :name) || tool.dig(:function, "name") ||

data/lib/agent_harness/providers/cursor.rb

@@ -255,6 +255,9 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed (same as Base#send_message)
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         runtime = options[:provider_runtime]
 
         # Normalize and validate MCP servers (same as Base#send_message)
@@ -306,7 +309,7 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration)
 
         response
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -316,6 +319,9 @@ module AgentHarness
         log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
 
@@ -328,7 +334,7 @@ module AgentHarness
           env: build_env(options),
           preparation: build_execution_preparation(options)
         }
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)

data/lib/agent_harness/providers/github_copilot.rb

@@ -292,6 +292,9 @@ module AgentHarness
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
 
@@ -339,7 +342,7 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -349,6 +352,9 @@ module AgentHarness
         log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
 
         options = normalize_provider_runtime(options)
+        skill_context = resolve_skills(options)
+        prompt = apply_skills_to_prompt(prompt, skill_context)
+        options = skill_context[:options]
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
 
@@ -363,7 +369,7 @@ module AgentHarness
           env: env,
           preparation: build_execution_preparation(options)
         }
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ConfigurationError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)

data/lib/agent_harness/skill.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentHarness
+  # Canonical provider-agnostic skill definition loaded from SKILL.md.
+  class Skill
+    PROVIDER_FAMILY_ALIASES = {
+      anthropic: :anthropic,
+      google: :google,
+      openai: :openai,
+      openai_compatible: :openai
+    }.freeze
+
+    attr_reader :name, :description, :instructions, :trigger, :tools, :mcp_servers
+    attr_reader :provider_overrides, :source_path
+
+    def initialize(name:, description:, instructions:, trigger: nil, tools: [], mcp_servers: [],
+      providers: {}, source_path: nil)
+      @name = normalize_name(name)
+      @description = validate_string!(:description, description)
+      @instructions = validate_string!(:instructions, instructions)
+      @trigger = trigger.nil? ? nil : validate_string!(:trigger, trigger)
+      @tools = normalize_array(:tools, tools)
+      @mcp_servers = normalize_mcp_servers(mcp_servers)
+      @provider_overrides = normalize_provider_overrides(providers)
+      @source_path = source_path && File.expand_path(source_path)
+    end
+
+    def self.from_hash(hash = nil, source_path: nil, **kwargs)
+      hash = kwargs if hash.nil? && !kwargs.empty?
+
+      unless hash.is_a?(Hash)
+        raise ConfigurationError, "Skill definition must be a Hash, got #{hash.class}"
+      end
+
+      attrs = hash.each_with_object({}) do |(key, value), memo|
+        memo[key.to_sym] = value
+      end
+
+      %i[name description instructions].each do |field|
+        value = attrs[field]
+        next if value.is_a?(String) && !value.strip.empty?
+        next if value.is_a?(Symbol)
+
+        raise ConfigurationError, "#{field} is required"
+      end
+
+      new(**attrs.merge(source_path: source_path))
+    end
+
+    def self.load_file(path)
+      expanded_path = File.expand_path(path)
+      content = File.read(expanded_path)
+      frontmatter, body = parse_markdown(content)
+      from_hash(frontmatter.merge(instructions: body), source_path: expanded_path)
+    rescue Errno::ENOENT
+      raise ConfigurationError, "Skill file not found: #{path}"
+    rescue Psych::Exception => e
+      raise ConfigurationError, "Invalid YAML frontmatter in skill #{path}: #{e.message}"
+    end
+
+    def provider_override_for(provider)
+      merged = provider_override_keys_for(provider).reduce(nil) do |runtime, key|
+        override = @provider_overrides[key]
+        next runtime unless override
+
+        runtime ? runtime.merge(override) : ProviderRuntime.wrap(override)
+      end
+
+      merged ? merged.to_h : {}
+    end
+
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        instructions: @instructions,
+        trigger: @trigger,
+        tools: deep_dup(@tools),
+        mcp_servers: deep_dup(@mcp_servers),
+        providers: deep_dup(@provider_overrides),
+        source_path: @source_path
+      }.compact
+    end
+
+    private
+
+    def self.parse_markdown(content)
+      match = content.match(/\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m)
+      raise ConfigurationError, "Skill markdown must begin with YAML frontmatter" unless match
+
+      frontmatter = YAML.safe_load(match[1], permitted_classes: [], aliases: false) || {}
+      unless frontmatter.is_a?(Hash)
+        raise ConfigurationError, "Skill frontmatter must be a Hash"
+      end
+
+      [frontmatter, match[2].to_s.strip]
+    end
+    private_class_method :parse_markdown
+
+    def normalize_name(name)
+      value = validate_string!(:name, name)
+      value.tr(" -", "__").to_sym
+    end
+
+    def validate_string!(field, value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ConfigurationError, "#{field} must be a String or Symbol"
+      end
+
+      string = value.to_s.strip
+      raise ConfigurationError, "#{field} is required" if string.empty?
+
+      string
+    end
+
+    def normalize_array(field, value)
+      return [].freeze if value.nil?
+
+      unless value.is_a?(Array)
+        raise ConfigurationError, "#{field} must be an Array"
+      end
+
+      deep_dup(value).freeze
+    end
+
+    def normalize_mcp_servers(mcp_servers)
+      normalize_array(:mcp_servers, mcp_servers).map do |server|
+        case server
+        when McpServer
+          server.to_h.freeze
+        when Hash
+          McpServer.from_hash(server).to_h.freeze
+        else
+          raise ConfigurationError, "Unsupported MCP server reference #{server.inspect} in skill definition"
+        end
+      end.freeze
+    end
+
+    def normalize_provider_overrides(providers)
+      return {}.freeze if providers.nil?
+
+      unless providers.is_a?(Hash)
+        raise ConfigurationError, "providers must be a Hash"
+      end
+
+      providers.each_with_object({}) do |(key, value), memo|
+        provider_key = normalize_provider_key(key)
+        memo[provider_key] = normalize_provider_override_value(provider_key, value)
+      end.freeze
+    end
+
+    def normalize_provider_override_value(provider_key, value)
+      case value
+      when true
+        (provider_key == :all) ? nil : {}
+      when nil
+        {}
+      when Hash
+        deep_dup(value).transform_keys(&:to_sym).freeze
+      else
+        raise ConfigurationError, "providers.#{provider_key} must be true or a Hash"
+      end
+    end
+
+    def normalize_provider_key(provider)
+      key = provider.to_sym
+      return :all if key == :all
+
+      return PROVIDER_FAMILY_ALIASES[key] if PROVIDER_FAMILY_ALIASES.key?(key)
+
+      registry = Providers::Registry.instance
+      canonical = registry.canonical_name(key)
+      raise ConfigurationError, "Unknown provider in skill definition: #{provider}" unless registry.registered?(canonical)
+
+      canonical.to_sym
+    end
+
+    def provider_override_keys_for(provider)
+      key = provider.to_sym
+      return [:all] if key == :all
+
+      registry = Providers::Registry.instance
+      canonical = registry.canonical_name(key)
+      concrete = registry.registered?(canonical) ? canonical.to_sym : key
+      family = normalize_provider_family(concrete)
+
+      [:all, family, concrete].uniq
+    end
+
+    def normalize_provider_family(provider)
+      case provider
+      when :claude then :anthropic
+      when :gemini then :google
+      when :cursor, :github_copilot, :codex, :opencode, :openai_compatible then :openai
+      else provider
+      end
+    end
+
+    def deep_dup(value)
+      case value
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when Hash
+        value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+      else
+        value.dup
+      end
+    rescue TypeError
+      value
+    end
+  end
+end

data/lib/agent_harness/skills.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Filesystem-backed registry for reusable agent skills.
+  module Skills
+    AGENT_HARNESS_SKILLS_DIR = File.join(".agent-harness", "skills")
+    SHARED_SKILLS_DIR = File.join(".agents", "skills")
+
+    class << self
+      def discover(cwd: Dir.pwd, home: Dir.home, refresh: false)
+        cache_key = [File.expand_path(cwd), File.expand_path(home)]
+        @discovered ||= {}
+        @registry ||= {}
+        @discovered.delete(cache_key) if refresh
+        @discovered[cache_key] ||= discover_registry(cwd: cwd, home: home)
+
+        combined_registry(cache_key).values
+      end
+
+      def find(name, cwd: Dir.pwd, home: Dir.home)
+        cache_key = [File.expand_path(cwd), File.expand_path(home)]
+        discover(cwd: cwd, home: home)
+
+        combined_registry(cache_key).fetch(normalize_lookup_key(name)) do
+          raise ConfigurationError, "Unknown skill: #{name}"
+        end
+      end
+
+      def register(name, attributes)
+        @registry ||= {}
+        skill = case attributes
+        when Skill
+          attributes
+        when Hash
+          Skill.from_hash(attributes.merge(name: name))
+        else
+          raise ConfigurationError, "Skill registration must be a Skill or Hash"
+        end
+
+        @registry[skill.name] = skill
+      end
+
+      def resolve(reference, cwd: Dir.pwd, home: Dir.home)
+        case reference
+        when nil
+          nil
+        when Skill
+          reference
+        when Hash
+          Skill.from_hash(reference)
+        else
+          find(reference, cwd: cwd, home: home)
+        end
+      end
+
+      def resolve_all(references, cwd: Dir.pwd, home: Dir.home)
+        Array(references).filter_map { |reference| resolve(reference, cwd: cwd, home: home) }
+      end
+
+      def reset!
+        @registry = {}
+        @discovered = {}
+      end
+
+      private
+
+      def normalize_lookup_key(name)
+        name.to_s.tr(" -", "__").to_sym
+      end
+
+      def combined_registry(cache_key)
+        discovered_registry = @discovered.fetch(cache_key)
+        discovered_registry.merge(@registry || {})
+      end
+
+      def discover_registry(cwd:, home:)
+        skill_paths_for(cwd: cwd, home: home).each_with_object({}) do |path, memo|
+          skill = Skill.load_file(path)
+          memo[skill.name] = skill
+        end
+      end
+
+      def skill_paths_for(cwd:, home:)
+        [
+          File.join(File.expand_path(home), AGENT_HARNESS_SKILLS_DIR),
+          File.join(File.expand_path(cwd), SHARED_SKILLS_DIR),
+          File.join(File.expand_path(cwd), AGENT_HARNESS_SKILLS_DIR)
+        ].flat_map do |directory|
+          next [] unless Dir.exist?(directory)
+
+          direct_skill = File.join(directory, "SKILL.md")
+          nested_skills = Dir.glob(File.join(directory, "*", "SKILL.md")).sort
+          ([direct_skill] + nested_skills).select { |path| File.file?(path) }
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.17.2"
+  VERSION = "0.17.3"
 end

data/lib/agent_harness.rb

@@ -47,6 +47,7 @@ module AgentHarness
       @configuration = nil
       @conductor = nil
       @token_tracker = nil
+      Skills.reset! if defined?(Skills)
     end
 
     # Returns the global logger
@@ -346,6 +347,8 @@ end
 # Core components
 require_relative "agent_harness/errors"
 require_relative "agent_harness/extensions"
+require_relative "agent_harness/skill"
+require_relative "agent_harness/skills"
 require_relative "agent_harness/mcp_server"
 require_relative "agent_harness/mcp_config_loader"
 require_relative "agent_harness/mcp_config_translator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.17.3
 platform: ruby
 authors:
 - Bart Agapinan
@@ -138,6 +138,8 @@ files:
 - lib/agent_harness/providers/registry.rb
 - lib/agent_harness/providers/token_usage_parsing.rb
 - lib/agent_harness/response.rb
+- lib/agent_harness/skill.rb
+- lib/agent_harness/skills.rb
 - lib/agent_harness/sub_agent_config.rb
 - lib/agent_harness/sub_agent_file_loader.rb
 - lib/agent_harness/sub_agent_translator.rb