Agent-Skills.md

Agent Skills: Claude Agent Ruby SDK

Implement or modify Ruby code using the claude-agent-sdk gem. Covers query() one-shot calls, Client-based interactive sessions, streaming input, all 27 hook events, permission callbacks, SDK MCP servers, structured output, bare mode, full sandbox settings (network + filesystem), all 26 message types (including tool_progress, auth_status, prompt_suggestion, hook lifecycle, compact_boundary, session_state_changed, mirror_error, task_updated), session browsing/mutations, SessionStore transcript mirroring to external storage (S3/Redis/Postgres) with store-backed resume, subagents, file checkpointing, Rails integration, and custom transports. Use this skill whenever the user mentions claude-agent-sdk, Claude Agent Ruby, building AI agents in Ruby, or integrating Claude Code into a Ruby/Rails application.

UncategorizedID: ya-luotao/claude-agent-sdk-ruby/claude-agent-ruby

Repository

ya-luotao/claude-agent-sdk-ruby
ya-luotaoLicense: MIT
425

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ya-luotao/claude-agent-sdk-ruby/tree/HEAD/plugins/claude-agent-ruby/skills/claude-agent-ruby

Skill Files

Browse the full folder contents for claude-agent-ruby.

Download Skill

Loading file tree…

plugins/claude-agent-ruby/skills/claude-agent-ruby/SKILL.md

Skill Metadata

Name
claude-agent-ruby
Description
Implement or modify Ruby code using the claude-agent-sdk gem. Covers query() one-shot calls, Client-based interactive sessions, streaming input, all 27 hook events, permission callbacks, SDK MCP servers, structured output, bare mode, full sandbox settings (network + filesystem), all 26 message types (including tool_progress, auth_status, prompt_suggestion, hook lifecycle, compact_boundary, session_state_changed, mirror_error, task_updated), session browsing/mutations, SessionStore transcript mirroring to external storage (S3/Redis/Postgres) with store-backed resume, subagents, file checkpointing, Rails integration, and custom transports. Use this skill whenever the user mentions claude-agent-sdk, Claude Agent Ruby, building AI agents in Ruby, or integrating Claude Code into a Ruby/Rails application.

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, the docs/ topic subpages, and lib/ types for exact APIs.

Decision Guide

  • Choose ClaudeAgentSDK.query for one-shot queries or streaming input. Internally uses the control protocol (streaming mode).
  • Choose ClaudeAgentSDK::Client for multi-turn sessions, hooks, permission callbacks, MCP server control, or dynamic model switching; 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.
  • Choose ClaudeAgentSDK.list_sessions / ClaudeAgentSDK.get_session_messages for browsing previous session transcripts (pure filesystem, no CLI needed).

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 — the SDK has 26 typed message classes:
    • Core: AssistantMessage, UserMessage, ResultMessage, StreamEvent, RateLimitEvent
    • System init: InitMessage (session start / /clear — carries uuid, session_id, tools, model, cwd, agents, betas, claude_code_version, permission_mode, slash_commands, output_style, skills, plugins, fast_mode_state)
    • Compaction: CompactBoundaryMessage (uuid, session_id, compact_metadata with pre_tokens, trigger, preserved_segment)
    • Status: StatusMessage (compacting status, permission mode changes)
    • Tasks: TaskStartedMessage (+ workflow_name, prompt), TaskProgressMessage (+ summary), TaskNotificationMessage, TaskUpdatedMessage (lifecycle state change; status derived from patch['status'], task_id always a String — clear active-task tracking when status is in TERMINAL_TASK_STATUSES)
    • Hooks: HookStartedMessage, HookProgressMessage, HookResponseMessage
    • Sessions: SessionStateChangedMessage (idle/running/requires_action)
    • Tools: ToolProgressMessage (elapsed_time_seconds per tool), ToolUseSummaryMessage
    • Auth: AuthStatusMessage (isAuthenticating, output, error)
    • Files: FilesPersistedMessage (files, failed, processed_at)
    • API: APIRetryMessage (attempt, max_retries, retry_delay_ms, error_status)
    • Session store: MirrorErrorMessage (a SessionStore append failed after retries — session continues; local transcript stays durable)
    • Other: LocalCommandOutputMessage, ElicitationCompleteMessage, PromptSuggestionMessage
    • Unknown message types return nil (forward-compatible)
  • Handle content blocks: TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock, UnknownBlock
  • AssistantMessage carries: content, model, parent_tool_use_id, error, usage, message_id (API message ID), stop_reason, session_id, uuid (transcript UUID)
  • ResultMessage carries: stop_reason, model_usage (per-model breakdown), permission_denials, errors (on error subtypes), uuid, fast_mode_state
  • Use output_format for JSON schema structured output
  • Use thinking: with ThinkingConfigAdaptive, ThinkingConfigEnabled(budget_tokens:), or ThinkingConfigDisabled. Use effort: for effort level.

Hooks (27 events)

All hook events: PreToolUse, PostToolUse, PostToolUseFailure, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop, PreCompact, PostCompact, PermissionRequest, PermissionDenied, Setup, TeammateIdle, TaskCreated, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded, CwdChanged, FileChanged.

Define hooks as Ruby procs/lambdas. Do not combine can_use_tool with permission_prompt_tool_name. Tool-lifecycle hooks carry agent_id and agent_type when firing inside subagents. StopHookInput and SubagentStopHookInput include last_assistant_message.

Hook-specific outputs with to_h: PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, NotificationHookSpecificOutput, SubagentStartHookSpecificOutput, SessionStartHookSpecificOutput, SetupHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, CwdChangedHookSpecificOutput, FileChangedHookSpecificOutput.

Bare Mode

Use bare: true for minimal startup — skips hooks, LSP, plugin sync, CLAUDE.md auto-discovery, auto-memory, keychain reads. Explicitly provide context via system_prompt, add_dirs, setting_sources, allowed_tools.

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  bare: true,
  system_prompt: 'You are a code reviewer.',
  permission_mode: 'bypassPermissions'
)

Sandbox Settings (full CC parity)

  • SandboxSettings: enabled, fail_if_unavailable, auto_allow_bash_if_sandboxed, excluded_commands, allow_unsandboxed_commands, network, filesystem, ignore_violations (Hash), enable_weaker_nested_sandbox, enable_weaker_network_isolation, ripgrep
  • SandboxNetworkConfig: allowed_domains, denied_domains, allow_managed_domains_only, allow_unix_sockets, allow_all_unix_sockets, allow_local_binding, allow_mach_lookup, http_proxy_port, socks_proxy_port
  • SandboxFilesystemConfig: allow_write, deny_write, deny_read, allow_read, allow_managed_read_paths_only

SDK MCP Tools

  • Include mcp__<server>__<tool> in allowed_tools
  • Use annotations: on create_tool for MCP tool annotations
  • Use meta: on create_tool for _meta field forwarding (e.g., { 'anthropic/maxResultSizeChars' => 100000 } to prevent truncation of large results)
  • If annotations[:maxResultSizeChars] is set, _meta is auto-populated
  • Both symbol-keyed and string-keyed input_schema hashes are accepted

Session Management

  • resume, session_id, fork_session option for session handling
  • ClaudeAgentSDK.delete_session(session_id:, directory:) — hard-deletes a session
  • ClaudeAgentSDK.fork_session(session_id:, directory:, up_to_message_id:, title:) → ForkSessionResult — filesystem fork with UUID remapping
  • ClaudeAgentSDK.list_sessions(directory:, limit:, offset:, include_worktrees:) — supports offset for pagination
  • ClaudeAgentSDK.list_subagents(session_id:, directory:) / ClaudeAgentSDK.get_subagent_messages(session_id:, agent_id:, directory:, limit:, offset:) — local-disk subagent transcript readers (disk counterparts of the *_from_store pair)
  • SessionStore mirroring: ClaudeAgentOptions.new(session_store: store) mirrors transcripts to external storage (subclass ClaudeAgentSDK::SessionStore — only #append/#load required; InMemorySessionStore for tests; S3/Redis/Postgres reference adapters in examples/session_stores/). session_store_flush: 'eager' flushes per frame; load_timeout_ms bounds resume store calls.
  • Resume from store: pair session_store with resume:/continue_conversation — no local JSONL needed. Note: runs the CLI against a bare temp CLAUDE_CONFIG_DIR (user-scope settings.json/agents/skills invisible; project .claude/* still applies).
  • Store-backed helpers: list_sessions_from_store, get_session_info_from_store, get_session_messages_from_store, list_subagents_from_store, get_subagent_messages_from_store, rename_session_via_store, tag_session_via_store, delete_session_via_store, fork_session_via_store, import_session_to_store (migrate disk → store). Store reads default directory: to cwd. Validate adapters with ClaudeAgentSDK::Testing.run_session_store_conformance.
  • Client#get_context_usage — context window breakdown (tokens by category, model, MCP tools, etc.)
  • Client#reconnect_mcp_server(name), Client#toggle_mcp_server(name, enabled), Client#stop_task(task_id) for live control
  • Client#rewind_files(uuid) with enable_file_checkpointing: true
  • McpStatusResponse.parse(client.get_mcp_status) for typed MCP status

Where To Look For Exact Details

  • Locate the gem: bundle show claude-agent-sdk
  • Read <gem_path>/README.md for the overview, install, and minimal API examples
  • Read <gem_path>/docs/*.md for topic subpages — client.md (bidirectional + custom transports), mcp-servers.md (SDK MCP tools/resources/prompts), hooks-and-permissions.md (27 hook events + permission callbacks), configuration.md (structured output, thinking, budget, sandbox, bare mode, file checkpointing), sessions.md (list/read/rename/tag/fork/resume + SessionStore mirroring/store-backed helpers), observability.md (OTel + Langfuse), rails.md (ActionCable, jobs, initializers), types.md (message/content-block/configuration types), errors.md (error hierarchy + timeout)
  • Inspect <gem_path>/lib/claude_agent_sdk/types.rb for all types
  • Inspect <gem_path>/lib/claude_agent_sdk/message_parser.rb for message parsing
  • Inspect <gem_path>/lib/claude_agent_sdk/sessions.rb for session browsing
  • Inspect <gem_path>/lib/claude_agent_sdk/errors.rb for error classes
  • Use references/usage-map.md for a documentation map (README + docs/) and minimal skeletons

Resources

references/

  • Read references/usage-map.md to map tasks to README and docs/ subpages, gem paths, and minimal skeletons.
  • Read references/message-handling.md to extract text/tool blocks, build streaming input, use Client runtime APIs, and capture UUIDs for rewind.
  • Read references/options.md to configure ClaudeAgentOptions (defaults, tools, permissions, skills, output formats, budgets, sandbox, sessions, agents, custom transports), and to browse/mutate sessions.
  • Read references/mcp-servers.md to define in-process SDK MCP tools/resources/prompts, configure external MCP servers, or manage MCP servers at runtime.
  • Read references/rails.md for initializers, background jobs, ActionCable streaming, and session resumption patterns.
  • Read references/troubleshooting.md for common setup/runtime errors and timeout tuning.