ruby_llm-skills 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39bffc3152e2a10d3f8000006e50d45748c30d6a04a71189ff0d52c61ada7984
+  data.tar.gz: 57a3d68ee3b3a1f47a9bbe7b18facc4ae52a12608d275428c37a02769d0a78db
+SHA512:
+  metadata.gz: 6aa5b23f9bcaaafeb00b073e031645e72671414eaa744c06eafbd6d66ff23d8023c4b384b5240a42013ae07c5a36b562c3b849b6f57c5ceee5bcc88ee7dfdfde
+  data.tar.gz: d1d4a88688857c09a4399dfcb336ea2b1191ba792689b27c796a7c803005900006b52a772656be3c1a6a6c21814bd3783392af538e4c8c2ca94103b399781487

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-15
+
+### Added
+
+- Initial release with full Agent Skills specification support
+- `Parser` - YAML frontmatter parsing with safe_load
+- `Skill` - Lazy loading for content and resources
+- `Validator` - Agent Skills spec validation rules
+- `FilesystemLoader` - Directory-based skill loading
+- `ZipLoader` - Archive-based skill loading (optional rubyzip dependency)
+- `DatabaseLoader` - Duck-typed record loading (text or binary storage)
+- `CompositeLoader` - Multi-source skill combination
+- `SkillTool` - RubyLLM tool with progressive disclosure via dynamic description
+- `ChatExtensions` - `with_skills()` and `with_skill_loader()` convenience methods
+- Rails integration with Railtie, generator, and rake tasks
+- Comprehensive test suite (142 tests)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kieran Klaassen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,396 @@
+# RubyLLM::Skills
+
+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)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ruby_llm-skills"
+```
+
+## Quick Start
+
+```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
+```
+
+## Validation
+
+Validate skills match the specification:
+
+```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: [...] }
+```
+
+## 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:
+
+```yaml
+---
+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.
+---
+
+# PDF Report Generator
+
+## Quick Start
+
+Use the bundled script for generation:
+
+```bash
+ruby scripts/generate.rb --input data.json --output report.pdf
+```
+
+## 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 |
+
+### Skill Directories
+
+```
+skill-name/
+├── SKILL.md           # Required - instructions
+├── scripts/           # Optional - executable code
+├── references/        # Optional - additional docs
+└── assets/            # Optional - templates, images
+```
+
+### Best Practices
+
+**Keep SKILL.md under 500 lines.** Move detailed content to `references/`.
+
+**Write good descriptions.** Include both what the skill does AND when to use it:
+
+```yaml
+# Good
+description: Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction.
+
+# Bad
+description: PDF helper.
+```
+
+**Use scripts for deterministic operations.** Scripts execute without loading into context.
+
+**One level of references.** Avoid deeply nested file chains.
+
+## Development
+
+```bash
+git clone https://github.com/kieranklaassen/ruby_llm-skills.git
+cd ruby_llm-skills
+bundle install
+bundle exec rake test
+```
+
+## 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)

data/lib/generators/skill/skill_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+class SkillGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  class_option :description, type: :string, default: "Description of what this skill does"
+  class_option :license, type: :string, default: nil
+  class_option :scripts, type: :boolean, default: false
+  class_option :references, type: :boolean, default: false
+  class_option :assets, type: :boolean, default: false
+
+  def create_skill_directory
+    empty_directory skill_path
+  end
+
+  def create_skill_md
+    template "SKILL.md.tt", File.join(skill_path, "SKILL.md")
+  end
+
+  def create_scripts_directory
+    return unless options[:scripts]
+
+    empty_directory File.join(skill_path, "scripts")
+    create_file File.join(skill_path, "scripts", ".keep")
+  end
+
+  def create_references_directory
+    return unless options[:references]
+
+    empty_directory File.join(skill_path, "references")
+    create_file File.join(skill_path, "references", ".keep")
+  end
+
+  def create_assets_directory
+    return unless options[:assets]
+
+    empty_directory File.join(skill_path, "assets")
+    create_file File.join(skill_path, "assets", ".keep")
+  end
+
+  private
+
+  def skill_path
+    File.join("app", "skills", skill_name)
+  end
+
+  def skill_name
+    file_name.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "")
+  end
+
+  def skill_description
+    options[:description]
+  end
+
+  def skill_license
+    options[:license]
+  end
+end

data/lib/generators/skill/templates/SKILL.md.tt

@@ -0,0 +1,21 @@
+---
+name: <%= skill_name %>
+description: <%= skill_description %>
+<% if skill_license -%>
+license: <%= skill_license %>
+<% end -%>
+---
+
+# <%= skill_name.split("-").map(&:capitalize).join(" ") %>
+
+Instructions for using this skill.
+
+## When to Use
+
+Use this skill when...
+
+## Steps
+
+1. First step
+2. Second step
+3. Third step

data/lib/ruby_llm/skills/chat_extensions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+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
+    #   chat = RubyLlm.chat
+    #   chat.with_skills("app/skills")
+    #   chat.ask("Generate a PDF report")
+    #
+    module ChatExtensions
+      # Add skills from a directory to this chat.
+      #
+      # @param path [String] path to skills directory
+      # @return [self] for chaining
+      # @example
+      #   chat.with_skills("app/skills")
+      def with_skills(path = RubyLlm::Skills.default_path)
+        loader = RubyLlm::Skills.from_directory(path)
+        skill_tool = RubyLlm::Skills::SkillTool.new(loader)
+        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)
+      end
+    end
+  end
+end
+
+# Extend RubyLLM::Chat if available
+if defined?(RubyLlm::Chat)
+  RubyLlm::Chat.include(RubyLlm::Skills::ChatExtensions)
+end

data/lib/ruby_llm/skills/composite_loader.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLlm
+  module Skills
+    # Combines multiple loaders into a single source.
+    #
+    # Skills are searched in order, with earlier loaders taking precedence.
+    # This allows layering skills from multiple sources (filesystem, database, etc).
+    #
+    # @example
+    #   composite = CompositeLoader.new([
+    #     FilesystemLoader.new("app/skills"),
+    #     DatabaseLoader.new(Skill.all)
+    #   ])
+    #   composite.list  # => skills from all loaders
+    #
+    class CompositeLoader < Loader
+      attr_reader :loaders
+
+      # Initialize with an array of loaders.
+      #
+      # @param loaders [Array<Loader>] loaders to combine
+      def initialize(loaders)
+        super()
+        @loaders = loaders
+      end
+
+      # List all skills from all loaders.
+      # Skills are deduplicated by name, with earlier loaders taking precedence.
+      #
+      # @return [Array<Skill>] combined list of skills
+      def list
+        skills
+      end
+
+      # Reload all loaders.
+      #
+      # @return [self]
+      def reload!
+        @loaders.each(&:reload!)
+        super
+      end
+
+      protected
+
+      def load_all
+        seen = {}
+        @loaders.flat_map(&:list).each_with_object([]) do |skill, result|
+          next if seen[skill.name]
+
+          seen[skill.name] = true
+          result << skill
+        end
+      end
+    end
+  end
+end