ruby_llm-skills 0.1.0

data/lib/ruby_llm/skills/database_loader.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Loads skills from database records using duck-typing.
+    #
+    # Records must respond to either:
+    # - Text storage: #name, #description, #content
+    # - Binary storage: #name, #description, #data (zip blob)
+    #
+    # 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))
+    #
+    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
+      end
+
+      protected
+
+      def load_all
+        @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
+          nil
+        end
+      end
+
+      private
+
+      def load_skill_from_record(record)
+        if binary_storage?(record)
+          load_from_binary(record)
+        else
+          load_from_text(record)
+        end
+      end
+
+      def binary_storage?(record)
+        record.respond_to?(:data) && record.data.present?
+      end
+
+      def load_from_text(record)
+        validate_text_record!(record)
+
+        metadata = build_metadata(record)
+        metadata["__content__"] = record.content.to_s
+
+        Skill.new(
+          path: "database:#{record_id(record)}",
+          metadata: metadata
+        )
+      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)
+        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
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Base error class for all skills-related errors.
+    # Rescue this to catch any error from the gem.
+    class Error < StandardError; end
+
+    # Raised when a skill has invalid structure or content.
+    class InvalidSkillError < Error; end
+
+    # Raised when a requested skill cannot be found.
+    class NotFoundError < Error; end
+
+    # Raised when skill loading fails (filesystem, zip, database).
+    class LoadError < Error; end
+
+    # Raised when YAML frontmatter parsing fails.
+    class ParseError < Error; end
+  end
+end

data/lib/ruby_llm/skills/filesystem_loader.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # @example
+    #   loader = FilesystemLoader.new("app/skills")
+    #   loader.list # => [Skill, Skill, ...]
+    #
+    class FilesystemLoader < Loader
+      attr_reader :path
+
+      # Initialize with a directory path.
+      #
+      # @param path [String, Pathname] path to skills directory
+      def initialize(path)
+        super()
+        @path = path.to_s
+      end
+
+      # List all skills from the directory.
+      #
+      # @return [Array<Skill>] skills found in directory
+      def list
+        skills
+      end
+
+      protected
+
+      def load_all
+        return [] unless File.directory?(@path)
+
+        Dir.glob(File.join(@path, "*", "SKILL.md")).filter_map do |skill_md_path|
+          load_skill(skill_md_path)
+        rescue ParseError => e
+          warn "Warning: Failed to parse #{skill_md_path}: #{e.message}" if RubyLlm::Skills.logger
+          nil
+        end
+      end
+
+      private
+
+      def load_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
+    end
+  end
+end

data/lib/ruby_llm/skills/loader.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Base class for skill loaders.
+    #
+    # Loaders are responsible for discovering and loading skills from various sources:
+    # - FilesystemLoader: loads from directory structures
+    # - ZipLoader: loads from .zip archives
+    # - DatabaseLoader: loads from ActiveRecord models
+    #
+    # @example
+    #   loader = FilesystemLoader.new("app/skills")
+    #   loader.list         # => [skill1, skill2, ...]
+    #   loader.find("name") # => Skill or nil
+    #   loader.get("name")  # => Skill or raises NotFoundError
+    #
+    class Loader
+      # List all skills from this source.
+      #
+      # @return [Array<Skill>] collection of skills
+      def list
+        raise NotImplementedError, "#{self.class}#list must be implemented"
+      end
+
+      # Find a skill by name.
+      #
+      # @param name [String] skill name
+      # @return [Skill, nil] skill or nil if not found
+      def find(name)
+        list.find { |skill| skill.name == name }
+      end
+
+      # Get a skill by name, raising if not found.
+      #
+      # @param name [String] skill name
+      # @return [Skill] the found skill
+      # @raise [NotFoundError] if skill not found
+      def get(name)
+        skill = find(name)
+        raise NotFoundError, "Skill not found: #{name}" unless skill
+
+        skill
+      end
+
+      # Check if a skill exists.
+      #
+      # @param name [String] skill name
+      # @return [Boolean] true if skill exists
+      def exists?(name)
+        !find(name).nil?
+      end
+
+      # Reload all skills, clearing any cache.
+      #
+      # @return [self]
+      def reload!
+        @skills = nil
+        self
+      end
+
+      protected
+
+      # Cache skills from #load_all for performance.
+      def skills
+        @skills ||= load_all
+      end
+
+      # Subclasses must implement this to load all skills.
+      #
+      # @return [Array<Skill>] all skills from source
+      def load_all
+        raise NotImplementedError, "#{self.class}#load_all must be implemented"
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/parser.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RubyLlm
+  module Skills
+    # Parses SKILL.md files with YAML frontmatter.
+    #
+    # A valid SKILL.md has the format:
+    #   ---
+    #   name: skill-name
+    #   description: What the skill does
+    #   ---
+    #   # Skill content here
+    #
+    class Parser
+      # Regex to match YAML frontmatter between --- delimiters
+      FRONTMATTER_REGEX = /\A---\n(.*?)\n---\n?(.*)/m
+
+      class << self
+        # Parse a SKILL.md file and extract frontmatter metadata.
+        #
+        # @param path [String, Pathname] path to SKILL.md file
+        # @return [Hash] parsed frontmatter as hash
+        # @raise [ParseError] if frontmatter is missing or invalid
+        def parse_file(path)
+          content = File.read(path)
+          parse_string(content)
+        rescue Errno::ENOENT
+          raise ParseError, "File not found: #{path}"
+        rescue Errno::EACCES
+          raise ParseError, "Permission denied: #{path}"
+        end
+
+        # Parse SKILL.md content string and extract frontmatter.
+        #
+        # @param content [String] full SKILL.md content
+        # @return [Hash] parsed frontmatter as hash
+        # @raise [ParseError] if frontmatter is missing or invalid
+        def parse_string(content)
+          match = content.match(FRONTMATTER_REGEX)
+
+          unless match
+            raise ParseError, "Missing YAML frontmatter (must start with ---)"
+          end
+
+          yaml_content = match[1]
+          parse_yaml(yaml_content)
+        end
+
+        # Extract the body content (everything after frontmatter).
+        #
+        # @param content [String] full SKILL.md content
+        # @return [String] body content without frontmatter
+        def extract_body(content)
+          match = content.match(FRONTMATTER_REGEX)
+          return "" unless match
+
+          match[2].to_s.strip
+        end
+
+        private
+
+        def parse_yaml(yaml_content)
+          # Use safe_load with permitted classes for security
+          YAML.safe_load(
+            yaml_content,
+            permitted_classes: [Symbol],
+            permitted_symbols: [],
+            aliases: false
+          ) || {}
+        rescue Psych::SyntaxError => e
+          raise ParseError, "Invalid YAML frontmatter: #{e.message}"
+        rescue Psych::DisallowedClass => e
+          raise ParseError, "Disallowed class in YAML: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Rails integration for RubyLLM::Skills.
+    #
+    # Sets up the default skills path to Rails.root/app/skills
+    # and configures autoloading of skill files.
+    #
+    class Railtie < ::Rails::Railtie
+      initializer "ruby_llm_skills.configure" do
+        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|
+        skills_path = Rails.root.join("app", "skills")
+        if skills_path.exist?
+          app.config.autoload_paths << skills_path.to_s
+        end
+      end
+
+      # Provide rake tasks
+      rake_tasks do
+        load File.expand_path("tasks/skills.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/skill.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Represents a single skill with its metadata and content.
+    #
+    # Skills follow a progressive disclosure pattern:
+    # - Level 1: Metadata (name, description) - loaded immediately
+    # - Level 2: Content (SKILL.md body) - loaded lazily on demand
+    # - Level 3: Resources (scripts, references, assets) - loaded lazily
+    #
+    # @example
+    #   skill = Skill.new(
+    #     path: "app/skills/pdf-report",
+    #     metadata: { "name" => "pdf-report", "description" => "Generate PDFs" }
+    #   )
+    #   skill.name        # => "pdf-report" (immediate)
+    #   skill.content     # => loads SKILL.md body (lazy)
+    #   skill.scripts     # => lists script files (lazy)
+    #
+    class Skill
+      attr_reader :path, :metadata
+
+      # Initialize a skill from parsed metadata.
+      #
+      # @param path [String] path to skill directory or virtual identifier
+      # @param metadata [Hash] parsed YAML frontmatter
+      # @param content [String, nil] pre-loaded content (optional)
+      def initialize(path:, metadata:, content: nil)
+        @path = path.to_s
+        @metadata = metadata || {}
+        @content = content
+      end
+
+      # @return [String] skill name from frontmatter
+      def name
+        @metadata["name"]
+      end
+
+      # @return [String] skill description from frontmatter
+      def description
+        @metadata["description"]
+      end
+
+      # @return [String, nil] license from frontmatter
+      def license
+        @metadata["license"]
+      end
+
+      # @return [String, nil] compatibility info from frontmatter
+      def compatibility
+        @metadata["compatibility"]
+      end
+
+      # @return [Hash] custom metadata key-value pairs
+      def custom_metadata
+        @metadata["metadata"] || {}
+      end
+
+      # @return [Array<String>] list of allowed tools (experimental)
+      def allowed_tools
+        (@metadata["allowed-tools"] || "").split
+      end
+
+      # Get the full SKILL.md content (body without frontmatter).
+      # Content is loaded lazily on first access.
+      #
+      # @return [String] skill instructions
+      def content
+        @content ||= load_content
+      end
+
+      # List script files in the scripts/ directory.
+      # Loaded lazily on first access.
+      #
+      # @return [Array<String>] paths to script files
+      def scripts
+        @scripts ||= list_resources("scripts")
+      end
+
+      # List reference files in the references/ directory.
+      # Loaded lazily on first access.
+      #
+      # @return [Array<String>] paths to reference files
+      def references
+        @references ||= list_resources("references")
+      end
+
+      # List asset files in the assets/ directory.
+      # Loaded lazily on first access.
+      #
+      # @return [Array<String>] paths to asset files
+      def assets
+        @assets ||= list_resources("assets")
+      end
+
+      # Check if skill path is a filesystem path (vs database virtual path).
+      #
+      # @return [Boolean] true if path points to filesystem
+      def filesystem?
+        !virtual?
+      end
+
+      # Check if skill is a virtual/database skill.
+      #
+      # @return [Boolean] true if path is a virtual identifier
+      def virtual?
+        @path.start_with?("database:")
+      end
+
+      # Path to the SKILL.md file.
+      #
+      # @return [String, nil] path to SKILL.md or nil for virtual skills
+      def skill_md_path
+        return nil if virtual?
+
+        File.join(@path, "SKILL.md")
+      end
+
+      # Validate the skill structure.
+      #
+      # @return [Boolean] true if skill is valid
+      def valid?
+        errors.empty?
+      end
+
+      # Get validation errors.
+      #
+      # @return [Array<String>] list of error messages
+      def errors
+        @errors ||= Validator.validate(self)
+      end
+
+      # Clear cached content and resources (useful for testing).
+      def reload!
+        @content = nil
+        @scripts = nil
+        @references = nil
+        @assets = nil
+        @errors = nil
+        self
+      end
+
+      # @return [String] inspection string
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} path=#{path.inspect}>"
+      end
+
+      private
+
+      def load_content
+        return @metadata["__content__"] if @metadata["__content__"]
+        return "" if virtual?
+
+        md_path = skill_md_path
+        return "" unless md_path && File.exist?(md_path)
+
+        Parser.extract_body(File.read(md_path))
+      end
+
+      def list_resources(subdir)
+        return [] if virtual?
+
+        resource_path = File.join(@path, subdir)
+        return [] unless File.directory?(resource_path)
+
+        Dir.glob(File.join(resource_path, "**", "*"))
+          .select { |f| File.file?(f) }
+          .reject { |f| File.basename(f) == ".keep" }
+          .sort
+      end
+    end
+  end
+end