ruby_llm-skills 0.1.0 → 0.3.0

data/lib/ruby_llm/skills/skill_tool.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-module RubyLlm
+require "ruby_llm"
+
+module RubyLLM
   module Skills
     # A RubyLLM Tool that enables progressive skill loading.
     #
@@ -15,15 +17,23 @@ module RubyLlm
     # 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)
+    #   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
+    class SkillTool < RubyLLM::Tool
+      description "Execute a skill within the main conversation."
+      param :command, type: "string",
+        desc: "The skill name (e.g., 'pdf' or 'write-poem')"
+      param :arguments, type: "string", required: false,
+        desc: "Arguments passed after the command (e.g., '/write-poem about robots' passes 'about robots')"
+      param :resource, type: "string", required: false,
+        desc: "Optional resource path to load (e.g., 'scripts/helper.rb', 'references/guide.md')"
+
       attr_reader :loader
 
       # Initialize with a skill loader.
@@ -44,51 +54,41 @@ module RubyLlm
       #
       # @return [String] tool description with embedded skill metadata
       def description
+        base_description = self.class.description
         skills_xml = build_skills_xml
         <<~DESC.strip
-          Load a skill to get specialized instructions for a task.
+          #{base_description}
 
-          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.
+          When to use this tool:
+          - When the user's message starts with "/" followed by a skill name (e.g., "/write-poem about robots"), invoke this tool with that command and pass any text after the command name as arguments
+          - When the user's request matches one of the available skills below
+
+          Call with command (and optional arguments) to get the full skill instructions.
+          Call with command and resource to load a specific file (script, reference, or asset).
 
           #{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.
+      # Execute the tool to load a skill's content or a specific resource.
       #
-      # @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)
+      # @param command [String] name of skill to load
+      # @param arguments [String, nil] optional arguments passed with the command
+      # @param resource [String, nil] optional resource path within the skill
+      # @return [String] skill content, resource content, or error message
+      def execute(command:, arguments: nil, resource: nil)
+        skill = @loader.find(command)
 
         unless skill
           available = @loader.list.map(&:name).join(", ")
-          return "Skill '#{skill_name}' not found. Available skills: #{available}"
+          return "Skill '#{command}' 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)
+        if resource
+          load_resource(skill, resource)
+        else
+          build_skill_response(skill, arguments: arguments)
+        end
       end
 
       # Convert to RubyLLM Tool-compatible format.
@@ -98,7 +98,7 @@ module RubyLlm
         {
           name: name,
           description: description,
-          parameters: parameters
+          parameters: params_schema
         }
       end
 
@@ -122,29 +122,41 @@ module RubyLlm
         xml_parts.join("\n")
       end
 
-      def build_skill_response(skill)
+      def build_skill_response(skill, arguments: nil)
         parts = []
         parts << "# Skill: #{skill.name}"
+        if arguments && !arguments.strip.empty?
+          parts << "# Arguments: #{arguments}"
+        end
         parts << ""
         parts << skill.content
         parts << ""
 
         # Include resource information if available
+        has_resources = skill.scripts.any? || skill.references.any? || skill.assets.any?
+
         if skill.scripts.any?
           parts << "## Available Scripts"
-          skill.scripts.each { |s| parts << "- #{File.basename(s)}" }
+          skill.scripts.each { |s| parts << "- scripts/#{File.basename(s)}" }
           parts << ""
         end
 
         if skill.references.any?
           parts << "## Available References"
-          skill.references.each { |r| parts << "- #{File.basename(r)}" }
+          skill.references.each { |r| parts << "- references/#{File.basename(r)}" }
           parts << ""
         end
 
         if skill.assets.any?
           parts << "## Available Assets"
-          skill.assets.each { |a| parts << "- #{File.basename(a)}" }
+          skill.assets.each { |a| parts << "- assets/#{File.basename(a)}" }
+          parts << ""
+        end
+
+        if has_resources
+          parts << "---"
+          parts << "To load a resource, call this tool again with resource parameter."
+          parts << "Example: command=\"#{skill.name}\", resource=\"scripts/example.rb\""
           parts << ""
         end
 
@@ -161,6 +173,36 @@ module RubyLlm
           .gsub('"', "&quot;")
           .gsub("'", "&apos;")
       end
+
+      def load_resource(skill, resource_path)
+        return "Cannot load resources from virtual skills" if skill.virtual?
+
+        # Prevent path traversal
+        if resource_path.include?("..") || resource_path.start_with?("/")
+          return "Invalid resource path: #{resource_path}"
+        end
+
+        full_path = File.join(skill.path, resource_path)
+
+        unless File.exist?(full_path)
+          available = list_available_resources(skill)
+          return "Resource '#{resource_path}' not found in skill '#{skill.name}'. Available: #{available}"
+        end
+
+        unless File.file?(full_path)
+          return "Resource '#{resource_path}' is not a file"
+        end
+
+        content = File.read(full_path)
+        "# Resource: #{resource_path}\n\n#{content}"
+      end
+
+      def list_available_resources(skill)
+        resources = skill.scripts + skill.references + skill.assets
+        return "none" if resources.empty?
+
+        resources.map { |r| r.sub("#{skill.path}/", "") }.join(", ")
+      end
     end
   end
 end

data/lib/ruby_llm/skills/validator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Skills
     # Validates skill structure according to the Agent Skills specification.
     #

data/lib/ruby_llm/skills/version.rb

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

data/lib/ruby_llm/skills.rb

@@ -1,5 +1,52 @@
 # frozen_string_literal: true
 
+# RubyLLM 1.12.0 Agent uses `delegate` but doesn't require ActiveSupport.
+# Provide a minimal fallback for plain Ruby environments.
+unless Module.method_defined?(:delegate)
+  class Module
+    def delegate(*methods, to:, prefix: nil, allow_nil: false, private: false, **_options)
+      target_method = to.to_sym
+
+      methods.each do |method_name|
+        delegated_method = delegated_method_name(method_name, target_method, prefix)
+
+        define_method(delegated_method) do |*args, **kwargs, &block|
+          target = public_send(target_method)
+          if target.nil?
+            return nil if allow_nil
+
+            raise NoMethodError,
+              "#{self.class}##{delegated_method} delegated to ##{target_method}, but ##{target_method} is nil"
+          end
+
+          if kwargs.empty?
+            target.public_send(method_name, *args, &block)
+          else
+            target.public_send(method_name, *args, **kwargs, &block)
+          end
+        end
+
+        private delegated_method if binding.local_variable_get(:private)
+      end
+    end
+
+    private
+
+    def delegated_method_name(method_name, target_method, prefix)
+      case prefix
+      when true
+        :"#{target_method}_#{method_name}"
+      when String, Symbol
+        :"#{prefix}_#{method_name}"
+      else
+        method_name
+      end
+    end
+  end
+end
+
+require "ruby_llm"
+
 require_relative "skills/version"
 require_relative "skills/error"
 require_relative "skills/parser"
@@ -7,24 +54,27 @@ 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"
+require_relative "skills/agent_extensions"
 
 # Load Rails integration when Rails is available
 require_relative "skills/railtie" if defined?(Rails::Railtie)
 
-module RubyLlm
+# Extend RubyLLM::Chat with skill methods
+RubyLLM::Chat.include(RubyLLM::Skills::ChatExtensions)
+RubyLLM::Agent.include(RubyLLM::Skills::AgentExtensions)
+
+module RubyLLM
   module Skills
     class << self
-      attr_accessor :default_path, :logger
+      attr_accessor :default_path
 
       # 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")
+      #   RubyLLM::Skills.from_directory("app/skills")
       def from_directory(path = default_path)
         FilesystemLoader.new(path)
       end
@@ -35,7 +85,7 @@ module RubyLlm
       # @return [Skill] the loaded skill
       # @raise [LoadError] if SKILL.md not found
       # @example
-      #   RubyLlm::Skills.load("app/skills/my-skill")
+      #   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)
@@ -44,26 +94,12 @@ module RubyLlm
         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))
+      #   RubyLLM::Skills.from_database(Skill.where(active: true))
       def from_database(records)
         require_relative "skills/database_loader"
         DatabaseLoader.new(records)
@@ -74,9 +110,9 @@ module RubyLlm
       # @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)
+      #   RubyLLM::Skills.compose(
+      #     RubyLLM::Skills.from_directory("app/skills"),
+      #     RubyLLM::Skills.from_database(Skill.all)
       #   )
       def compose(*loaders)
         require_relative "skills/composite_loader"

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-skills
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kieran Klaassen
 bindir: exe
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
-dependencies: []
+date: 2026-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
 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.
@@ -21,9 +35,11 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/skill/USAGE
 - lib/generators/skill/skill_generator.rb
 - lib/generators/skill/templates/SKILL.md.tt
 - lib/ruby_llm/skills.rb
+- lib/ruby_llm/skills/agent_extensions.rb
 - lib/ruby_llm/skills/chat_extensions.rb
 - lib/ruby_llm/skills/composite_loader.rb
 - lib/ruby_llm/skills/database_loader.rb
@@ -37,7 +53,6 @@ files:
 - 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
@@ -53,7 +68,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/ruby_llm/skills/zip_loader.rb

@@ -1,129 +0,0 @@
-# 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