ruby_llm-skills 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39bffc3152e2a10d3f8000006e50d45748c30d6a04a71189ff0d52c61ada7984
-  data.tar.gz: 57a3d68ee3b3a1f47a9bbe7b18facc4ae52a12608d275428c37a02769d0a78db
+  metadata.gz: '048ac6f6a76a7fd48994d208799b967754b25ecc3959acd56d44f5ab707f9f8d'
+  data.tar.gz: 268827da6d73359d9451b159b1abe68dea7881419df6b473cceeb2d8c74bc073
 SHA512:
-  metadata.gz: 6aa5b23f9bcaaafeb00b073e031645e72671414eaa744c06eafbd6d66ff23d8023c4b384b5240a42013ae07c5a36b562c3b849b6f57c5ceee5bcc88ee7dfdfde
-  data.tar.gz: d1d4a88688857c09a4399dfcb336ea2b1191ba792689b27c796a7c803005900006b52a772656be3c1a6a6c21814bd3783392af538e4c8c2ca94103b399781487
+  metadata.gz: febe501ab666f7e1cdf06e043ab44305ea065ffe561508b6fdcb9a959a90eabad8d2cb9fcc90384536eaf0871f73f2e52c3c9e93b8d883fbe8823274f547f0f3
+  data.tar.gz: 73226c3f1eb42ba6073dbfdcccb9f334896e078ca04ab1814260feb4218d432a83cf92817a32bb6c1abe847cf7fcd0098259aa2bab5886ce933d2c258d4ae8f1

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.3.0] - 2026-02-17
+
+### Added
+
+- `RubyLLM::Agent` integration via `RubyLLM::Skills::AgentExtensions`
+- Class-level `skills` DSL on agent subclasses with source, `only:`, and proc support
+- Instance-level `with_skills` for runtime agent skill configuration
+- Agent-specific unit and integration test coverage
+- Compatibility tests for delegate fallback behavior
+
+### Changed
+
+- Tightened `ruby_llm` dependency from open lower bound to `~> 1.12`
+- Added explicit runtime compatibility checks for required `RubyLLM::Agent` hooks
+- Documented `agent.with_skills(...)` replacement semantics in README
+
+### Fixed
+
+- Dynamic skill blocks resolving to `nil` or `[]` no longer silently load default skills
+- Skill source normalization and validation now prevent nested/invalid source runtime crashes
+- Delegate fallback now supports common delegation options (`prefix`, `allow_nil`, `private`)
+
 ## [0.1.0] - 2025-01-15
 
 ### Added

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,142 @@ 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"])
+chat.ask "Create a PDF report from this data"
 ```
 
-### Source Detection
+The LLM discovers skills, calls the skill tool, and gets instructions.
 
-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.
+## Usage
 
 ```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
+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
 ```
 
-### Per-User Skills with ActiveRecord
+### With RubyLLM::Agent (v1.12+)
 
 ```ruby
-class User < ApplicationRecord
-  has_many :skills
+class SupportAgent < RubyLLM::Agent
+  model "gpt-5-nano"
+  instructions "You are a support assistant."
+  skills "app/skills", only: [:faq, :troubleshooting]
 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:
+chat = SupportAgent.chat
+chat.ask("How do I reset my password?")
 
-```xml
-<available_skills>
-<skill>
-  <name>pdf-report</name>
-  <description>Generate PDF reports with charts...</description>
-  <location>app/skills/pdf-report</location>
-</skill>
-</available_skills>
+agent = SupportAgent.new
+agent.with_skills("extra/skills")
+agent.ask("What can you help with?")
 ```
 
-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.
+`agent.with_skills(...)` replaces the current skill tool configuration.
+To combine sources, pass all sources in a single `skills`/`with_skills` call.
 
 ## 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
+Instructions here...
+```
 
-Use the bundled script for generation:
+## Slash Commands
 
-```bash
-ruby scripts/generate.rb --input data.json --output report.pdf
-```
+Single-file skills work as commands:
 
-## Guidelines
+```
+app/commands/
+├── write-poem.md
+└── review-code.md
+```
 
-- Always include page numbers
-- Use company logo from assets/
+```ruby
+chat.with_skills("app/skills", "app/commands")
+chat.ask "/write-poem about robots"
 ```
 
-### Frontmatter Fields
+## Database Skills
 
-| 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 |
+Store skills or commands in your database:
 
-### Skill Directories
+```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
 
+chat.with_skills(user.skills)
+chat.ask "/my-command args"  # works as command too
 ```
-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/`.
+Records must respond to `#name`, `#description`, and `#content`. For skills with scripts/references, use filesystem skills.
 
-**Write good descriptions.** Include both what the skill does AND when to use it:
+## Rails
 
-```yaml
-# Good
-description: Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction.
+Default path auto-configured to `Rails.root/app/skills`.
 
-# Bad
-description: PDF helper.
+```bash
+rails generate skill pdf-report --description "Generate PDF reports"
 ```
 
-**Use scripts for deterministic operations.** Scripts execute without loading into context.
+## Development
 
-**One level of references.** Avoid deeply nested file chains.
+### Setup
 
-## Development
+```bash
+bin/setup
+```
+
+### Running Tests
 
 ```bash
-git clone https://github.com/kieranklaassen/ruby_llm-skills.git
-cd ruby_llm-skills
-bundle install
-bundle exec rake test
+bundle exec rake test        # Unit tests (151 tests)
+bundle exec rake test_rails  # Rails integration tests (25+ tests)
+bundle exec rake test_all    # Both
+bundle exec rake             # Tests + linting
 ```
 
-## Contributing
+### Dummy Rails App
 
-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
+A minimal Rails 8 app at `test/dummy/` tests Rails integration:
 
-## License
+- **Filesystem skills**: `app/skills/greeting/` tests directory-based loading
+- **Database skills**: `Skill` model tests ActiveRecord-based loading
+- **Generator tests**: Tests for `rails generate skill`
+- **Composite loading**: Tests combining filesystem + database sources
 
-MIT License. See [LICENSE](LICENSE) for details.
+```bash
+cd test/dummy
+bundle exec rails test  # Run Rails tests directly
+```
 
 ## 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/generators/skill/USAGE

@@ -0,0 +1,29 @@
+Description:
+    Creates a new Agent Skill following the agentskills.io specification.
+    Skills are stored in app/skills/ and contain a SKILL.md file with
+    YAML frontmatter (name, description) and markdown instructions.
+
+Example:
+    rails generate skill pdf-report --description "Generate PDF reports"
+
+    This creates:
+        app/skills/pdf-report/
+        app/skills/pdf-report/SKILL.md
+
+    With optional directories:
+        --scripts     Creates scripts/ directory for executable code
+        --references  Creates references/ directory for documentation
+        --assets      Creates assets/ directory for templates/images
+
+Full Example:
+    rails generate skill data-export -d "Export data to CSV/JSON. Use when asked to export or download data." --scripts --assets
+
+    This creates:
+        app/skills/data-export/
+        app/skills/data-export/SKILL.md
+        app/skills/data-export/scripts/.keep
+        app/skills/data-export/assets/.keep
+
+Note:
+    The description should include both what the skill does AND when to use it.
+    Example: "Generate PDF reports from data. Use when asked to create reports or export to PDF."

data/lib/generators/skill/skill_generator.rb

@@ -5,11 +5,16 @@ 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
+  class_option :description, type: :string, default: "Description of what this skill does. Use when...",
+    aliases: "-d", desc: "Short description of the skill (max 1024 chars)"
+  class_option :license, type: :string, default: nil,
+    aliases: "-l", desc: "License identifier (e.g., MIT, Apache-2.0)"
+  class_option :scripts, type: :boolean, default: false,
+    desc: "Create scripts/ directory for executable code"
+  class_option :references, type: :boolean, default: false,
+    desc: "Create references/ directory for documentation"
+  class_option :assets, type: :boolean, default: false,
+    desc: "Create assets/ directory for templates/images"
 
   def create_skill_directory
     empty_directory skill_path
@@ -57,4 +62,8 @@ class SkillGenerator < Rails::Generators::NamedBase
   def skill_license
     options[:license]
   end
+
+  def skill_title
+    skill_name.split("-").map(&:capitalize).join(" ")
+  end
 end

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

@@ -6,16 +6,52 @@ license: <%= skill_license %>
 <% end -%>
 ---
 
-# <%= skill_name.split("-").map(&:capitalize).join(" ") %>
+# <%= skill_title %>
 
-Instructions for using this skill.
+<%= skill_description %>
 
 ## When to Use
 
-Use this skill when...
+Use this skill when:
 
-## Steps
+- [Trigger condition 1 - be specific about keywords/phrases]
+- [Trigger condition 2]
 
-1. First step
-2. Second step
-3. Third step
+## Instructions
+
+### Step 1: [Action]
+
+[Clear instruction with expected outcome]
+
+### Step 2: [Action]
+
+[Clear instruction with expected outcome]
+
+### Step 3: [Action]
+
+[Clear instruction with expected outcome]
+
+## Examples
+
+### Example 1: [Scenario]
+
+**Input:**
+```
+[Example input or command]
+```
+
+**Output:**
+```
+[Expected result]
+```
+
+## Edge Cases
+
+- **[Scenario]**: [How to handle it]
+- **[Error condition]**: [Recovery steps]
+
+## Notes
+
+- Keep this file under 500 lines for optimal token usage
+- Move detailed documentation to `references/` directory
+- Move executable code to `scripts/` directory