home / skills / ya-luotao / claude-agent-sdk-ruby / claude-agent-ruby

claude-agent-ruby skill

safe

This skill helps you integrate Ruby applications with Claude Agent using claude-agent-sdk for one-shot queries, bidirectional sessions, and structured outputs.

npx playbooks add skill ya-luotao/claude-agent-sdk-ruby --skill claude-agent-ruby

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.4 KB

---
name: claude-agent-ruby
description: Implement or modify Ruby code that uses the claude-agent-sdk gem, including query() one-shot calls, Client-based interactive sessions, streaming input, option configuration, tools/permissions, hooks, SDK MCP servers, structured output, budgets, sandboxing, session resumption, Rails integration, and error handling.
---

# Claude Agent Ruby SDK

## Overview
Use this skill to build or refactor Ruby integrations with Claude Code via `claude-agent-sdk`, favoring the gem's README and types for exact APIs.

## Decision Guide
- Choose `ClaudeAgentSDK.query` for one-shot or unidirectional streaming.
- Choose `ClaudeAgentSDK::Client` for bidirectional sessions, hooks, or permission callbacks; wrap in `Async do ... end.wait`.
- Choose SDK MCP servers (`create_tool`, `create_sdk_mcp_server`) for in-process tools; choose external MCP configs for subprocess/HTTP servers.

## Implementation Checklist
- Confirm prerequisites (Ruby 3.2+, Node.js, Claude Code CLI).
- Build `ClaudeAgentSDK::ClaudeAgentOptions` and pass it to `query` or `Client.new`.
- Handle messages by type (`AssistantMessage`, `ResultMessage`, etc.) and content blocks (`TextBlock`, `ToolUseBlock`, etc.).
- Use `output_format` and read `StructuredOutput` tool-use blocks for JSON schema responses.
- Define hooks and permission callbacks as Ruby procs/lambdas; do not combine `can_use_tool` with `permission_prompt_tool_name`.
- For SDK MCP tools, include `mcp__<server>__<tool>` in `allowed_tools`.
- Use `tools` or `ToolsPreset` for base tool selection; use `append_allowed_tools` when extending defaults.
- Configure sandboxing via `SandboxSettings` and `SandboxNetworkConfig` when requested.
- Use `resume`, `session_id`, and `fork_session` for session handling; enable file checkpointing only when explicitly needed.

## Where To Look For Exact Details
- Locate the gem path with `bundle show claude-agent-sdk` or `ruby -e 'puts Gem::Specification.find_by_name(\"claude-agent-sdk\").full_gem_path'`.
- Read `<gem_path>/README.md` for canonical usage and option examples.
- Inspect `<gem_path>/lib/claude_agent_sdk/types.rb` for the full options and type list.
- Inspect `<gem_path>/lib/claude_agent_sdk/errors.rb` for error classes and handling.
- Use `references/usage-map.md` for a README section map and minimal skeletons.

## Resources
### references/
Use `references/usage-map.md` to map tasks to README sections and gem paths.

Overview

This skill helps you implement or modify Ruby code that uses the claude-agent-sdk gem to interact with Claude Agent. It covers one-shot queries, Client-based interactive sessions, streaming, hooks, tools, sandboxing, structured output, and Rails integration. The content focuses on practical patterns, configuration objects, and error handling to make integrations reliable and maintainable.

How this skill works

The skill guides you to pick the right API: use ClaudeAgentSDK.query for simple one-shot or unidirectional streams and ClaudeAgentSDK::Client for bidirectional, stateful sessions with hooks and permission callbacks. It explains how to build ClaudeAgentOptions, register tools or MCP servers, handle message and block types (TextBlock, ToolUseBlock, ResultMessage), and read StructuredOutput for JSON schema responses. It also describes sandbox/network settings, session resumption and forking, and common error classes to catch and handle.

When to use it

Build a simple request/response integration or background job that needs one-shot calls.
Implement an interactive assistant or long-lived session that requires hooks, permissions, or streaming input/output.
Add in-process tools or create SDK MCP servers for local tool implementations.
Integrate Claude Agent into a Rails app with session checkpointing and structured output handling.
Harden integrations with sandboxing, allowed_tools, and explicit permission callbacks.

Best practices

Choose the minimal API: query for one-shot flows, Client for interactive or streaming flows.
Construct ClaudeAgentSDK::ClaudeAgentOptions explicitly and pass it to query or Client.new to avoid implicit defaults.
Handle messages by type and inspect content blocks; treat StructuredOutput tool-use blocks as authoritative for JSON responses.
Use append_allowed_tools to extend defaults instead of replacing core presets unless needed.
Define hooks and permission callbacks as Procs/lambdas and avoid mixing can_use_tool with permission_prompt_tool_name.
Enable file checkpointing or session forking only when necessary to avoid state divergence.

Example use cases

Background worker that uses ClaudeAgentSDK.query to summarize text or extract structured data via output_format.
Rails controller that resumes a user session by session_id and streams assistant messages to the client.
A CLI tool that spins up an SDK MCP server to expose a local tool to the agent and registers mcp__<server>__<tool> in allowed_tools.
An interactive chatbot using ClaudeAgentSDK::Client with on_message hooks and permission callbacks to gate sensitive tool use.
A pipeline that enforces sandboxing and network restrictions for tool execution and captures StructuredOutput for downstream validation.

FAQ

Which API should I use for simple calls?

Use ClaudeAgentSDK.query for one-shot requests or unidirectional streaming; it is simpler and requires less state management.

How do I get exact option names and types?

Inspect the gem path (bundle show or Gem::Specification) and read lib/claude_agent_sdk/types.rb for canonical option names and types.