ruby_llm-skills 0.1.0

data/lib/ruby_llm/skills/skill_tool.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # A RubyLLM Tool that enables progressive skill loading.
+    #
+    # This tool is the key integration point for LLM skill discovery.
+    # It embeds skill metadata (name + description) in its description,
+    # allowing the LLM to discover available skills. When invoked,
+    # it returns the full skill content.
+    #
+    # Progressive Disclosure Pattern:
+    # 1. Skill metadata is always visible in the tool description (~100 tokens/skill)
+    # 2. Full skill content is loaded on-demand when the tool is called (~5k tokens)
+    # 3. Resources (scripts, references) can be loaded separately as needed
+    #
+    # @example Basic usage
+    #   loader = RubyLlm::Skills.from_directory("app/skills")
+    #   skill_tool = RubyLlm::Skills::SkillTool.new(loader)
+    #
+    #   chat.with_tools(skill_tool)
+    #   chat.ask("Help me generate a PDF report")
+    #   # LLM sees available skills, calls skill_tool with name="pdf-report"
+    #   # Tool returns full SKILL.md content for LLM to follow
+    #
+    class SkillTool
+      attr_reader :loader
+
+      # Initialize with a skill loader.
+      #
+      # @param loader [Loader] any loader (FilesystemLoader, ZipLoader, etc.)
+      def initialize(loader)
+        @loader = loader
+      end
+
+      # Tool name for RubyLLM.
+      #
+      # @return [String] "skill"
+      def name
+        "skill"
+      end
+
+      # Dynamic description including available skills.
+      #
+      # @return [String] tool description with embedded skill metadata
+      def description
+        skills_xml = build_skills_xml
+        <<~DESC.strip
+          Load a skill to get specialized instructions for a task.
+
+          Use this tool when the user's request matches one of the available skills.
+          The tool returns the full skill instructions that you should follow.
+
+          #{skills_xml}
+        DESC
+      end
+
+      # Parameter schema for the tool.
+      #
+      # @return [Hash] JSON Schema for parameters
+      def parameters
+        {
+          type: "object",
+          properties: {
+            skill_name: {
+              type: "string",
+              description: "The name of the skill to load (from the available skills list)"
+            }
+          },
+          required: ["skill_name"]
+        }
+      end
+
+      # Execute the tool to load a skill's content.
+      #
+      # @param skill_name [String] name of skill to load
+      # @return [String] skill content or error message
+      def call(skill_name:)
+        skill = @loader.find(skill_name)
+
+        unless skill
+          available = @loader.list.map(&:name).join(", ")
+          return "Skill '#{skill_name}' not found. Available skills: #{available}"
+        end
+
+        build_skill_response(skill)
+      end
+
+      # Alternative execute method name for RubyLLM compatibility.
+      def execute(skill_name:)
+        call(skill_name: skill_name)
+      end
+
+      # Convert to RubyLLM Tool-compatible format.
+      #
+      # @return [Hash] tool definition for RubyLLM
+      def to_tool_definition
+        {
+          name: name,
+          description: description,
+          parameters: parameters
+        }
+      end
+
+      private
+
+      def build_skills_xml
+        skills = @loader.list
+
+        return "<available_skills>\nNo skills available.\n</available_skills>" if skills.empty?
+
+        xml_parts = ["<available_skills>"]
+
+        skills.each do |skill|
+          xml_parts << "  <skill>"
+          xml_parts << "    <name>#{escape_xml(skill.name)}</name>"
+          xml_parts << "    <description>#{escape_xml(skill.description)}</description>"
+          xml_parts << "  </skill>"
+        end
+
+        xml_parts << "</available_skills>"
+        xml_parts.join("\n")
+      end
+
+      def build_skill_response(skill)
+        parts = []
+        parts << "# Skill: #{skill.name}"
+        parts << ""
+        parts << skill.content
+        parts << ""
+
+        # Include resource information if available
+        if skill.scripts.any?
+          parts << "## Available Scripts"
+          skill.scripts.each { |s| parts << "- #{File.basename(s)}" }
+          parts << ""
+        end
+
+        if skill.references.any?
+          parts << "## Available References"
+          skill.references.each { |r| parts << "- #{File.basename(r)}" }
+          parts << ""
+        end
+
+        if skill.assets.any?
+          parts << "## Available Assets"
+          skill.assets.each { |a| parts << "- #{File.basename(a)}" }
+          parts << ""
+        end
+
+        parts.join("\n").strip
+      end
+
+      def escape_xml(text)
+        return "" if text.nil?
+
+        text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+          .gsub("'", "&apos;")
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/tasks/skills.rake

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+namespace :skills do
+  desc "List all available skills"
+  task list: :environment do
+    loader = RubyLlm::Skills.from_directory
+    skills = loader.list
+
+    if skills.empty?
+      puts "No skills found in #{RubyLlm::Skills.default_path}"
+      next
+    end
+
+    puts "Available skills (#{skills.count}):"
+    puts ""
+
+    skills.each do |skill|
+      status = skill.valid? ? "✓" : "✗"
+      puts "  #{status} #{skill.name}"
+      puts "    #{skill.description}"
+      puts ""
+    end
+  end
+
+  desc "Validate all skills"
+  task validate: :environment do
+    loader = RubyLlm::Skills.from_directory
+    skills = loader.list
+
+    if skills.empty?
+      puts "No skills found in #{RubyLlm::Skills.default_path}"
+      next
+    end
+
+    valid_count = 0
+    invalid_count = 0
+
+    skills.each do |skill|
+      if skill.valid?
+        valid_count += 1
+        puts "✓ #{skill.name}"
+      else
+        invalid_count += 1
+        puts "✗ #{skill.name}"
+        skill.errors.each do |error|
+          puts "    - #{error}"
+        end
+      end
+    end
+
+    puts ""
+    puts "#{valid_count} valid, #{invalid_count} invalid"
+
+    exit(1) if invalid_count > 0
+  end
+
+  desc "Show details of a specific skill"
+  task :show, [:name] => :environment do |_, args|
+    name = args[:name]
+    unless name
+      puts "Usage: rake skills:show[skill-name]"
+      exit(1)
+    end
+
+    loader = RubyLlm::Skills.from_directory
+    skill = loader.find(name)
+
+    unless skill
+      puts "Skill '#{name}' not found"
+      exit(1)
+    end
+
+    puts "Name: #{skill.name}"
+    puts "Description: #{skill.description}"
+    puts "License: #{skill.license || "(none)"}"
+    puts "Compatibility: #{skill.compatibility || "(none)"}"
+    puts "Path: #{skill.path}"
+    puts "Valid: #{skill.valid? ? "yes" : "no"}"
+
+    unless skill.errors.empty?
+      puts ""
+      puts "Errors:"
+      skill.errors.each { |e| puts "  - #{e}" }
+    end
+
+    if skill.custom_metadata.any?
+      puts ""
+      puts "Metadata:"
+      skill.custom_metadata.each { |k, v| puts "  #{k}: #{v}" }
+    end
+
+    if skill.scripts.any?
+      puts ""
+      puts "Scripts:"
+      skill.scripts.each { |s| puts "  - #{File.basename(s)}" }
+    end
+
+    if skill.references.any?
+      puts ""
+      puts "References:"
+      skill.references.each { |r| puts "  - #{File.basename(r)}" }
+    end
+
+    if skill.assets.any?
+      puts ""
+      puts "Assets:"
+      skill.assets.each { |a| puts "  - #{File.basename(a)}" }
+    end
+  end
+end

data/lib/ruby_llm/skills/validator.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Validates skill structure according to the Agent Skills specification.
+    #
+    # Validation rules based on agentskills.io specification:
+    # - name: required, max 64 chars, lowercase + hyphens only, no leading/trailing hyphens
+    # - description: required, max 1024 chars
+    # - license: optional, max 128 chars
+    # - compatibility: optional, max 500 chars
+    #
+    # @example
+    #   errors = Validator.validate(skill)
+    #   puts errors # => [] if valid, or list of error messages
+    #
+    class Validator
+      NAME_MAX_LENGTH = 64
+      DESCRIPTION_MAX_LENGTH = 1024
+      LICENSE_MAX_LENGTH = 128
+      COMPATIBILITY_MAX_LENGTH = 500
+      NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+
+      class << self
+        # Validate a skill and return all errors.
+        #
+        # @param skill [Skill] skill to validate
+        # @return [Array<String>] list of error messages (empty if valid)
+        def validate(skill)
+          errors = []
+          validate_name(skill, errors)
+          validate_description(skill, errors)
+          validate_license(skill, errors)
+          validate_compatibility(skill, errors)
+          validate_path_name_match(skill, errors)
+          errors
+        end
+
+        # Check if a skill is valid.
+        #
+        # @param skill [Skill] skill to validate
+        # @return [Boolean] true if skill passes validation
+        def valid?(skill)
+          validate(skill).empty?
+        end
+
+        private
+
+        def validate_name(skill, errors)
+          name = skill.name
+
+          if name.nil? || name.empty?
+            errors << "name is required"
+            return
+          end
+
+          if name.length > NAME_MAX_LENGTH
+            errors << "name exceeds maximum length of #{NAME_MAX_LENGTH} characters"
+          end
+
+          unless name.match?(NAME_PATTERN)
+            errors << "name must be lowercase letters, numbers, and single hyphens (no leading/trailing hyphens)"
+          end
+        end
+
+        def validate_description(skill, errors)
+          description = skill.description
+
+          if description.nil? || description.empty?
+            errors << "description is required"
+            return
+          end
+
+          if description.length > DESCRIPTION_MAX_LENGTH
+            errors << "description exceeds maximum length of #{DESCRIPTION_MAX_LENGTH} characters"
+          end
+        end
+
+        def validate_license(skill, errors)
+          license = skill.license
+          return if license.nil? || license.empty?
+
+          if license.length > LICENSE_MAX_LENGTH
+            errors << "license exceeds maximum length of #{LICENSE_MAX_LENGTH} characters"
+          end
+        end
+
+        def validate_compatibility(skill, errors)
+          compatibility = skill.compatibility
+          return if compatibility.nil? || compatibility.empty?
+
+          if compatibility.length > COMPATIBILITY_MAX_LENGTH
+            errors << "compatibility exceeds maximum length of #{COMPATIBILITY_MAX_LENGTH} characters"
+          end
+        end
+
+        def validate_path_name_match(skill, errors)
+          return if skill.virtual?
+
+          dir_name = File.basename(skill.path)
+          return if skill.name == dir_name
+
+          errors << "name '#{skill.name}' does not match directory name '#{dir_name}'"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/skills/zip_loader.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "zip"
+
+module RubyLlm
+  module Skills
+    # Loads skills from a ZIP archive.
+    #
+    # The archive should contain skill directories at the root level,
+    # each with a SKILL.md file.
+    #
+    # Structure:
+    #   archive.zip
+    #   ├── skill-one/
+    #   │   ├── SKILL.md
+    #   │   └── scripts/
+    #   └── skill-two/
+    #       └── SKILL.md
+    #
+    # @example
+    #   loader = ZipLoader.new("skills.zip")
+    #   loader.list  # => [Skill, Skill, ...]
+    #
+    class ZipLoader < Loader
+      attr_reader :path
+
+      # Initialize with path to zip file.
+      #
+      # @param path [String] path to .zip archive
+      # @raise [LoadError] if file doesn't exist
+      def initialize(path)
+        super()
+        @path = path.to_s
+        raise LoadError, "Zip file not found: #{@path}" unless File.exist?(@path)
+      end
+
+      # List all skills from the archive.
+      #
+      # @return [Array<Skill>] skills found in archive
+      def list
+        skills
+      end
+
+      # Read content of a file within a skill's directory.
+      #
+      # @param skill_name [String] name of the skill
+      # @param relative_path [String] path relative to skill directory
+      # @return [String, nil] file content or nil if not found
+      def read_file(skill_name, relative_path)
+        entry_path = "#{skill_name}/#{relative_path}"
+        read_zip_entry(entry_path)
+      end
+
+      protected
+
+      def load_all
+        loaded_skills = []
+
+        Zip::File.open(@path) do |zip|
+          skill_dirs = find_skill_directories(zip)
+
+          skill_dirs.each do |skill_dir|
+            skill = load_skill_from_zip(zip, skill_dir)
+            loaded_skills << skill if skill
+          end
+        end
+
+        loaded_skills
+      rescue Zip::Error => e
+        raise LoadError, "Failed to read zip archive: #{e.message}"
+      end
+
+      private
+
+      def find_skill_directories(zip)
+        zip.entries
+          .select { |e| e.name.end_with?("/SKILL.md") }
+          .map { |e| File.dirname(e.name) }
+          .reject { |d| d.include?("/") } # Only top-level skills
+      end
+
+      def load_skill_from_zip(zip, skill_dir)
+        skill_md_path = "#{skill_dir}/SKILL.md"
+        entry = zip.find_entry(skill_md_path)
+        return nil unless entry
+
+        content = entry.get_input_stream.read
+        metadata = Parser.parse_string(content)
+        body = Parser.extract_body(content)
+
+        # Store content in metadata for virtual skill
+        metadata["__content__"] = body
+
+        # Store resource lists
+        metadata["__scripts__"] = list_resources(zip, skill_dir, "scripts")
+        metadata["__references__"] = list_resources(zip, skill_dir, "references")
+        metadata["__assets__"] = list_resources(zip, skill_dir, "assets")
+
+        Skill.new(
+          path: "zip:#{@path}:#{skill_dir}",
+          metadata: metadata
+        )
+      rescue ParseError => e
+        warn "Warning: Failed to parse #{skill_md_path}: #{e.message}" if RubyLlm::Skills.logger
+        nil
+      end
+
+      def list_resources(zip, skill_dir, subdir)
+        prefix = "#{skill_dir}/#{subdir}/"
+        zip.entries
+          .select { |e| e.name.start_with?(prefix) && !e.directory? }
+          .map { |e| e.name.sub(prefix, "") }
+          .reject { |f| f == ".keep" }
+          .sort
+      end
+
+      def read_zip_entry(entry_path)
+        Zip::File.open(@path) do |zip|
+          entry = zip.find_entry(entry_path)
+          return nil unless entry
+
+          entry.get_input_stream.read
+        end
+      rescue Zip::Error
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/skills.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "skills/version"
+require_relative "skills/error"
+require_relative "skills/parser"
+require_relative "skills/validator"
+require_relative "skills/skill"
+require_relative "skills/loader"
+require_relative "skills/filesystem_loader"
+require_relative "skills/composite_loader"
+require_relative "skills/skill_tool"
+require_relative "skills/chat_extensions"
+
+# Load Rails integration when Rails is available
+require_relative "skills/railtie" if defined?(Rails::Railtie)
+
+module RubyLlm
+  module Skills
+    class << self
+      attr_accessor :default_path, :logger
+
+      # Load skills from a filesystem directory.
+      #
+      # @param path [String] path to skills directory (defaults to default_path)
+      # @return [FilesystemLoader] loader for the directory
+      # @example
+      #   RubyLlm::Skills.from_directory("app/skills")
+      def from_directory(path = default_path)
+        FilesystemLoader.new(path)
+      end
+
+      # Load a single skill from a directory.
+      #
+      # @param path [String] path to skill directory (containing SKILL.md)
+      # @return [Skill] the loaded skill
+      # @raise [LoadError] if SKILL.md not found
+      # @example
+      #   RubyLlm::Skills.load("app/skills/my-skill")
+      def load(path)
+        skill_md = File.join(path, "SKILL.md")
+        raise LoadError, "SKILL.md not found in #{path}" unless File.exist?(skill_md)
+
+        metadata = Parser.parse_file(skill_md)
+        Skill.new(path: path, metadata: metadata)
+      end
+
+      # Load skills from a zip archive.
+      #
+      # @param path [String] path to .zip file
+      # @return [ZipLoader] loader for the archive
+      # @raise [LoadError] if rubyzip not available
+      # @example
+      #   RubyLlm::Skills.from_zip("skills.zip")
+      def from_zip(path)
+        require_relative "skills/zip_loader"
+        ZipLoader.new(path)
+      rescue ::LoadError
+        raise LoadError, "rubyzip gem required for zip support. Add 'gem \"rubyzip\"' to your Gemfile."
+      end
+
+      # Load skills from database records.
+      #
+      # @param records [ActiveRecord::Relation, Array] collection of skill records
+      # @return [DatabaseLoader] loader for the records
+      # @example
+      #   RubyLlm::Skills.from_database(Skill.where(active: true))
+      def from_database(records)
+        require_relative "skills/database_loader"
+        DatabaseLoader.new(records)
+      end
+
+      # Create a composite loader from multiple sources.
+      #
+      # @param loaders [Array<Loader>] loaders to combine
+      # @return [CompositeLoader] combined loader
+      # @example
+      #   RubyLlm::Skills.compose(
+      #     RubyLlm::Skills.from_directory("app/skills"),
+      #     RubyLlm::Skills.from_database(Skill.all)
+      #   )
+      def compose(*loaders)
+        require_relative "skills/composite_loader"
+        CompositeLoader.new(loaders)
+      end
+    end
+
+    self.default_path = "app/skills"
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-skills
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kieran Klaassen
+bindir: exe
+cert_chain: []
+date: 2026-01-16 00:00:00.000000000 Z
+dependencies: []
+description: Load, validate, and integrate Agent Skills with RubyLLM. Supports the
+  open Agent Skills specification for progressive skill discovery and loading from
+  filesystem, zip archives, and databases.
+email:
+- kieranklaassen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/skill/skill_generator.rb
+- lib/generators/skill/templates/SKILL.md.tt
+- lib/ruby_llm/skills.rb
+- lib/ruby_llm/skills/chat_extensions.rb
+- lib/ruby_llm/skills/composite_loader.rb
+- lib/ruby_llm/skills/database_loader.rb
+- lib/ruby_llm/skills/error.rb
+- lib/ruby_llm/skills/filesystem_loader.rb
+- lib/ruby_llm/skills/loader.rb
+- lib/ruby_llm/skills/parser.rb
+- lib/ruby_llm/skills/railtie.rb
+- lib/ruby_llm/skills/skill.rb
+- lib/ruby_llm/skills/skill_tool.rb
+- lib/ruby_llm/skills/tasks/skills.rake
+- lib/ruby_llm/skills/validator.rb
+- lib/ruby_llm/skills/version.rb
+- lib/ruby_llm/skills/zip_loader.rb
+homepage: https://github.com/kieranklaassen/ruby_llm-skills
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kieranklaassen/ruby_llm-skills
+  source_code_uri: https://github.com/kieranklaassen/ruby_llm-skills
+  changelog_uri: https://github.com/kieranklaassen/ruby_llm-skills/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Agent Skills extension for RubyLLM
+test_files: []