ruby_llm-skills: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RubyLLM::Skills is a Ruby gem that implements the Agent Skills specification for RubyLLM. It enables progressive disclosure of AI capabilities through a three-level pattern: metadata (~100 tokens), full instructions (SKILL.md), and on-demand resources (scripts, references, assets).

Development Commands

Setup

bin/setup                    # Install dependencies and prepare development environment

Testing

bundle exec rake test        # Run all tests using Minitest
bundle exec rake             # Run default task: tests + linting

Linting

bundle exec rake standard    # Run StandardRB linter
bundle exec standardrb --fix # Auto-fix linting issues

Console

bin/console                  # Start IRB console with gem loaded

Gem Tasks

bundle exec rake build       # Build gem to pkg/
bundle exec rake install     # Build and install gem locally
bundle exec rake release     # Build, tag, and push gem (requires credentials)

Architecture

Module Structure

The gem uses the RubyLLM::Skills namespace (matches the parent ruby_llm gem):

lib/ruby_llm/
├── skills.rb           # Main module entry point
└── skills/
    └── version.rb      # Gem version constant

Key Design Patterns

Progressive Disclosure: Skills load in three stages to minimize context usage:

1. Metadata (name + description) - loaded at startup, injected into system prompt
2. Full instructions (SKILL.md) - loaded when LLM determines skill is relevant
3. Resources (scripts, references, assets) - loaded on demand during execution

Multi-Source Loading: Skills can be loaded from:

• Filesystem directories (default: app/skills)
• Zip archives (for distribution)
• ActiveRecord models (for per-user customization)
• Multiple sources simultaneously (later sources override earlier ones)