claude-agent-sdk-ruby_skill

Overview

This skill documents how to use the unofficial Claude Agent SDK for Ruby to integrate Claude Code into Ruby apps. It covers both simple one-shot queries and interactive client sessions, configuration via ClaudeAgentOptions, streaming, tools/permissions, MCP servers, and Rails patterns like jobs and ActionCable. The goal is practical guidance for writing or refactoring Ruby code that calls Claude Agent features reliably.

How this skill works

Use ClaudeAgentSDK.query for stateless, one-shot prompts with unidirectional streaming. For multi-turn interactions, interruptible flows, hooks, permission callbacks, or custom tools, use ClaudeAgentSDK::Client and manage sessions. Configure behavior through ClaudeAgentOptions, parse content blocks for assistant text, and stop processing when you receive a ResultMessage that contains final result metadata and cost.

When to use it

• Quick prompts or single-turn operations where low setup is desired (use ClaudeAgentSDK.query).
• Multi-turn conversations requiring interrupts, rewinds, or session resumption (use ClaudeAgentSDK::Client).
• Integrations that require custom tools, permission callbacks, budgets, or sandboxing.
• In-app streaming to browsers via ActionCable or background processing with Rails jobs.
• When you need structured output parsing, cost/session IDs, or compliance features from ResultMessage.

Best practices

• Pick the interface first: query for simple jobs, Client for interactive control and hooks.
• Configure only needed ClaudeAgentOptions fields and validate tool/permission lists before starting sessions.
• Parse assistant content blocks and treat ResultMessage as the authoritative end-of-response with cost and session_id.
• Capture UserMessage#uuid when sending messages you may rewind or resume later.
• Use Rails background jobs or ActionCable streaming patterns for long-running interactions to avoid blocking web requests.

Example use cases

• A web form that sends a single prompt via ClaudeAgentSDK.query and streams the answer to the UI.
• A chat interface using ClaudeAgentSDK::Client to allow multi-turn dialogues, interrupts, and rewinds.
• A service that runs custom MCP tools in-process for constrained environments or delegates to external MCP servers.
• A Rails job that resumes a session by session_id to continue processing after a worker restart.
• Structured-output workflows where the SDK returns ResultMessage containing parsed fields, cost, and session metadata.