claude-agent-ruby_skill

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.