robot_lab 0.1.0 → 0.2.1

data/docs/superpowers/specs/2026-05-06-agentskills-design.md

@@ -0,0 +1,247 @@
+# AgentSkills.io Support — Design Spec
+
+**Date:** 2026-05-06
+**Status:** Approved
+
+## Overview
+
+Add support for the [AgentSkills.io](https://agentskills.io) open standard to RobotLab's existing skills system. Skills are currently single `.md` prompt_manager template files referenced by symbol ID. This spec extends `skills:` to also recognize the AgentSkills folder format (`~/.prompts/skills/<name>/SKILL.md`) with bundled scripts auto-exposed as tools and runtime embedding-based matching for progressive disclosure.
+
+## Goals
+
+- Unified `skills:` API — no new constructor params; format detected automatically
+- AgentSkills folder skills use runtime embedding similarity to decide injection per `run()` call
+- Scripts in `scripts/` auto-wrapped as `RobotLab::Tool` subclasses
+- Zero breakage to existing PM template skills behavior
+- Graceful degradation when embeddings fail or no skills match
+
+## Non-Goals
+
+- Automatic catalog-wide skill discovery without explicit `skills:` listing
+- Fetching remote skills from registries
+- Skills referencing `references/` or `assets/` sub-folders (deferred)
+- Modifying the AgentSkills.io specification
+
+---
+
+## Discovery Path
+
+AgentSkill folders are resolved from a single fixed root: `~/.prompts/skills/`. Given `skills: [:check_style]`, the loader checks `~/.prompts/skills/check_style/SKILL.md`. If that file exists, it is an AgentSkill. If not, the existing PM template resolution applies.
+
+This root is not configurable in v1.
+
+---
+
+## New Classes
+
+### `RobotLab::AgentSkill`
+
+Plain Ruby value object. Constructed by the catalog or the expand_skills loader.
+
+```
+AgentSkill
+  name:         String       # from SKILL.md front matter
+  description:  String       # from SKILL.md front matter — used for embedding
+  path:         Pathname     # directory path
+  instructions: String       # lazy: SKILL.md body — everything after the closing ---
+  scripts:      Array<Pathname>  # lazy: glob of scripts/*
+```
+
+- `instructions` and `scripts` are loaded on first access (lazy).
+- Raises `RobotLab::ConfigurationError` on construction if `SKILL.md` is missing `name` or `description`.
+- `description_vector` — memoized fastembed **passage** embedding of `description` (`DocumentStore#passage_vector`), computed on first match attempt.
+
+### `RobotLab::AgentSkillCatalog`
+
+Module-level singleton (`RobotLab::AgentSkillCatalog`). Scans `~/.prompts/skills/` at process start (lazy, on first access). Caches `AgentSkill` objects keyed by name symbol.
+
+Responsibilities:
+- `find(id)` — return `AgentSkill` for a given symbol, or `nil`
+- `all` — return all discovered skills
+- Internal: compute and cache description vectors using the `DocumentStore` fastembed infrastructure
+
+### `RobotLab::AgentSkillMatching`
+
+Module included in `Robot`. Contains the `run()` override and the similarity logic.
+
+### `RobotLab::ScriptTool`
+
+Factory method `ScriptTool.from_path(path)` returns an anonymous `RobotLab::Tool` subclass. The tool:
+- Name: script filename without extension, underscored (e.g. `check_style`)
+- Description: first comment line of the script, or `"Run #{name}"`
+- Execution: shells out via `Open3.capture2e`, returns stdout+stderr as the tool result
+- Raises `RobotLab::ToolNotFoundError` if the script is not executable
+
+---
+
+## Modified Code
+
+### `Robot::TemplateRendering#expand_skills`
+
+Before resolving a skill ID as a PM template, check `AgentSkillCatalog.find(skill_id)`:
+
+```
+expand_skills([:runbook_protocol, :check_style], visited)
+  :runbook_protocol → catalog.find → nil → PM template (existing path)
+  :check_style      → catalog.find → AgentSkill<check_style>
+                       → store in @pending_agent_skills
+                       → do NOT add to @expanded_skills
+```
+
+`@expanded_skills` continues to hold only PM-format skill IDs, preserving all existing behavior.
+
+### `Robot` constructor
+
+Add `@pending_agent_skills = []` alongside `@expanded_skills = nil`.
+
+### `Robot::AgentSkillMatching#run`
+
+Prepended to `Robot` to intercept `run()`:
+
+```ruby
+def run(message, **kwargs)
+  activated = match_agent_skills(message)
+  inject_agent_skills(activated)
+  super
+ensure
+  restore_after_agent_skills(activated)
+end
+```
+
+**`match_agent_skills(message)`**
+1. Return `[]` if `@pending_agent_skills` is empty
+2. Embed `message` as a **query** vector (`DocumentStore#query_vector`) — distinct from the passage embedding used for skill descriptions
+3. For each pending AgentSkill, compute cosine similarity between message query-vector and `skill.description_vector` (passage-vector)
+4. Return skills where similarity >= `SIMILARITY_THRESHOLD` (default: `0.70`)
+
+**`inject_agent_skills(skills)`**
+1. Prepend each skill's `instructions` to the chat's system prompt (using `with_instructions`)
+2. Instantiate `ScriptTool` for each script in each skill's `scripts/`; add to `@local_tools`
+
+**`restore_after_agent_skills(skills)`**
+1. Remove injected script tools from `@local_tools`
+2. Restore system prompt to pre-injection state
+
+The system prompt is snapshotted before injection and restored in the `ensure` block so state does not accumulate across calls.
+
+---
+
+## SKILL.md Format
+
+Follows the AgentSkills.io specification. Front matter is YAML; body is Markdown.
+
+```markdown
+---
+name: check_style
+description: Review Ruby code style against project conventions
+---
+When reviewing code, check for:
+- Frozen string literal comments
+- Method length under 20 lines
+- No inline rescue
+```
+
+RobotLab reads only `name` and `description` from front matter. All other front matter keys are ignored (no LLM config via SKILL.md — that remains the PM template system's domain).
+
+---
+
+## Script Tools
+
+Given `~/.prompts/skills/check_style/scripts/run_rubocop.sh`:
+
+- Tool name: `run_rubocop`
+- Description: first `# comment` line in the file, else `"Run run_rubocop"`
+- Input: optional `args` string passed as CLI arguments
+- Execution: `Open3.capture2e("bash #{path} #{args}")`, returns combined output
+- Not executable → log warn, skip (no error raised to the robot)
+
+---
+
+## Similarity Threshold
+
+Default: `0.70` (cosine similarity, 0..1 range).
+
+Accessible as `RobotLab::AgentSkillMatching::SIMILARITY_THRESHOLD`. Not yet user-configurable in v1; a future `config.agent_skill_threshold` can override it.
+
+---
+
+## Error Handling
+
+| Situation | Behavior |
+|---|---|
+| `SKILL.md` missing `name` or `description` | `ConfigurationError` raised at catalog load |
+| fastembed fails on message | Log warn, skip all AgentSkill injection for that call |
+| Script not executable | Log warn, skip that tool; other scripts still wrap |
+| No skills match threshold | Normal `run()` with no injection |
+| Circular skill reference via AgentSkill | Existing cycle detection in `expand_skills` handles it |
+
+---
+
+## Testing
+
+### Unit tests (`test/robot_lab/agent_skill_test.rb`)
+- Parses `SKILL.md` front matter correctly
+- Raises `ConfigurationError` when `name` or `description` missing
+- `instructions` lazy-loads body content
+- `scripts` lazy-globs `scripts/` directory
+
+### Unit tests (`test/robot_lab/agent_skill_catalog_test.rb`)
+- Scans fixture skills directory
+- `find` returns correct `AgentSkill` by symbol
+- `find` returns `nil` for unknown ID
+
+### Unit tests (`test/robot_lab/script_tool_test.rb`)
+- `from_path` produces a tool with correct name and description
+- Tool execution returns stdout+stderr
+- Non-executable script skipped with warning
+
+### Unit tests (`test/robot_lab/robot/agent_skill_matching_test.rb`)
+- `match_agent_skills` returns skills above threshold (mock embeddings)
+- `match_agent_skills` returns empty when below threshold
+- `inject_agent_skills` prepends instructions to system prompt
+- `restore_after_agent_skills` removes injected tools and restores prompt
+- Empty `@pending_agent_skills` short-circuits without embedding
+
+### Integration tests (`test/robot_lab/robot_test.rb`)
+- Robot with `skills: [:pm_template, :agent_skill_fixture]` correctly expands PM template eagerly and AgentSkill at runtime
+- AgentSkill scripts appear in tool list during run, absent after
+
+### Fixtures
+- `test/fixtures/skills/test_skill/SKILL.md` — valid skill
+- `test/fixtures/skills/bad_skill/SKILL.md` — missing description
+- `test/fixtures/skills/scripted_skill/SKILL.md` + `scripts/hello.sh`
+
+---
+
+## File Layout
+
+```
+lib/robot_lab/
+  agent_skill.rb                   # AgentSkill value object
+  agent_skill_catalog.rb           # Singleton scanner/registry
+  script_tool.rb                   # ScriptTool factory
+  robot/
+    agent_skill_matching.rb        # run() override mixin
+
+test/robot_lab/
+  agent_skill_test.rb
+  agent_skill_catalog_test.rb
+  script_tool_test.rb
+  robot/
+    agent_skill_matching_test.rb
+
+test/fixtures/skills/
+  test_skill/SKILL.md
+  bad_skill/SKILL.md
+  scripted_skill/SKILL.md
+  scripted_skill/scripts/hello.sh
+```
+
+---
+
+## Open Questions (deferred)
+
+- `references/` and `assets/` subdirectories: make content available as context variables in future
+- User-configurable similarity threshold via `RobotLab.config`
+- Auto-catalog mode: discover all skills without explicit `skills:` listing
+- AgentSkill nesting (a SKILL.md referencing other skill IDs)

data/examples/.envrc

@@ -0,0 +1 @@
+export ROBOT_LAB_TEMPLATE_PATH="${PWD}/prompts"

data/examples/01_simple_robot.rb

@@ -8,20 +8,16 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/01_simple_robot.rb
 
-# Configure template path before loading (MywayConfig reads env vars on init)
-ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
-
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # Create a simple robot using a template
 robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "helper",
-  template: :helper,
-  model: "claude-3-haiku-20240307"
+  template: :helper
 )
 
-puts "Running simple robot..."
-puts "-" * 40
+banner "Simple Robot"
 
 # Run the robot
 result = robot.run("What is 2 + 2? Please explain your reasoning briefly.")
@@ -32,4 +28,4 @@ puts "Output:"
 result.output.each do |message|
   puts "  #{message.content}" if message.respond_to?(:content)
 end
-puts "-" * 40
+hr

data/examples/02_tools.rb

@@ -8,10 +8,7 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/02_tools.rb
 
-# Configure template path before loading (MywayConfig reads env vars on init)
-ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
-
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # Define tools using RubyLLM::Tool
 class Calculator < RubyLLM::Tool
@@ -81,14 +78,13 @@ end
 
 # Create robot with tools
 robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "assistant",
   template: :assistant,
-  local_tools: [Calculator, FortuneCookie],
-  model: "claude-3-haiku-20240307"
+  local_tools: [Calculator, FortuneCookie]
 )
 
-puts "Running robot with tools..."
-puts "-" * 40
+banner "Robot with Tools"
 
 # Run the robot
 result = robot.run("What is 15 multiplied by 7? Also, give me a fortune about my career.")
@@ -100,4 +96,4 @@ result.output.each do |message|
   puts "  #{message.content}" if message.respond_to?(:content)
 end
 
-puts "-" * 40
+hr

data/examples/03_network.rb

@@ -9,10 +9,7 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/03_network.rb
 
-# Configure template path before loading (MywayConfig reads env vars on init)
-ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
-
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # Classifier robot that activates the appropriate specialist
 class ClassifierRobot < RobotLab::Robot
@@ -40,7 +37,7 @@ class ClassifierRobot < RobotLab::Robot
 end
 
 # Shared RunConfig — all robots in this network use the same model
-shared_config = RobotLab::RunConfig.new(model: "claude-3-haiku-20240307")
+shared_config = RobotLab::RunConfig.new(model: LLM[:default].model)
 
 # Create specialized robots (no model: needed — inherited from RunConfig)
 classifier = ClassifierRobot.new(
@@ -50,18 +47,21 @@ classifier = ClassifierRobot.new(
 )
 
 billing_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "billing",
   template: :billing,
   config: shared_config
 )
 
 technical_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "technical",
   template: :technical,
   config: shared_config
 )
 
 general_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "general",
   template: :general,
   config: shared_config
@@ -75,11 +75,10 @@ network = RobotLab.create_network(name: "support_network", config: shared_config
   task :general, general_robot, depends_on: :optional
 end
 
-puts "Running multi-robot network..."
-puts "-" * 40
+banner "Multi-Robot Network"
 puts "Network structure:"
 puts network.visualize
-puts "-" * 40
+hr
 
 # Run the network with a billing question
 result = network.run(message: "I was charged twice for my subscription last month. Can you help?")
@@ -102,4 +101,4 @@ if result.value.is_a?(RobotLab::RobotResult)
   puts "   Response: #{content[0..200]}..." if content
 end
 
-puts "-" * 40
+hr

data/examples/04_mcp.rb

@@ -21,10 +21,7 @@
 #   - Reading file contents and repository information
 #   - Managing branches and commits
 
-# Configure template path before loading (MywayConfig reads env vars on init)
-ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
-
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # GitHub MCP server configuration using StdIO transport
 github_server = {
@@ -39,14 +36,11 @@ github_server = {
   }
 }
 
-puts <<~HEADER
-  MCP Integration Example: GitHub
-  #{"=" * 40}
-
-  This example demonstrates using the GitHub MCP server to interact
-  with GitHub repositories through the Model Context Protocol.
+banner "MCP Integration Example: GitHub"
 
-HEADER
+puts "This example demonstrates using the GitHub MCP server to interact"
+puts "with GitHub repositories through the Model Context Protocol."
+puts
 
 # Verify prerequisites
 unless ENV["GITHUB_PERSONAL_ACCESS_TOKEN"]
@@ -65,9 +59,7 @@ end
 # Part 1: Direct MCP Client Usage
 # ============================================================================
 
-puts "PART 1: Direct MCP Client Usage"
-puts "-" * 40
-puts
+section "Part 1: Direct MCP Client Usage"
 puts "Connecting to GitHub MCP server..."
 
 begin
@@ -91,7 +83,7 @@ begin
 
   # List available tools
   puts "Available GitHub Tools:"
-  puts "-" * 40
+  hr
 
   tools = client.list_tools
   if tools.empty?
@@ -103,7 +95,7 @@ begin
     end
   end
 
-  puts "-" * 40
+  hr
   puts "Total: #{tools.size} tools available"
   puts
 
@@ -134,22 +126,22 @@ begin
   # Part 2: Robot + MCP Integration
   # ============================================================================
 
-  puts
-  puts "=" * 40
-  puts "PART 2: Robot + MCP Integration"
-  puts "-" * 40
-  puts
+
+  section "Part 2: Robot + MCP Integration"
 
   puts "Creating Robot with MCP server integration..."
   puts
 
-  # Create a Robot with MCP server - tools are automatically discovered
+  # Create a Robot with MCP server - tools are automatically discovered.
+  # connect_mcp! forces eager connection; without it MCP clients initialize
+  # lazily on the first run() call, leaving mcp_clients empty until then.
   robot = RobotLab.build(
+    model: LLM[:default].model,
     name: "github_assistant",
     template: :github_assistant,
-    mcp_servers: [github_server],
-    model: "claude-3-haiku-20240307"
+    mcp_servers: [github_server]
   )
+  robot.connect_mcp!
 
   puts "Robot created: #{robot.name}"
   puts "  Model: #{robot.model}"
@@ -159,7 +151,7 @@ begin
 
   # Show discovered MCP tools
   puts "Discovered MCP Tools:"
-  puts "-" * 40
+  hr
   robot.mcp_tools.first(10).each do |tool|
     puts "  #{tool.name}"
     puts "    #{tool.description&.slice(0, 60)}..." if tool.description
@@ -170,13 +162,13 @@ begin
   # Run the robot with a query that will use MCP tools
   puts "Running Robot with a GitHub query..."
   puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
-  puts "-" * 40
+  hr
 
   result = robot.run("What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.")
 
   puts
   puts "Robot Response:"
-  puts "-" * 40
+  hr
   result.output.each do |msg|
     puts msg.content if msg.respond_to?(:content)
   end
@@ -185,7 +177,7 @@ begin
   # Show tool calls if any were made
   if result.tool_calls.any?
     puts "Tool Calls Made:"
-    puts "-" * 40
+    hr
     result.tool_calls.each do |tc|
       tool_info = tc.respond_to?(:tool) ? tc.tool : tc
       puts "  #{tool_info[:name] || tool_info}"
@@ -212,5 +204,5 @@ rescue Errno::ENOENT
 end
 
 puts
-puts "=" * 40
+hr
 puts "Example complete!"

data/examples/05_streaming.rb

@@ -11,10 +11,7 @@
 # Usage:
 #   ANTHROPIC_API_KEY=your_key ruby examples/05_streaming.rb
 
-# Configure template path before loading (MywayConfig reads env vars on init)
-ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
-
-require_relative "../lib/robot_lab"
+require_relative "common"
 
 # Send logger output to a file instead of stdout
 require 'logger'
@@ -22,19 +19,17 @@ log_file = File.join(__dir__, "05.log")
 RobotLab.config.logger = Logger.new(log_file)
 RubyLLM.configure { |c| c.logger = Logger.new(log_file) }
 
-puts "Streaming Content Example"
-puts "=" * 50
-puts ""
+banner "Streaming Content"
 
 # ── 1. Stored callback (on_content:) ─────────────────────────────
 #
 # Wire streaming at build time. The callback fires on every run() call.
 
-puts "1. Stored callback (on_content:)"
-puts "-" * 50
+section "1. Stored Callback (on_content:)"
 
 chunks_received = 0
 robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "storyteller",
   system_prompt: "You are a concise storyteller. Keep responses under 3 sentences.",
   on_content: ->(chunk) {
@@ -53,11 +48,11 @@ puts ""
 #
 # Pass a block to run() for one-off streaming.
 
-puts "2. Per-call block"
-puts "-" * 50
+section "2. Per-call Block"
 
 block_chunks = 0
 bare_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "factbot",
   system_prompt: "You are concise. Answer in one sentence."
 )
@@ -75,13 +70,13 @@ puts ""
 #
 # When both exist, both fire: stored callback first, then block.
 
-puts "3. Both together (stored fires first, then block)"
-puts "-" * 50
+section "3. Both Together (stored fires first, then block)"
 
 stored_log = []
 block_log  = []
 
 combo_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "combo",
   system_prompt: "You are concise. Answer in one sentence.",
   on_content: ->(chunk) { stored_log << chunk.content }
@@ -101,11 +96,11 @@ puts ""
 #
 # on_content participates in the config cascade.
 
-puts "4. Via RunConfig (config cascade)"
-puts "-" * 50
+section "4. Via RunConfig (config cascade)"
 
 config_chunks = 0
 config = RobotLab::RunConfig.new(
+  model: LLM[:default].model,
   on_content: ->(chunk) {
     print chunk.content
     config_chunks += 1
@@ -113,6 +108,7 @@ config = RobotLab::RunConfig.new(
 )
 
 config_robot = RobotLab.build(
+  model: LLM[:default].model,
   name: "config_bot",
   system_prompt: "You are concise. Answer in one sentence.",
   config: config
@@ -126,9 +122,7 @@ puts ""
 
 # ── Summary ──────────────────────────────────────────────────────
 
-puts "=" * 50
-puts "Summary"
-puts ""
+section "Summary"
 puts <<~SUMMARY
   on_content: callback  — wired at build time, fires every run()
   run() { |chunk| ... } — per-call streaming block