robot_lab 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eaa090a87b2f82890dc8ee350bb1326b380c41d6560c3ae01e0ea1a4fc0d84a
-  data.tar.gz: 8232818730ba698d09ed9537adbc774f5d2ad84013942016e48ebad192a653c9
+  metadata.gz: 37a044eb81a0e5c56aa7c5c00f9b4eff600c56eecda8bb2deb18058919a18267
+  data.tar.gz: a48253bbceb5ac99f1babf9c4538045886e038fb0c4a827b96b219b5363bf5c8
 SHA512:
-  metadata.gz: ce75a3733e3d153196f85995c1363e542aa9b039f523cb15388a2d0d0f7a13d7ea26390a12abf6582680da5b119f1df8f6f35a7837a28a8b6f07f5aca72639db
-  data.tar.gz: c2c4f50e6352dc6018c8f0077549450e05adccb3eaa555236c46b131c557f69acf6f59ca6af12c823e429db777019bca684846338af273de2e2ce5587be5a976
+  metadata.gz: 9f84d7c82598d281e8c88a4e67b2b0c13bac1142e8dae9834a1b0e84d1055e16837c62b452398da615d477aec834b153ca74f6313c67b806fe174aacd3a0999b
+  data.tar.gz: 549afa0eb2e622ad8caf0d928559bb881b3f1307d2e427074a2f96f943418784e580ef9d5b2a06534f9ec57873682189ec6890cd0ed1790e19b66c159fff572e

data/CHANGELOG.md

@@ -1,8 +1,5 @@
 # Changelog
 
-> [!CAUTION]
-> This gem is under active development. APIs and features may change without notice.
-
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
@@ -11,6 +8,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.8] - 2026-02-22
+
+### Added
+
+- **Skills as composable templates** — prepend reusable prompt snippets at build time via `skills:` parameter
+  - Skills are regular PromptManager templates (no special subdirectory)
+  - Recursive expansion — skills can declare nested skills via front matter `skills:` key
+  - Depth-first ordering — nested skills appear before their parent
+  - Cycle detection via `Set` of visited IDs; cycles log a warning and skip
+  - Config cascade — skill₁ → skill₂ → ... → main template → constructor kwargs
+  - Shared context — all skills and the main template render with the same `context:` hash
+  - Example: `examples/17_skills.rb` — SRE incident response system with flat and recursive skills
+  - 20 new tests covering expansion, ordering, cycles, config cascade, and factory passthrough
+- **Streaming content callback (`on_content:`)** — wire streaming at robot build time
+  - Stored callback fires on every `run()` call automatically
+  - Pass-through block on `run()` for per-call streaming
+  - When both exist, both fire (stored first, then runtime block)
+  - `effective_streaming_block` merges stored + runtime into a single Proc
+  - Added `:on_content` to `RunConfig::CALLBACK_FIELDS`
+  - 12 new tests
+- **Graceful tool error handling** — `RobotLab::Tool#call` wraps `execute` with `rescue StandardError`
+  - Errors returned as plain string (`"Error (tool_name): message"`) so the LLM can reason about them
+  - Class-level `raise_on_error` opt-out for critical tools
+  - MCP tools inherit the same wrapper via `Tool.create` subclasses
+  - 10 new tests
+- **`RobotRunJob` generator template** (`job.rb.tt`) — turnkey ActiveJob background job for robot runs
+  - Resolves robot class via `constantize.build`
+  - Wires `TurboStreamCallbacks` when `turbo-rails` is available (graceful no-op otherwise)
+  - Persists results via `result.export`; broadcasts completion/error via Turbo Streams
+  - `--skip-job` option on install generator
+- **`TurboStreamCallbacks` module** (`lib/robot_lab/rails_integration/turbo_stream_callbacks.rb`)
+  - `available?` — runtime check for `Turbo::StreamsChannel`
+  - `build_content_callback(stream_name:, target:)` — broadcasts HTML-escaped content chunks
+  - `build_tool_call_callback(stream_name:, target:)` — broadcasts tool call badges
+  - 13 tests
+- **Rails demo app** (`examples/18_rails/`) — minimal hand-built Rails 8 app exercising all Rails integration
+  - ChatRobot with TimeTool, RobotRunJob, Turbo Stream token streaming, SQLite persistence
+  - No asset pipeline — Turbo JS via importmap from CDN
+  - `:async` adapters for both ActiveJob and ActionCable (no Redis, no Solid Queue)
+  - User messages persisted in history; auto-scrolling via MutationObserver; form clears after submit
+  - Rake tasks: `examples:rails_setup`, `examples:rails`
+- **Routing robot example** in Rails integration docs — `ClassifierRobot` subclass with `call(result)` override
+- **Custom tool example** in Rails integration docs — `OrderLookup` tool with ActiveRecord
+
+### Changed
+
+- Bumped version to 0.0.8
+- **Renamed `RobotLab::Rails` → `RobotLab::RailsIntegration`** — eliminates constant shadowing where bare `Rails` inside `module RobotLab` resolved to the gem's own namespace instead of `::Rails`
+  - Moved `lib/robot_lab/rails/` → `lib/robot_lab/rails_integration/`
+  - Updated all require paths, loader.ignore, generator templates, tests, and documentation
+  - Reverted `::Rails` back to bare `Rails` in `config.rb` (shadow eliminated)
+- Rakefile updated with `STANDALONE_APPS` map for standalone demo apps
+- Documentation updates across README, guides, API reference, and examples for all new features
+- Updated Gemfile.lock dependencies
+
+### Fixed
+
+- `RobotLab::Rails` namespace shadowing `::Rails` in `config.rb` (`NoMethodError: undefined method 'root' for module RobotLab::Rails`)
+- MkDocs broken anchor link in `docs/examples/index.md` (`#with-conversation-history` → `#with-memory`)
+
 ## [0.0.7] - 2026-02-17 [unreleased]
 
 ### Added

data/README.md

@@ -1,7 +1,8 @@
 # RobotLab
 
-> [!CAUTION]
-> This gem is under active development. APIs and features may change without notice. See the [CHANGELOG](CHANGELOG.md) for details.
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section  of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
+
 <br>
 <table>
 <tr>
@@ -10,24 +11,27 @@
 <em>"Build robots. Solve problems."</em>
 </td>
 <td width="50%" valign="top">
-<strong>Multi-robot LLM workflow orchestration for Ruby</strong><br><br>
-RobotLab enables you to build sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own system prompt, tools, and capabilities.<br><br>
 <strong>Key Features</strong><br>
 
 - <strong>Multi-Robot Architecture</strong> - Build with specialized AI agents<br>
 - <strong>Network Orchestration</strong> - Connect robots with flexible routing<br>
-- <strong>Extensible Tools</strong> - Give robots custom capabilities<br>
+- <strong>Prompt Templates</strong> - Self-contained .md files with YAML front matter<br>
+- <strong>Composable Skills</strong> - Mix reusable prompt behaviors into any robot<br>
+- <strong>Extensible Tools</strong> - Custom capabilities with graceful error handling<br>
+- <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
+- <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
-- <strong>Conversation History</strong> - Persist and restore threads<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
-- <strong>Streaming</strong> - Real-time event streaming<br>
-- <strong>Rails Integration</strong> - Generators and ActiveRecord support
+- <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
+- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting
 </td>
 </tr>
 </table>
 
+<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) snd explore the [many examples](examples/README.md) available as working demo applications.</p>
+
 ## Installation
 
 ```bash
@@ -172,7 +176,35 @@ You are a GitHub assistant. Use available tools to help with repository tasks.
 robot = RobotLab.build(template: :github_assistant)
 ```
 
-Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+
+### Composable Skills
+
+Skills let you compose robot behaviors from reusable templates. A skill is just a template whose prompt body is prepended before the main template. Use skills to mix in capabilities like "ask clarifying questions", "respond in JSON", or "follow safety guidelines" without creating a dedicated template for every combination.
+
+```ruby
+# Compose a support robot from reusable skills
+robot = RobotLab.build(
+  name: "support",
+  template: :support_agent,
+  skills: [:clarifier, :sentiment_aware, :json_responder],
+  context: { company: "Acme Corp" }
+)
+```
+
+Skills can also be declared in template front matter:
+
+```markdown
+---
+description: Support agent with built-in skills
+skills:
+  - clarifier
+  - sentiment_aware
+---
+You are a support agent for <%= company %>.
+```
+
+Skills are expanded depth-first and can reference other skills (with automatic cycle detection). Config cascades through skills in order — later values override earlier ones, and constructor kwargs always win.
 
 ### Combining Templates with System Prompts
 
@@ -252,6 +284,28 @@ result = robot
   .run("Write a haiku about Ruby programming")
 ```
 
+## Graceful Tool Error Handling
+
+`RobotLab::Tool` automatically catches exceptions in `execute` and returns a plain-text error to the LLM instead of crashing the run. The LLM can then reason about the error and try an alternative approach.
+
+```ruby
+tool = RobotLab::Tool.create(name: "fetch_data") do |args|
+  raise IOError, "connection refused"
+end
+
+result = tool.call({})
+# => "Error (fetch_data): connection refused"
+```
+
+This applies to all tools — subclasses, factory tools, and MCP tools. For critical tools where you want exceptions to propagate, opt out per class:
+
+```ruby
+class CriticalTool < RobotLab::Tool
+  self.raise_on_error = true
+  # ...
+end
+```
+
 ## Creating a Robot with Tools
 
 ```ruby
@@ -502,26 +556,48 @@ Key features:
 
 ## Streaming
 
-Use a `Streaming::Context` with a publish callback to receive real-time events:
+Stream LLM content in real-time using a stored callback, a per-call block, or both. Each receives a [`RubyLLM::Chunk`](https://rubyllm.com/streaming/#basic-streaming) — use `chunk.content` for the text delta. Chunks also carry `model_id`, `tool_calls`, `thinking`, and token usage on the final chunk.
+
+### Stored Callback (`on_content:`)
+
+Wire streaming at build time. The callback fires on every `run()` call automatically:
 
 ```ruby
-handler = lambda do |event|
-  case event[:event]
-  when RobotLab::Streaming::Events::TEXT_DELTA
-    print event[:data][:delta]
-  when RobotLab::Streaming::Events::RUN_COMPLETED
-    puts "\nDone!"
-  end
-end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { print chunk.content }
+)
+
+robot.run("Tell me a story")  # streams automatically
+```
+
+### Per-Call Block
+
+Pass a block to `run()` for one-off streaming:
 
-context = RobotLab::Streaming::Context.new(
-  run_id: SecureRandom.uuid,
-  message_id: SecureRandom.uuid,
-  scope: "robot",
-  publish: handler
+```ruby
+robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
+
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
+
+### Both Together
+
+When both a stored callback and a runtime block are provided, both fire (stored first):
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { log_chunk(chunk.content) }
 )
+
+robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 ```
 
+The `on_content:` callback participates in the RunConfig cascade, so it can be set at the network or config level and inherited by robots.
+
 ## Rails Integration
 
 ```bash

data/Rakefile

@@ -52,7 +52,12 @@ namespace :examples do
     "16_writers_room" => "writers_room.rb"
   }.freeze
 
-  desc "Run all examples"
+  # Subdirectory demos that are standalone apps (not run via `ruby`)
+  STANDALONE_APPS = {
+    "18_rails" => { setup: "bin/setup", run: "bin/dev" }
+  }.freeze
+
+  desc "Run all examples (excludes standalone apps like 18_rails)"
   task :all do
     # Single-file examples
     Dir.glob("examples/*.rb").sort.each do |example|
@@ -72,6 +77,15 @@ namespace :examples do
       puts '=' * 60
       ruby path
     end
+
+    # Remind about standalone apps
+    STANDALONE_APPS.each do |dir, commands|
+      puts "\n#{'=' * 60}"
+      puts "Skipped: examples/#{dir} (standalone app)"
+      puts "  Setup: cd examples/#{dir} && #{commands[:setup]}"
+      puts "  Run:   cd examples/#{dir} && #{commands[:run]}"
+      puts '=' * 60
+    end
   end
 
   desc "Run a specific example by number (e.g., rake examples:run[1])"
@@ -89,6 +103,16 @@ namespace :examples do
     dir = Dir.glob("examples/#{padded}_*/").first
     if dir
       dir_name = File.basename(dir)
+
+      # Check if it's a standalone app
+      if STANDALONE_APPS.key?(dir_name)
+        commands = STANDALONE_APPS[dir_name]
+        puts "Example #{args[:num]} is a standalone app (#{dir_name})."
+        puts "  Setup: cd examples/#{dir_name} && #{commands[:setup]}"
+        puts "  Run:   cd examples/#{dir_name} && #{commands[:run]}"
+        next
+      end
+
       entry = SUBDIR_ENTRY_POINTS[dir_name]
       if entry && File.exist?(File.join(dir, entry))
         ruby File.join(dir, entry)
@@ -99,6 +123,20 @@ namespace :examples do
       puts "Example #{args[:num]} not found"
     end
   end
+
+  desc "Setup the Rails demo app (example 18)"
+  task :rails_setup do
+    Dir.chdir("examples/18_rails") do
+      sh "bin/setup"
+    end
+  end
+
+  desc "Start the Rails demo app (example 18)"
+  task :rails do
+    Dir.chdir("examples/18_rails") do
+      sh "bin/dev"
+    end
+  end
 end
 
 namespace :docs do

data/docs/api/core/robot.md

@@ -28,8 +28,10 @@ Robot.new(
   tools: :none,
   on_tool_call: nil,
   on_tool_result: nil,
+  on_content: nil,
   enable_cache: true,
   bus: nil,
+  skills: nil,
   temperature: nil,
   top_p: nil,
   top_k: nil,
@@ -57,8 +59,10 @@ Robot.new(
 | `tools` | `Symbol`, `Array` | `:none` | Hierarchical tools config (`:none`, `:inherit`, or tool name array) |
 | `on_tool_call` | `Proc`, `nil` | `nil` | Callback invoked when a tool is called |
 | `on_tool_result` | `Proc`, `nil` | `nil` | Callback invoked when a tool returns a result |
+| `on_content` | `Proc`, `nil` | `nil` | Stored streaming callback invoked with each content chunk (see [Streaming](#streaming)) |
 | `enable_cache` | `Boolean` | `true` | Whether to enable semantic caching |
 | `bus` | `TypedBus::MessageBus`, `nil` | `nil` | Optional message bus for inter-robot communication |
+| `skills` | `Symbol`, `Array<Symbol>`, `nil` | `nil` | Skill templates to prepend (see [Skills](#skills)) |
 | `config` | `RunConfig`, `nil` | `nil` | Shared config merged with explicit kwargs (see [RunConfig](#runconfig)) |
 | `temperature` | `Float`, `nil` | `nil` | Controls randomness (0.0-1.0) |
 | `top_p` | `Float`, `nil` | `nil` | Nucleus sampling threshold |
@@ -80,6 +84,7 @@ robot = RobotLab.build(
   context: {},
   enable_cache: true,
   bus: nil,           # Optional TypedBus::MessageBus
+  skills: nil,        # Optional skill templates
   **options           # All other Robot.new parameters
 )
 # => RobotLab::Robot
@@ -95,6 +100,7 @@ If `name` is omitted, it defaults to `"robot"`.
 | `description` | `String`, `nil` | Human-readable description |
 | `template` | `Symbol`, `nil` | Prompt template identifier |
 | `system_prompt` | `String`, `nil` | Inline system prompt |
+| `skills` | `Array<Symbol>`, `nil` | Constructor-provided skill template IDs (nil if none) |
 | `local_tools` | `Array` | Locally defined tools |
 | `mcp_clients` | `Hash<String, MCP::Client>` | Connected MCP clients, keyed by server name |
 | `mcp_tools` | `Array<Tool>` | Tools discovered from MCP servers |
@@ -119,7 +125,7 @@ Used by tools like [`AskUser`](tool.md#built-in-askuser) that need terminal IO.
 ### run
 
 ```ruby
-result = robot.run(message, **kwargs)
+result = robot.run(message, **kwargs, &block)
 # => RobotResult
 ```
 
@@ -136,6 +142,9 @@ Primary execution method. Sends a message to the LLM with memory/MCP/tools resol
 | `mcp` | `Symbol`, `Array` | `:none` | Runtime MCP override |
 | `tools` | `Symbol`, `Array` | `:none` | Runtime tools override |
 | `**kwargs` | `Hash` | `{}` | Additional keyword arguments passed to `Agent#ask` |
+| `&block` | `Proc` | `nil` | Per-call streaming block, receives each content chunk |
+
+When both a stored `on_content` callback and a runtime block are provided, both fire (stored first, then runtime block).
 
 **Returns:** `RobotResult`
 
@@ -148,8 +157,8 @@ result = robot.run("What is 2+2?")
 # With runtime memory
 result = robot.run("Summarize the data", memory: { data: report })
 
-# With streaming block
-result = robot.run("Tell me a story") { |event| print event.text }
+# With per-call streaming block
+result = robot.run("Tell me a story") { |chunk| print chunk.content }
 
 # With runtime overrides
 result = robot.run("Help me", mcp: :none, tools: :none)
@@ -408,7 +417,7 @@ robot.to_h
 # => Hash
 ```
 
-Returns a hash representation of the robot including name, description, template, system_prompt, local_tools, mcp_tools, mcp_config, tools_config, mcp_servers, model, and bus (true if configured, omitted otherwise).
+Returns a hash representation of the robot including name, description, template, skills, system_prompt, local_tools, mcp_tools, mcp_config, tools_config, mcp_servers, model, and bus (true if configured, omitted otherwise). Nil values are compacted out.
 
 ## Memory Behavior
 
@@ -437,7 +446,7 @@ Front matter supports two categories of keys:
 
 **LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` — applied to the underlying chat.
 
-**Robot Extras:** `robot_name`, `description`, `tools`, `mcp` — applied to the robot's identity and capabilities. Constructor-provided values always take precedence.
+**Robot Extras:** `robot_name`, `description`, `tools`, `mcp`, `skills` — applied to the robot's identity and capabilities. Constructor-provided values always take precedence.
 
 | Key | Type | Description |
 |-----|------|-------------|
@@ -445,6 +454,40 @@ Front matter supports two categories of keys:
 | `description` | `String` | Human-readable description |
 | `tools` | `Array<String>` | Tool class names resolved via `Object.const_get` |
 | `mcp` | `Array<Hash>` | MCP server configurations |
+| `skills` | `Array<Symbol>` | Skill templates to prepend (recursive, with cycle detection) |
+
+## Skills
+
+Skills compose robot behaviors from reusable templates. Each skill is a standard `.md` template whose prompt body is prepended before the main template. Skills are expanded depth-first with automatic cycle detection.
+
+**Constructor:** `skills:` accepts `Symbol` or `Array<Symbol>`:
+
+```ruby
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  skills: [:clarifier, :json_responder]
+)
+```
+
+**Front matter:** templates can declare skills via `skills:` key:
+
+```markdown
+---
+skills:
+  - clarifier
+  - json_responder
+---
+Main template body here.
+```
+
+Constructor `skills:` and front matter `skills:` are combined (constructor first, then front matter). Skills can nest (a skill can declare its own `skills:` in front matter).
+
+**Config cascade:** skill config merges in processing order (deepest first). Later values override earlier. Constructor kwargs always win.
+
+**Prompt order:** skill bodies are concatenated in expansion order, followed by the main template body. All are joined with `"\n\n"` and set as system instructions via a single `with_instructions` call.
+
+**Cycle detection:** if skills form a cycle, the duplicate is skipped with a logger warning.
 
 ## RunConfig
 
@@ -463,10 +506,78 @@ robot = RobotLab.build(
 robot.config  #=> RunConfig with model: "claude-sonnet-4", temperature: 0.9, ...
 ```
 
-RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `bus`, `enable_cache`.
+RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `on_content`, `bus`, `enable_cache`.
 
 See [Configuration: RunConfig](../../getting-started/configuration.md#runconfig-shared-operational-defaults) for full details.
 
+## Streaming
+
+Robots support two complementary approaches for streaming LLM content in real-time.
+
+### The Chunk Object
+
+Both callbacks and blocks receive a [`RubyLLM::Chunk`](https://rubyllm.com/streaming/#basic-streaming) (subclass of `RubyLLM::Message`). Key accessors:
+
+| Accessor | Type | Description |
+|----------|------|-------------|
+| `content` | `String`, `nil` | The text delta for this chunk (`nil` on tool-call or usage-only chunks) |
+| `role` | `Symbol` | Always `:assistant` |
+| `model_id` | `String` | The LLM model ID |
+| `tool_calls` | `Array`, `nil` | Tool call deltas (partial JSON arguments) |
+| `tool_call?` | `Boolean` | Whether this chunk contains tool call data |
+| `thinking` | `Thinking`, `nil` | Extended thinking delta (Anthropic only) |
+| `input_tokens` | `Integer`, `nil` | Input token count (populated on final chunk) |
+| `output_tokens` | `Integer`, `nil` | Output token count (populated on final chunk) |
+| `cached_tokens` | `Integer`, `nil` | Cached prompt tokens (final chunk) |
+
+Most chunks carry only `content` (the text delta). The final chunk(s) carry token usage counts. Tool call chunks have `tool_calls` instead of `content`.
+
+### Stored Callback (`on_content:`)
+
+Wired at build time via constructor or RunConfig. Fires on every `run()` call automatically:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { broadcast(chunk.content) }
+)
+robot.run("Tell me a story")  # streams via stored callback
+```
+
+The `on_content` callback participates in the RunConfig cascade:
+
+```ruby
+config = RobotLab::RunConfig.new(
+  on_content: ->(chunk) { log(chunk.content) }
+)
+robot = RobotLab.build(name: "bot", config: config)
+```
+
+Constructor `on_content:` overrides RunConfig `on_content`.
+
+### Per-Call Block
+
+Pass a block to `run()` for one-off streaming:
+
+```ruby
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
+
+### Both Together
+
+When both exist, both fire — stored callback first, then runtime block:
+
+```ruby
+robot = RobotLab.build(
+  name: "bot",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { log(chunk.content) }
+)
+robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
+# log() fires first, then stream_to_client()
+```
+
 ## Configuration Hierarchy
 
 Tools and MCP servers use hierarchical resolution: **runtime > robot > network > global config**.
@@ -559,6 +670,18 @@ result = robot.run("Search for popular Ruby repos")
 robot.disconnect
 ```
 
+### Robot with Skills
+
+```ruby
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  skills: [:clarifier, :safety, :json_responder],
+  context: { company: "Acme Corp" }
+)
+result = robot.run("I need help with my order")
+```
+
 ### Bare Robot with Chaining
 
 ```ruby
@@ -628,6 +751,6 @@ bot.send_message(to: :someone, content: "Hello!")
 
 ## See Also
 
-- [Building Robots Guide](../../guides/building-robots.md)
+- [Building Robots Guide](../../guides/building-robots.md) (includes [Composable Skills](../../guides/building-robots.md#composable-skills))
 - [Tool](tool.md)
 - [Network](network.md)

data/docs/api/core/tool.md

@@ -4,7 +4,7 @@ Callable function that robots can use to interact with external systems.
 
 ## Class: `RobotLab::Tool < RubyLLM::Tool`
 
-RobotLab::Tool inherits from RubyLLM::Tool, adding a `robot:` constructor parameter and a `Tool.create` factory for dynamic tools.
+RobotLab::Tool inherits from RubyLLM::Tool, adding a `robot:` constructor parameter, a `Tool.create` factory for dynamic tools, and graceful error handling that returns plain-text errors to the LLM instead of crashing the run.
 
 ### Subclass Pattern
 
@@ -51,6 +51,15 @@ Tool.new(robot: nil)
 
 ## Class Methods
 
+### raise_on_error / raise_on_error?
+
+```ruby
+MyTool.raise_on_error = true
+MyTool.raise_on_error?  # => true
+```
+
+Per-class flag controlling whether `call` propagates exceptions from `execute` instead of catching them. Defaults to `false`. Does not affect other tool classes.
+
 ### Tool.create
 
 Factory for dynamic tools (MCP wrappers, inline tools).
@@ -169,7 +178,24 @@ Whether this is an MCP-provided tool.
 result = tool.call(args_hash)
 ```
 
-Inherited from RubyLLM::Tool. Converts string keys to symbols and calls `execute(**args)`.
+Overrides `RubyLLM::Tool#call` with graceful error handling. Converts string keys to symbols and calls `execute(**args)`. If `execute` raises a `StandardError`, the error is caught and returned as a plain-text string the LLM can reason about:
+
+```
+Error (tool_name): exception message
+```
+
+The error is also logged via `RobotLab.config.logger` at `:warn` level.
+
+To propagate exceptions instead of catching them (for critical tools), set `raise_on_error` on the class:
+
+```ruby
+class CriticalTool < RobotLab::Tool
+  self.raise_on_error = true
+  # ...
+end
+```
+
+`raise_on_error` is per-class (defaults to `false`) and does not affect other tool classes.
 
 ### params_schema
 

data/docs/concepts.md

@@ -12,7 +12,9 @@ Each robot has:
 - **Template**: A `.md` file with YAML front matter managed by prompt_manager, referenced by symbol
 - **System Prompt**: Inline instructions (can be used alone or combined with a template)
 - **Model**: The LLM model to use (defaults to `RobotLab.config.ruby_llm.model`)
-- **Local Tools**: `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances
+- **Skills**: Composable template behaviors prepended before the main template
+- **Local Tools**: `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances (with automatic error handling)
+- **Streaming**: Real-time content via stored `on_content` callback or per-call block
 - **Memory**: Persistent key-value store across runs
 
 ```ruby
@@ -137,7 +139,9 @@ result.continued? # Whether execution continues
 
 ## Tool
 
-**Tools** give robots the ability to interact with external systems. There are two patterns for defining tools:
+**Tools** give robots the ability to interact with external systems. `RobotLab::Tool` extends `RubyLLM::Tool` with graceful error handling — if `execute` raises a `StandardError`, the error is caught and returned as a plain-text string (`"Error (tool_name): message"`) so the LLM can reason about it. Critical tools can opt out with `self.raise_on_error = true`.
+
+There are two patterns for defining tools:
 
 ### RubyLLM::Tool Subclass (Preferred)
 
@@ -446,7 +450,7 @@ Templates support two categories of front matter keys:
 
 **LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` — applied to the robot's chat configuration.
 
-**Robot Extras:** `robot_name`, `description`, `tools`, `mcp` — applied to the robot's identity and capabilities. These make templates self-contained: reading the `.md` file tells you everything about the robot.
+**Robot Extras:** `robot_name`, `description`, `tools`, `mcp`, `skills` — applied to the robot's identity and capabilities. These make templates self-contained: reading the `.md` file tells you everything about the robot.
 
 ```markdown
 ---

data/docs/examples/index.md

@@ -29,7 +29,7 @@ These examples show how to use RobotLab for common scenarios, from simple chatbo
 ### Advanced Examples
 
 - [Streaming Responses](basic-chat.md#with-streaming)
-- [Persistent Conversations](basic-chat.md#with-conversation-history)
+- [Persistent Conversations](basic-chat.md#with-memory)
 - [MCP Integration](mcp-server.md)
 - [Message Bus Communication](#message-bus)
 - [Spawning Robots](#spawning-robots)

data/docs/examples/rails-application.md

@@ -88,7 +88,7 @@ RobotLab.config.logger  #=> Rails.logger
 
 ### Rails Engine and Railtie
 
-RobotLab provides both a Rails Engine (`RobotLab::Rails::Engine`) and a Railtie (`RobotLab::Rails::Railtie`). These are loaded automatically when Rails is detected. The Engine isolates the RobotLab namespace and adds `app/robots` and `app/tools` to the autoload paths. The Railtie loads rake tasks and generators.
+RobotLab provides both a Rails Engine (`RobotLab::RailsIntegration::Engine`) and a Railtie (`RobotLab::RailsIntegration::Railtie`). These are loaded automatically when Rails is detected. The Engine isolates the RobotLab namespace and adds `app/robots` and `app/tools` to the autoload paths. The Railtie loads rake tasks and generators.
 
 ## Models