SDK Reference

Ruby SDK

The official Ruby client for SkillRouter. Clean, idiomatic Ruby with built-in configuration, error classes, and Rails-friendly design.

View on GitHub

Installation

Install the SkillRouter Ruby SDK via RubyGems. Requires Ruby 3.0 or higher.

gem install skillrouter

Or add to your Gemfile: gem "skillrouter"

Quick Start

Initialize the client, discover a skill, and execute it in just a few lines.

require "skillrouter"

# Initialize the client
client = SkillRouter::Client.new(api_key: "sr_your_api_key")

# Discover the best skill for a task
result = client.discover("Send a welcome email to new users")
puts result.skill.name       # "sendgrid-send-email"
puts result.confidence        # 0.97

# Execute the skill
response = client.execute(
  skill_id: result.skill.id,
  params: {
    to: "user@example.com",
    subject: "Welcome!",
    body: "Thanks for signing up."
  }
)
puts response.status  # "success"

Client Initialization

The client can be configured via constructor arguments or a global configuration block, which is ideal for Rails initializers.

# Direct initialization
client = SkillRouter::Client.new(
  api_key: "sr_your_api_key",
  base_url: "https://api.skillrouter.dev",  # Optional
  timeout: 30,                               # Optional, seconds
  max_retries: 3                             # Optional
)

# Global configuration (great for Rails initializers)
SkillRouter.configure do |config|
  config.api_key     = ENV["SKILLROUTER_API_KEY"]
  config.base_url    = "https://api.skillrouter.dev"
  config.timeout     = 30
  config.max_retries = 3
end

# Then use the default client
client = SkillRouter::Client.new

Rails tip: Place your configuration in config/initializers/skillrouter.rb so the client is ready throughout your application.

Core Methods

discover(query, **options)

Finds the best matching skill for a natural language query using semantic matching.

result = client.discover(
  "Process a credit card payment",
  category: "payments",   # Optional filter
  top_k: 3,               # Return top 3 matches
  threshold: 0.8          # Minimum confidence
)

puts result.skill.id          # "stripe-checkout"
puts result.skill.provider    # "stripe"
puts result.confidence         # 0.95

# Iterate over multiple matches
result.matches.each do |match|
  puts "#{match.skill.name}: #{match.confidence}"
end

execute(skill_id:, params:)

Executes a skill with the given parameters. SkillRouter handles authentication and retries.

response = client.execute(
  skill_id: "stripe-checkout",
  params: {
    amount: 2999,
    currency: "usd",
    customer_email: "buyer@example.com"
  }
)

puts response.status       # "success"
puts response.data         # {"payment_id"=>"pi_abc123", ...}
puts response.latency_ms   # 230

list_skills(**options)

Returns a paginated list of available skills with optional filters.

skills = client.list_skills(
  category: "payments",
  provider: "stripe",
  page: 1,
  per_page: 20
)

skills.items.each do |skill|
  puts "#{skill.id}: #{skill.name}"
end

puts "Total: #{skills.total}"

Error Handling

The SDK raises specific exception classes that inherit from a common base, making it easy to rescue at the right level of granularity.

begin
  response = client.execute(
    skill_id: "stripe-checkout",
    params: { amount: 2999 }
  )
rescue SkillRouter::AuthenticationError
  puts "Check your API key"

rescue SkillRouter::RateLimitError => e
  puts "Rate limited. Retry after #{e.retry_after}s"

rescue SkillRouter::ValidationError => e
  e.errors.each do |err|
    puts "#{err.field}: #{err.message}"
  end

rescue SkillRouter::SkillNotFoundError => e
  puts "Skill not found: #{e.skill_id}"

rescue SkillRouter::ExecutionError => e
  puts "Execution failed: #{e.message}"

rescue SkillRouter::Error => e
  # Catch-all for any SkillRouter error
  puts "Unexpected error: #{e.message}"
end

Tip: All exception classes inherit from SkillRouter::Error, which inherits from StandardError. Always include a rescue SkillRouter::Error block as a fallback.

Next Steps

Quick Start Guide GitHub Repository