agent-harness 0.17.2 → 0.18.0

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.18.0"
 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.18.0
 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