ruby_llm-skills 0.1.0 → 0.3.0

data/lib/ruby_llm/skills/agent_extensions.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Skills
+    # Extensions for RubyLLM::Agent to enable declarative skill configuration.
+    #
+    # @example Static skills
+    #   class SupportAgent < RubyLLM::Agent
+    #     skills "app/skills", only: [:faq]
+    #   end
+    #
+    # @example Dynamic skills
+    #   class WorkspaceAgent < RubyLLM::Agent
+    #     inputs :workspace
+    #     skills { [workspace.skill_collection] }
+    #   end
+    #
+    module AgentExtensions
+      REQUIRED_AGENT_SINGLETON_METHODS = %i[apply_configuration runtime_context llm_chat_for].freeze
+
+      module ClassMethods
+        def self.extended(base)
+          base.instance_variable_set(:@skill_sources, nil)
+          base.instance_variable_set(:@skill_only, nil)
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@skill_sources, @skill_sources.is_a?(Proc) ? @skill_sources : @skill_sources&.dup)
+          subclass.instance_variable_set(:@skill_only, @skill_only&.dup)
+        end
+
+        # Declare skill sources for this agent class.
+        #
+        # Called with no arguments, returns the current configuration.
+        # Called with sources or a block, sets the configuration.
+        #
+        # @param sources [Array] skill sources
+        # @param only [Array<Symbol, String>, nil] include only these skills
+        # @return [Hash] current configuration when called as a getter
+        def skills(*sources, only: nil, &block)
+          if sources.empty? && only.nil? && !block_given?
+            return {
+              sources: @skill_sources.is_a?(Proc) ? @skill_sources : @skill_sources&.dup,
+              only: @skill_only&.dup
+            }
+          end
+
+          @skill_sources = block_given? ? block : normalize_skill_sources(sources)
+          @skill_only = only&.dup
+        end
+
+        private
+
+        def normalize_skill_sources(raw_sources)
+          flatten_skill_sources(raw_sources).compact
+        end
+
+        def flatten_skill_sources(source)
+          return [] if source.nil?
+          return [source] if source.is_a?(String)
+          return [source] if loader_source?(source)
+          return [source] if database_collection_source?(source)
+          return source.flat_map { |item| flatten_skill_sources(item) } if source.is_a?(Array)
+
+          [source]
+        end
+
+        def loader_source?(source)
+          source.respond_to?(:list) && source.respond_to?(:find)
+        end
+
+        def database_collection_source?(source)
+          source.respond_to?(:to_a) && source.first&.respond_to?(:name) && source.first.respond_to?(:content)
+        end
+      end
+
+      module InstanceMethods
+        # Add skills to this agent instance at runtime.
+        #
+        # @param sources [Array] skill sources
+        # @param only [Array<Symbol, String>, nil] include only these skills
+        # @return [self] for chaining
+        def with_skills(*sources, only: nil)
+          chat.with_skills(*sources, only: only)
+          self
+        end
+      end
+
+      module ConfigurationPatch
+        private
+
+        def apply_configuration(chat_object, **kwargs)
+          super
+          input_values = kwargs[:input_values] || {}
+          runtime = runtime_context(chat: chat_object, inputs: input_values)
+          apply_skills(llm_chat_for(chat_object), runtime)
+        end
+
+        def apply_skills(llm_chat, runtime)
+          config = skills
+          sources = config[:sources]
+          return if sources.nil?
+
+          resolved_sources = if sources.is_a?(Proc)
+            runtime.instance_exec(&sources)
+          else
+            sources
+          end
+
+          normalized_sources = normalize_skill_sources(resolved_sources)
+          return if normalized_sources.empty?
+
+          validate_skill_sources!(normalized_sources)
+          llm_chat.with_skills(*normalized_sources, only: config[:only])
+        end
+
+        def validate_skill_sources!(sources)
+          invalid_sources = sources.reject { |source| valid_skill_source?(source) }
+          return if invalid_sources.empty?
+
+          invalid_types = invalid_sources.map { |source| source.class.name || source.class.to_s }.uniq.join(", ")
+          raise ArgumentError,
+            "Invalid skill source(s): #{invalid_types}. Expected String path, Loader, or record collection."
+        end
+
+        def valid_skill_source?(source)
+          source.is_a?(String) || loader_source?(source) || database_collection_source?(source)
+        end
+      end
+
+      def self.included(base)
+        missing_methods = REQUIRED_AGENT_SINGLETON_METHODS.reject do |method_name|
+          base.singleton_class.private_method_defined?(method_name) || base.singleton_class.method_defined?(method_name)
+        end
+
+        if missing_methods.any?
+          raise LoadError,
+            "RubyLLM::Agent is missing required methods for ruby_llm-skills integration: #{missing_methods.join(", ")}"
+        end
+
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+        base.singleton_class.prepend(ConfigurationPatch)
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/chat_extensions.rb

@@ -1,49 +1,102 @@
 # frozen_string_literal: true
 
-module RubyLlm
+require_relative "skill_tool"
+
+module RubyLLM
   module Skills
     # Extensions for RubyLLM::Chat to enable skill integration.
     #
-    # These methods are added to RubyLLM::Chat when ruby_llm-skills is loaded,
-    # providing a convenient API for adding skills to conversations.
+    # @example Default (app/skills)
+    #   chat.with_skills
+    #
+    # @example Custom path
+    #   chat.with_skills("lib/skills")
     #
-    # @example
-    #   chat = RubyLlm.chat
-    #   chat.with_skills("app/skills")
-    #   chat.ask("Generate a PDF report")
+    # @example Multiple sources (auto-detected)
+    #   chat.with_skills("app/skills", "app/commands", user.skills)
+    #
+    # @example Filter skills
+    #   chat.with_skills(only: [:pdf_report])
     #
     module ChatExtensions
-      # Add skills from a directory to this chat.
+      # Add skills to this chat.
       #
-      # @param path [String] path to skills directory
+      # @param sources [Array] skill sources - auto-detects type (directory, zip, collection)
+      # @param only [Array<Symbol, String>, nil] include only these skills
       # @return [self] for chaining
-      # @example
-      #   chat.with_skills("app/skills")
-      def with_skills(path = RubyLlm::Skills.default_path)
-        loader = RubyLlm::Skills.from_directory(path)
-        skill_tool = RubyLlm::Skills::SkillTool.new(loader)
+      def with_skills(*sources, only: nil)
+        sources = [RubyLLM::Skills.default_path] if sources.empty?
+        loaders = sources.map { |s| to_loader(s) }
+
+        loader = (loaders.length == 1) ? loaders.first : RubyLLM::Skills.compose(*loaders)
+        loader = FilteredLoader.new(loader, only) if only
+
+        skill_tool = RubyLLM::Skills::SkillTool.new(loader)
         with_tool(skill_tool)
       end
 
-      # Add skills from a loader to this chat.
-      #
-      # @param loader [Loader] any skill loader
-      # @return [self] for chaining
-      # @example
-      #   loader = RubyLlm::Skills.compose(
-      #     RubyLlm::Skills.from_directory("app/skills"),
-      #     RubyLlm::Skills.from_database(Skill.all)
-      #   )
-      #   chat.with_skill_loader(loader)
-      def with_skill_loader(loader)
-        skill_tool = RubyLlm::Skills::SkillTool.new(loader)
-        with_tool(skill_tool)
+      private
+
+      def to_loader(source)
+        case source
+        when String
+          RubyLLM::Skills.from_directory(source)
+        when ->(s) { database_collection_source?(s) }
+          RubyLLM::Skills.from_database(source)
+        when ->(s) { loader_source?(s) }
+          source
+        else
+          raise ArgumentError,
+            "Invalid skill source: #{source.class}. Expected String path, Loader, or record collection."
+        end
+      end
+
+      def loader_source?(source)
+        source.respond_to?(:list) && source.respond_to?(:find)
+      end
+
+      def database_collection_source?(source)
+        source.respond_to?(:to_a) && source.first&.respond_to?(:name) && source.first.respond_to?(:content)
       end
     end
-  end
-end
 
-# Extend RubyLLM::Chat if available
-if defined?(RubyLlm::Chat)
-  RubyLlm::Chat.include(RubyLlm::Skills::ChatExtensions)
+    # Simple wrapper that filters skills by name.
+    class FilteredLoader
+      def initialize(loader, only)
+        @loader = loader
+        @only = Array(only).map(&:to_s)
+      end
+
+      def list
+        @loader.list.select { |s| @only.include?(s.name) }
+      end
+
+      def find(name)
+        return nil unless @only.include?(name.to_s)
+        @loader.find(name)
+      end
+
+      def get(name)
+        raise NotFoundError, "Skill not found: #{name}" unless @only.include?(name.to_s)
+        @loader.get(name)
+      end
+
+      def exists?(name)
+        @only.include?(name.to_s) && @loader.exists?(name)
+      end
+
+      def reload!
+        @loader.reload!
+        self
+      end
+    end
+
+    # Extensions for ActiveRecord models using acts_as_chat.
+    module ActiveRecordExtensions
+      def with_skills(*sources, only: nil)
+        to_llm.with_skills(*sources, only: only)
+        self
+      end
+    end
+  end
 end

data/lib/ruby_llm/skills/composite_loader.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Combines multiple loaders into a single source.
     #

data/lib/ruby_llm/skills/database_loader.rb

@@ -1,46 +1,27 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
-    # Loads skills from database records using duck-typing.
+    # Loads skills from database records.
     #
-    # Records must respond to either:
-    # - Text storage: #name, #description, #content
-    # - Binary storage: #name, #description, #data (zip blob)
+    # Records must respond to: #name, #description, #content
+    # Optional: #license, #compatibility, #skill_metadata
     #
-    # Optional methods: #license, #compatibility, #metadata
-    #
-    # @example With text content
-    #   class SkillRecord
-    #     attr_accessor :name, :description, :content
-    #   end
-    #   loader = DatabaseLoader.new(SkillRecord.all)
-    #
-    # @example With ActiveRecord
-    #   loader = DatabaseLoader.new(Skill.where(active: true))
+    # @example
+    #   loader = DatabaseLoader.new(Skill.where(user: current_user))
     #
     class DatabaseLoader < Loader
       attr_reader :records
 
-      # Initialize with a collection of records.
-      #
-      # @param records [Enumerable] collection responding to #each
       def initialize(records)
         super()
         @records = records
       end
 
-      # List all skills from the records.
-      #
-      # @return [Array<Skill>] skills from records
       def list
         skills
       end
 
-      # Reload skills by re-iterating records.
-      # Also reloads the records if they respond to #reload.
-      #
-      # @return [self]
       def reload!
         @records.reload if @records.respond_to?(:reload)
         super
@@ -52,7 +33,7 @@ module RubyLlm
         @records.filter_map do |record|
           load_skill_from_record(record)
         rescue => e
-          warn "Warning: Failed to load skill from record: #{e.message}" if RubyLlm::Skills.logger
+          warn "Failed to load skill from record: #{e.message}"
           nil
         end
       end
@@ -60,22 +41,20 @@ module RubyLlm
       private
 
       def load_skill_from_record(record)
-        if binary_storage?(record)
-          load_from_binary(record)
-        else
-          load_from_text(record)
-        end
-      end
+        validate_record!(record)
 
-      def binary_storage?(record)
-        record.respond_to?(:data) && record.data.present?
-      end
+        metadata = {
+          "name" => record.name.to_s,
+          "description" => record.description.to_s,
+          "__content__" => record.content.to_s
+        }
 
-      def load_from_text(record)
-        validate_text_record!(record)
+        metadata["license"] = record.license.to_s if record.respond_to?(:license) && record.license
+        metadata["compatibility"] = record.compatibility.to_s if record.respond_to?(:compatibility) && record.compatibility
 
-        metadata = build_metadata(record)
-        metadata["__content__"] = record.content.to_s
+        if record.respond_to?(:skill_metadata) && record.skill_metadata.is_a?(Hash)
+          metadata["metadata"] = record.skill_metadata
+        end
 
         Skill.new(
           path: "database:#{record_id(record)}",
@@ -83,64 +62,14 @@ module RubyLlm
         )
       end
 
-      def load_from_binary(record)
-        # Extract skill from zip data
-        require "zip"
-        require "stringio"
-
-        io = StringIO.new(record.data)
-        Zip::File.open_buffer(io) do |zip|
-          skill_md_entry = zip.find_entry("SKILL.md")
-          raise LoadError, "SKILL.md not found in binary data" unless skill_md_entry
-
-          content = skill_md_entry.get_input_stream.read
-          metadata = Parser.parse_string(content)
-          body = Parser.extract_body(content)
-
-          # Override name/description from record if present
-          metadata["name"] = record.name if record.respond_to?(:name) && record.name
-          metadata["description"] = record.description if record.respond_to?(:description) && record.description
-          metadata["__content__"] = body
-
-          Skill.new(
-            path: "database:#{record_id(record)}",
-            metadata: metadata
-          )
-        end
-      rescue ::LoadError
-        raise LoadError, "rubyzip gem required for binary storage. Add 'gem \"rubyzip\"' to your Gemfile."
-      end
-
-      def validate_text_record!(record)
+      def validate_record!(record)
         raise InvalidSkillError, "Record must respond to #name" unless record.respond_to?(:name)
         raise InvalidSkillError, "Record must respond to #description" unless record.respond_to?(:description)
         raise InvalidSkillError, "Record must respond to #content" unless record.respond_to?(:content)
       end
 
-      def build_metadata(record)
-        metadata = {
-          "name" => record.name.to_s,
-          "description" => record.description.to_s
-        }
-
-        metadata["license"] = record.license.to_s if record.respond_to?(:license) && record.license
-        metadata["compatibility"] = record.compatibility.to_s if record.respond_to?(:compatibility) && record.compatibility
-
-        if record.respond_to?(:skill_metadata) && record.skill_metadata.is_a?(Hash)
-          metadata["metadata"] = record.skill_metadata
-        end
-
-        metadata
-      end
-
       def record_id(record)
-        if record.respond_to?(:id)
-          record.id
-        elsif record.respond_to?(:name)
-          record.name
-        else
-          record.object_id
-        end
+        record.respond_to?(:id) ? record.id : record.name
       end
     end
   end

data/lib/ruby_llm/skills/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Base error class for all skills-related errors.
     # Rescue this to catch any error from the gem.

data/lib/ruby_llm/skills/filesystem_loader.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Loads skills from a filesystem directory.
     #
-    # Scans a directory for subdirectories containing SKILL.md files.
-    # Each subdirectory is treated as a skill if it contains a valid SKILL.md.
+    # Supports two formats:
+    # 1. Directory skills: subdirectories containing SKILL.md files
+    # 2. Single-file commands: .md files with frontmatter at the root level
     #
-    # @example
-    #   loader = FilesystemLoader.new("app/skills")
-    #   loader.list # => [Skill, Skill, ...]
+    # @example Directory skills
+    #   app/skills/
+    #   └── pdf-report/
+    #       └── SKILL.md
+    #
+    # @example Single-file commands
+    #   app/commands/
+    #   └── write-poem.md
     #
     class FilesystemLoader < Loader
       attr_reader :path
@@ -34,22 +40,49 @@ module RubyLlm
       def load_all
         return [] unless File.directory?(@path)
 
+        directory_skills + single_file_skills
+      end
+
+      private
+
+      # Load skills from subdirectories containing SKILL.md
+      def directory_skills
         Dir.glob(File.join(@path, "*", "SKILL.md")).filter_map do |skill_md_path|
-          load_skill(skill_md_path)
+          load_directory_skill(skill_md_path)
         rescue ParseError => e
-          warn "Warning: Failed to parse #{skill_md_path}: #{e.message}" if RubyLlm::Skills.logger
+          log_warning("Failed to parse #{skill_md_path}: #{e.message}")
           nil
         end
       end
 
-      private
+      # Load single-file .md commands from root level
+      def single_file_skills
+        Dir.glob(File.join(@path, "*.md")).filter_map do |md_path|
+          load_single_file_skill(md_path)
+        rescue ParseError => e
+          log_warning("Failed to parse #{md_path}: #{e.message}")
+          nil
+        end
+      end
 
-      def load_skill(skill_md_path)
+      def load_directory_skill(skill_md_path)
         skill_dir = File.dirname(skill_md_path)
         metadata = Parser.parse_file(skill_md_path)
 
         Skill.new(path: skill_dir, metadata: metadata)
       end
+
+      def load_single_file_skill(md_path)
+        metadata = Parser.parse_file(md_path)
+
+        # For single-file skills, the path is the file itself
+        # They are virtual in that they have no resources
+        Skill.new(path: md_path, metadata: metadata, virtual: true)
+      end
+
+      def log_warning(message)
+        warn(message)
+      end
     end
   end
 end

data/lib/ruby_llm/skills/loader.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Base class for skill loaders.
     #

data/lib/ruby_llm/skills/parser.rb

@@ -2,7 +2,7 @@
 
 require "yaml"
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Parses SKILL.md files with YAML frontmatter.
     #

data/lib/ruby_llm/skills/railtie.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Rails integration for RubyLLM::Skills.
     #
@@ -9,14 +9,23 @@ module RubyLlm
     #
     class Railtie < ::Rails::Railtie
       initializer "ruby_llm_skills.configure" do
-        RubyLlm::Skills.default_path = Rails.root.join("app", "skills").to_s
+        RubyLLM::Skills.default_path = Rails.root.join("app", "skills").to_s
       end
 
-      # Add app/skills to autoload paths
-      initializer "ruby_llm_skills.autoload_paths" do |app|
+      # Add app/skills to autoload paths (before initialization)
+      config.before_configuration do |app|
         skills_path = Rails.root.join("app", "skills")
         if skills_path.exist?
-          app.config.autoload_paths << skills_path.to_s
+          app.config.autoload_paths += [skills_path.to_s]
+        end
+      end
+
+      # Extend acts_as_chat models with skill methods
+      initializer "ruby_llm_skills.active_record" do
+        ActiveSupport.on_load(:active_record) do
+          if defined?(RubyLLM::ActiveRecord::ChatMethods)
+            RubyLLM::ActiveRecord::ChatMethods.include(RubyLLM::Skills::ActiveRecordExtensions)
+          end
         end
       end
 

data/lib/ruby_llm/skills/skill.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Represents a single skill with its metadata and content.
     #
@@ -23,13 +23,15 @@ module RubyLlm
 
       # Initialize a skill from parsed metadata.
       #
-      # @param path [String] path to skill directory or virtual identifier
+      # @param path [String] path to skill directory, file, or virtual identifier
       # @param metadata [Hash] parsed YAML frontmatter
       # @param content [String, nil] pre-loaded content (optional)
-      def initialize(path:, metadata:, content: nil)
+      # @param virtual [Boolean] force virtual mode (no filesystem access)
+      def initialize(path:, metadata:, content: nil, virtual: false)
         @path = path.to_s
         @metadata = metadata || {}
         @content = content
+        @virtual = virtual
       end
 
       # @return [String] skill name from frontmatter
@@ -101,11 +103,11 @@ module RubyLlm
         !virtual?
       end
 
-      # Check if skill is a virtual/database skill.
+      # Check if skill is a virtual/database skill (no filesystem resources).
       #
-      # @return [Boolean] true if path is a virtual identifier
+      # @return [Boolean] true if skill has no filesystem resources
       def virtual?
-        @path.start_with?("database:")
+        @virtual || @path.start_with?("database:")
       end
 
       # Path to the SKILL.md file.
@@ -150,14 +152,27 @@ module RubyLlm
 
       def load_content
         return @metadata["__content__"] if @metadata["__content__"]
+
+        # For single-file skills, path is the .md file itself
+        if single_file?
+          return "" unless File.exist?(@path)
+          return Parser.extract_body(File.read(@path))
+        end
+
+        # For virtual skills (database), no filesystem content
         return "" if virtual?
 
+        # For directory skills, load from SKILL.md
         md_path = skill_md_path
         return "" unless md_path && File.exist?(md_path)
 
         Parser.extract_body(File.read(md_path))
       end
 
+      def single_file?
+        @path.end_with?(".md") && File.file?(@path)
+      end
+
       def list_resources(subdir)
         return [] if virtual?