ruby_llm-skills 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39bffc3152e2a10d3f8000006e50d45748c30d6a04a71189ff0d52c61ada7984
-  data.tar.gz: 57a3d68ee3b3a1f47a9bbe7b18facc4ae52a12608d275428c37a02769d0a78db
+  metadata.gz: 676c58cfd47ff3e3bbf9a8eeac47658c56f2537d189eef7f2743740b8c44afb8
+  data.tar.gz: b54d6857a8340b9aab46a37e6385296acd6190987ef816172f96b265a4378d72
 SHA512:
-  metadata.gz: 6aa5b23f9bcaaafeb00b073e031645e72671414eaa744c06eafbd6d66ff23d8023c4b384b5240a42013ae07c5a36b562c3b849b6f57c5ceee5bcc88ee7dfdfde
-  data.tar.gz: d1d4a88688857c09a4399dfcb336ea2b1191ba792689b27c796a7c803005900006b52a772656be3c1a6a6c21814bd3783392af538e4c8c2ca94103b399781487
+  metadata.gz: 22da0df8891691181c0db718da07e3b44ad1ca1cbd04d3991350e5f7fff9996390493a5f047833ff978b8798f447172cfc7f7ddbdffe1871054e61cea40709f0
+  data.tar.gz: 0a48577bdb85af0d6a1216857fbdb9e4389a2121f271bdc48cff4f35324be2854563b8934d62064667fd1b829959e3e595c05d8be7bd5475b7d6797a36cf992d

data/README.md

@@ -2,15 +2,12 @@
 
 Agent Skills for [RubyLLM](https://github.com/crmne/ruby_llm). Teach your AI how to do things your way.
 
-Skills are folders of instructions, scripts, and resources that extend LLM capabilities for specialized tasks. This gem implements the [Agent Skills specification](https://agentskills.io/specification) for RubyLLM.
-
 [![Gem Version](https://badge.fury.io/rb/ruby_llm-skills.svg)](https://badge.fury.io/rb/ruby_llm-skills)
 [![CI](https://github.com/kieranklaassen/ruby_llm-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/kieranklaassen/ruby_llm-skills/actions)
+[![Compound Engineered](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem "ruby_llm-skills"
 ```
@@ -19,378 +16,91 @@ gem "ruby_llm-skills"
 
 ```ruby
 chat = RubyLLM.chat
-chat.with_skills              # Load skills from app/skills
-chat.ask "Create a PDF report from this data"
-```
-
-That's it. Skills are discovered automatically and injected into the system prompt.
-
-## How It Works
-
-Skills follow a three-level progressive disclosure pattern:
-
-1. **Metadata** - Name and description loaded at startup (~100 tokens per skill)
-2. **Instructions** - Full SKILL.md loaded when skill triggers
-3. **Resources** - Scripts and references loaded on demand
-
-This keeps context lean while making capabilities available.
-
-## Configuration
-
-```ruby
-RubyLLM::Skills.default_path = "lib/skills"   # Default: app/skills
-RubyLLM::Skills.logger = Rails.logger         # Default: nil
-```
-
-## Loading Skills
-
-### From Filesystem (Default)
-
-```ruby
-# Load from default path (app/skills)
 chat.with_skills
-
-# Load from specific directory
-chat.with_skills(from: "lib/skills")
-
-# Load specific skills only
-chat.with_skills(only: [:pdf_report, :data_analysis])
-```
-
-### From Multiple Sources
-
-Pass an array to load from multiple locations:
-
-```ruby
-chat.with_skills(from: [
-  "app/skills",                # Directory
-  "extras/skills.zip",         # Zip file
-  current_user.skills          # ActiveRecord relation
-])
-```
-
-Sources are loaded in order. Later skills with the same name override earlier ones.
-
-### From Database
-
-Store complete skills in your database for per-user customization. Two storage formats are supported:
-
-**Option A: Store as text (SKILL.md content)**
-
-```ruby
-# Migration
-create_table :skills do |t|
-  t.string :name, null: false
-  t.text :description, null: false
-  t.text :content, null: false  # Full SKILL.md content
-  t.references :user
-  t.timestamps
-end
-
-# Model
-class Skill < ApplicationRecord
-  belongs_to :user, optional: true
-
-  validates :name, format: { with: /\A[a-z0-9-]+\z/ }
-end
-
-# Create a skill
-current_user.skills.create!(
-  name: "my-workflow",
-  description: "Custom workflow for data processing",
-  content: <<~SKILL
-    # My Workflow
-
-    ## Steps
-    1. Load the data
-    2. Process with custom rules
-    3. Export results
-  SKILL
-)
-```
-
-**Option B: Store as binary (zip file)**
-
-For skills with scripts, references, or assets:
-
-```ruby
-# Migration
-create_table :skills do |t|
-  t.string :name, null: false
-  t.text :description, null: false
-  t.binary :data, null: false  # Zip file blob
-  t.references :user
-  t.timestamps
-end
-
-# Model
-class Skill < ApplicationRecord
-  belongs_to :user, optional: true
-end
-
-# Upload a skill zip
-skill_zip = File.read("my-skill.zip")
-current_user.skills.create!(
-  name: "pdf-report",
-  description: "Generate PDF reports with charts",
-  data: skill_zip
-)
-```
-
-**Loading database skills**
-
-```ruby
-# Combine app skills with user's custom skills
-chat.with_skills(from: [
-  "app/skills",           # Base skills from filesystem
-  current_user.skills     # User's skills from database
-])
-```
-
-The gem detects the storage format automatically:
-- Records with `content` field → parsed as SKILL.md text
-- Records with `data` field → extracted as zip
-
-### From Zip Files
-
-```ruby
-chat.with_skills(from: "skills.zip")
-chat.with_skills(from: ["core.zip", "custom.zip"])
-```
-
-### Source Detection
-
-The gem auto-detects source type:
-
-| Input | Type |
-|-------|------|
-| String ending in `/` or directory path | Filesystem |
-| String ending in `.zip` | Zip file |
-| ActiveRecord relation or array of objects | Database |
-
-## Rails Integration
-
-Skills load automatically via Railtie. No configuration needed.
-
-```ruby
-# app/skills/ is scanned at boot
-# Skills available on any RubyLLM chat
-
-class ReportsController < ApplicationController
-  def create
-    chat = RubyLLM.chat
-    chat.with_skills  # Already has app/skills loaded
-    chat.ask "Generate quarterly report from #{@data}"
-  end
-end
-```
-
-### Per-User Skills with ActiveRecord
-
-```ruby
-class User < ApplicationRecord
-  has_many :skills
-end
-
-class Skill < ApplicationRecord
-  belongs_to :user, optional: true
-
-  validates :name, presence: true,
-    format: { with: /\A[a-z0-9-]+\z/ },
-    length: { maximum: 64 }
-  validates :description, presence: true,
-    length: { maximum: 1024 }
-  validates :content, presence: true
-end
-```
-
-## Skill Discovery
-
-Skills are injected into the system prompt as available tools:
-
-```xml
-<available_skills>
-<skill>
-  <name>pdf-report</name>
-  <description>Generate PDF reports with charts...</description>
-  <location>app/skills/pdf-report</location>
-</skill>
-</available_skills>
-```
-
-When the LLM determines a skill is relevant, it reads the full `SKILL.md` into context.
-
-## API Reference
-
-### RubyLLM::Skills
-
-```ruby
-RubyLLM::Skills.default_path      # Get/set default skills directory
-RubyLLM::Skills.logger            # Get/set logger
-RubyLLM::Skills.load(from:)       # Load skills from path/database/zip
-RubyLLM::Skills.validate(skill)   # Validate skill structure
-```
-
-### RubyLLM::Skills::Skill
-
-```ruby
-skill = RubyLLM::Skills.find("pdf-report")
-
-skill.name                    # "pdf-report"
-skill.description             # "Generate PDF reports..."
-skill.content                 # Full SKILL.md content
-skill.path                    # Filesystem path
-skill.metadata                # Parsed frontmatter hash
-skill.references              # Array of reference files
-skill.scripts                 # Array of script files
-skill.assets                  # Array of asset files
-skill.valid?                  # Validates structure
-```
-
-### Chat Integration
-
-```ruby
-chat = RubyLLM.chat
-
-chat.with_skills                    # Load default skills
-chat.with_skills(only: [:name])     # Load specific skills
-chat.with_skills(except: [:name])   # Exclude skills
-chat.with_skills(from: records)     # Load from database
-chat.skills                         # List loaded skills
-chat.skill_metadata                 # Get metadata for prompt
+chat.ask "Create a PDF report from this data"
 ```
 
-## Validation
+The LLM discovers skills, calls the skill tool, and gets instructions.
 
-Validate skills match the specification:
+## Usage
 
 ```ruby
-skill = RubyLLM::Skills.find("my-skill")
-skill.valid?  # => true/false
-skill.errors  # => ["name contains uppercase"]
-
-# Validate all skills
-RubyLLM::Skills.validate_all
-# => { valid: [...], invalid: [...] }
+chat.with_skills                              # app/skills (default)
+chat.with_skills("lib/skills")                # custom path
+chat.with_skills("app/skills", "app/commands") # multiple paths
+chat.with_skills("app/skills", user.skills)   # with database records
 ```
 
-## Provider Support
-
-Skills work with any RubyLLM provider. The skill metadata is injected into the system prompt, so any model that supports system prompts can use skills.
-
-Tested with: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Ollama.
-
-## Comparison with MCP
-
-| Feature | Skills | MCP |
-|---------|--------|-----|
-| Execution | Prompt-based | Tool-based |
-| Setup | Drop in folder | Server config |
-| Context | Progressive disclosure | Always available |
-| Best for | Domain knowledge | External integrations |
-
-Use skills for specialized instructions. Use [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) for external tool integrations. They compose well together.
-
 ## Creating Skills
 
-Create a folder with a `SKILL.md` file:
-
 ```
 app/skills/
 └── pdf-report/
     ├── SKILL.md
     ├── scripts/
-    │   └── generate.rb
     └── references/
-        └── templates.md
 ```
 
-The `SKILL.md` requires YAML frontmatter:
+SKILL.md requires frontmatter:
 
-```yaml
+```markdown
 ---
 name: pdf-report
-description: Generate PDF reports with charts and tables. Use when asked to create reports, export data to PDF, or generate printable documents.
+description: Generate PDF reports. Use when asked to create reports or export to PDF.
 ---
 
 # PDF Report Generator
 
-## Quick Start
-
-Use the bundled script for generation:
-
-```bash
-ruby scripts/generate.rb --input data.json --output report.pdf
+Instructions here...
 ```
 
-## Guidelines
-
-- Always include page numbers
-- Use company logo from assets/
-```
-
-### Frontmatter Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Lowercase, hyphens only. Max 64 chars. |
-| `description` | Yes | What it does AND when to use it. Max 1024 chars. |
-| `license` | No | License identifier |
-| `compatibility` | No | Environment requirements |
-| `metadata` | No | Custom key-value pairs |
+## Slash Commands
 
-### Skill Directories
+Single-file skills work as commands:
 
 ```
-skill-name/
-├── SKILL.md           # Required - instructions
-├── scripts/           # Optional - executable code
-├── references/        # Optional - additional docs
-└── assets/            # Optional - templates, images
+app/commands/
+├── write-poem.md
+└── review-code.md
 ```
 
-### Best Practices
+```ruby
+chat.with_skills("app/skills", "app/commands")
+chat.ask "/write-poem about robots"
+```
 
-**Keep SKILL.md under 500 lines.** Move detailed content to `references/`.
+## Database Skills
 
-**Write good descriptions.** Include both what the skill does AND when to use it:
+Store skills or commands in your database:
 
-```yaml
-# Good
-description: Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction.
+```ruby
+create_table :skills do |t|
+  t.string :name, null: false
+  t.text :description, null: false
+  t.text :content, null: false  # SKILL.md body
+  t.references :user
+  t.timestamps
+end
 
-# Bad
-description: PDF helper.
+chat.with_skills(user.skills)
+chat.ask "/my-command args"  # works as command too
 ```
 
-**Use scripts for deterministic operations.** Scripts execute without loading into context.
+Records must respond to `#name`, `#description`, and `#content`. For skills with scripts/references, use filesystem skills.
 
-**One level of references.** Avoid deeply nested file chains.
+## Rails
 
-## Development
+Default path auto-configured to `Rails.root/app/skills`.
 
 ```bash
-git clone https://github.com/kieranklaassen/ruby_llm-skills.git
-cd ruby_llm-skills
-bundle install
-bundle exec rake test
+rails generate skill pdf-report --description "Generate PDF reports"
 ```
 
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-feature`)
-3. Commit your changes (`git commit -am 'Add feature'`)
-4. Push to the branch (`git push origin my-feature`)
-5. Create a Pull Request
-
-## License
-
-MIT License. See [LICENSE](LICENSE) for details.
-
 ## Resources
 
 - [Agent Skills Specification](https://agentskills.io/specification)
-- [Anthropic Skills Repository](https://github.com/anthropics/skills)
 - [RubyLLM](https://github.com/crmne/ruby_llm)
-- [RubyLLM::MCP](https://github.com/patvice/ruby_llm-mcp)
+
+## License
+
+MIT

data/lib/ruby_llm/skills/chat_extensions.rb

@@ -1,49 +1,91 @@
 # frozen_string_literal: true
 
+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)
+      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) { s.respond_to?(:to_a) && s.first&.respond_to?(:name) && s.first.respond_to?(:content) }
+          RubyLlm::Skills.from_database(source)
+        else
+          source
+        end
       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/database_loader.rb

@@ -2,45 +2,26 @@
 
 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/filesystem_loader.rb

@@ -4,12 +4,18 @@ 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/railtie.rb

@@ -20,6 +20,15 @@ module RubyLlm
         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
+
       # Provide rake tasks
       rake_tasks do
         load File.expand_path("tasks/skills.rake", __dir__)

data/lib/ruby_llm/skills/skill.rb

@@ -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?
 

data/lib/ruby_llm/skills/skill_tool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ruby_llm"
+
 module RubyLlm
   module Skills
     # A RubyLLM Tool that enables progressive skill loading.
@@ -23,7 +25,15 @@ module RubyLlm
     #   # 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/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLlm
   module Skills
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ruby_llm/skills.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ruby_llm"
+
 require_relative "skills/version"
 require_relative "skills/error"
 require_relative "skills/parser"
@@ -7,17 +9,18 @@ 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)
 
+# Extend RubyLLM::Chat with skill methods
+RubyLLM::Chat.include(RubyLlm::Skills::ChatExtensions)
+
 module RubyLlm
   module Skills
     class << self
-      attr_accessor :default_path, :logger
+      attr_accessor :default_path
 
       # Load skills from a filesystem directory.
       #
@@ -44,20 +47,6 @@ 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

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-skills
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kieran Klaassen
 bindir: exe
 cert_chain: []
 date: 2026-01-16 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
 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.
@@ -37,7 +51,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 +66,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