omakase-agents 0.0.1.alpha → 0.0.2.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1cd37ac842736548d6501feab0ad139df3bad22437902f19ead73ed5eae819c
-  data.tar.gz: 733def6d93d950e7bd1507240877d90447dd7359255ba4e3c5bc3d93ce3794c6
+  metadata.gz: 96b04f8669c6e6bf4f176d19b779ca495fb1b2fde034952c48175eb2999647b3
+  data.tar.gz: 32d2d58018dd35cf63590c889f6c9e5a8bca214e1ccfcd9989c0f90c157bec70
 SHA512:
-  metadata.gz: 78f54588fa331091f7e604bab6637a31a9f7f14298b0f513df78e243f851079f9181c2c71c627f0a33d5069ec541711adee81e17516916077990b5e1495a4533
-  data.tar.gz: 4c97ef7304cce538f6dd4b9d95d6c7053bc6fff9ee6cab88a02b9d44ccdc38e78edfcf95d669a3a9a20fd9f94557d28e05b714eeac3405957d47e1e615f89592
+  metadata.gz: e596c18452218540f3a92c7f2542cbf1ea7e5b4fe0314c359e784d14fe331defdaf40f642cd4679667ed0e6ca5c8e42bd171cb940b2b2bd6b3fd47faba41bf97
+  data.tar.gz: 18e626683d93029d7d29da409b9f456800cf4b0579e9e478636d4b8ff2902f628ef34460cf3dd935b164e76d057bc3b01bb22c3a4b58fe9c15c354befbdc9cf9

data/README.md

@@ -1,8 +1,10 @@
 # Omakase
 
-A light agent framework — about 600 lines of library. *Omakase* (お任せ): you name what you want,
+A light agent framework — about 700 lines of library. *Omakase* (お任せ): you name what you want,
 the rest is left to the chef.
 
+**[esshka.github.io/omakase](https://esshka.github.io/omakase/)** · [rubygems](https://rubygems.org/gems/omakase-agents) ![gem](https://img.shields.io/gem/v/omakase-agents?include_prereleases&color=c8452e&label=)
+
 The whole philosophy: **an agent is an object**. Its fields are state, its methods are what the
 model can call, and the methods it *declares without a body* are written by the model at runtime —
 the method name and prompt are the specification, the schema is the contract.
@@ -40,13 +42,11 @@ Ruby 3.2+.
 gem "omakase-agents"     # the library is `Omakase`
 ```
 
-Alpha (`0.0.1.alpha`) and not on RubyGems yet, so until it is, build it from a checkout:
+From the command line the flag is needed — `0.0.2.alpha` is a prerelease, and RubyGems skips those
+unless asked. Bundler resolves it without one, since no stable version exists yet.
 
 ```bash
-git clone https://github.com/esshka/omakase
-cd omakase
-gem build omakase-agents.gemspec
-gem install ./omakase-agents-*.gem
+gem install omakase-agents --pre
 ```
 
 ## Usage
@@ -131,8 +131,45 @@ Omakase.configure do |config|
 end
 ```
 
+### MCP tools
+
+An MCP server's tools become methods on the agent, listed among its capabilities like any other —
+so generated code calls a remote tool and the agent's own methods in the same expression. Add the
+`ruby_llm-mcp` gem; options are passed to it verbatim.
+
+```ruby
+class DocsAgent < ApplicationAgent
+  mcp :files,
+    transport_type: :stdio,
+    config: {command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", Rails.root.to_s]}
+
+  generates :changelog, "Summarise what changed in the last release."
+end
+```
+
+The connection opens when the class is defined and the tools are read from the server then, so a
+tool's arguments reach the model as documentation. A failed call raises, which the model sees and
+can correct. Only text comes back: an image or audio result is dropped.
 ### Testing
 
+### Skills
+
+A skill is a directory with a `SKILL.md` — the same YAML front matter Claude Code and friends use.
+`skill` reads it and defines one method: the front matter's `description` joins the agent's
+capabilities, and the body is what the method returns.
+
+```ruby
+class CommitAgent < ApplicationAgent
+  skill "skills/commit-style"    # description: "How this project writes commit subjects…"
+
+  generates :subject_for, "Write the commit subject for this change.", returns: :string
+end
+```
+
+That is the whole of “loaded on demand”: the one-line description is in the prompt, the body only
+reaches the model if the generated code calls `commit_style`. Anything else the skill ships —
+scripts, templates — sits in the same directory, and the body ends with its path, so generated Ruby
+can read or run it.
 `Omakase::Agent.new(chat:)` takes any object that quacks like a `RubyLLM::Chat`, and one ships with
 the library, so agents are tested without a network:
 
@@ -278,6 +315,8 @@ generates :plan, strategy: CriticStrategy
     lib/omakase/doc.rb             what an unfamiliar object offers, for generated code
     lib/omakase/executor.rb        runs generated Ruby against the agent
     lib/omakase/tools/ruby.rb      that executor, as a RubyLLM tool, with a call budget
+    lib/omakase/mcp.rb             an MCP server’s tools, as methods on the agent
+    lib/omakase/skills.rb          a SKILL.md directory, as one described method
     lib/omakase/fake_chat.rb       the stand-in chat for tests
     lib/omakase/strategies/        code_act, predict
 
@@ -293,6 +332,8 @@ Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pi
 | [`support_agent.rb`](examples/support_agent.rb) | plain Ruby orchestrating generated methods |
 | [`support_job.rb`](examples/support_job.rb) | generation off the request thread, via ActiveJob |
 | [`rails_app.rb`](examples/rails_app.rb) | a whole Rails app in one file: initializer, agent, controller |
+| [`mcp_agent.rb`](examples/mcp_agent.rb) | an MCP server's tools as methods on the agent |
+| [`skill_agent.rb`](examples/skill_agent.rb) | a SKILL.md directory the model loads when it needs it |
 
 ```bash
 bundle exec rake                     # tests, no network
@@ -327,10 +368,10 @@ What is not here yet, roughly in the order it would earn its place:
 - [ ] **Conversation history** — the chat is fresh per call. Keeping one per agent would let a
       method continue where the last one left off, at the cost of deciding what to keep.
 - [ ] **Session storage** — persist that history and the agent state so a run can be resumed.
-- [ ] **MCP tools** — external tools over the Model Context Protocol, via `ruby_llm-mcp`. Cheap to
-      add, since generated code can call anything the agent exposes.
-- [ ] **Skills** — capabilities as markdown files with front matter, loaded on demand rather than
-      all sitting in the system prompt.
+- [x] **MCP tools** — external tools over the Model Context Protocol, via `ruby_llm-mcp`. Done:
+      `mcp :files, …` puts the server's tools on the agent, and generated code calls them.
+- [x] **Skills** — capabilities as markdown files with front matter, loaded on demand rather than
+      all sitting in the system prompt. Done: `skill "path/to/dir"`, one described method.
 - [ ] **Memory** — recall that survives across sessions, backed by vector search.
 - [x] **Concurrency** — parallel generation calls. Done: output is buffered per thread instead of
       through `$stdout`, so threads no longer collide.

data/lib/omakase/agent.rb

@@ -27,6 +27,16 @@ module Omakase
         @strategy = name
       end
 
+      # An MCP server's tools, as methods on the agent. Options are passed to
+      # `ruby_llm-mcp` verbatim: `mcp :files, transport_type: :stdio, config: {command: "npx", …}`.
+      def mcp(name, **options)
+        require "ruby_llm/mcp"
+        MCP.attach(self, RubyLLM::MCP.add_client(name: name.to_s, **options))
+      end
+
+      # A skill directory — a SKILL.md with YAML front matter. Its description
+      # joins the agent's capabilities; its body arrives when the model asks.
+      def skill(path) = Skills.attach(self, path)
       # Documents the method defined next — the docstring Ruby does not have.
       def describe(text)
         @pending_description = text

data/lib/omakase/mcp.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Omakase
+  # An MCP server's tools, as methods on the agent — so generated code calls a
+  # remote tool the same way it calls anything else the agent exposes.
+  module MCP
+    module_function
+
+    def attach(agent_class, client)
+      client.tools.each do |tool|
+        name = method_name(tool)
+        # A remote tool list must not quietly shadow a capability the agent already has.
+        raise Error, "#{agent_class} already has ##{name}" if Capabilities.names(agent_class).include?(name)
+
+        agent_class.describe(description(tool))
+        # nil is how a model leaves an argument out; MCP servers reject it.
+        agent_class.define_method(name) { |**arguments| MCP.result(tool.execute(**arguments.compact)) }
+      end
+      client
+    end
+
+    # Tool names may hold characters a Ruby method name cannot.
+    def method_name(tool) = tool.name.tr("-", "_").to_sym
+
+    # ponytail: text only — an image or audio result is dropped.
+    def result(value)
+      raise Error, value[:error] if value.is_a?(Hash) && value[:error]
+
+      value.to_s
+    end
+
+    # The signature is `**arguments`, so what those arguments are goes here.
+    def description(tool)
+      schema = tool.params_schema || {}
+      required = schema["required"] || []
+      arguments = (schema["properties"] || {}).map do |name, property|
+        "#{name}: #{property["type"]}#{" (required)" if required.include?(name)}"
+      end
+      text = tool.description.to_s.gsub(/\s+/, " ").strip
+      [text, ("Arguments — #{arguments.join(", ")}" if arguments.any?)].compact.join(" ")
+    end
+  end
+end

data/lib/omakase/skills.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Omakase
+  # A skill is a directory with a SKILL.md: YAML front matter says what it is,
+  # the body is the guidance. The description is listed with the agent's other
+  # capabilities; the body only arrives when the model calls the method — which
+  # is all "loaded on demand" has to mean.
+  module Skills
+    module_function
+
+    def attach(agent_class, path)
+      directory = File.expand_path(path)
+      front_matter, body = parse(File.read(File.join(directory, "SKILL.md")))
+      name = (front_matter["name"] || File.basename(directory)).tr("-", "_").to_sym
+      raise Error, "#{agent_class} already has ##{name}" if Capabilities.names(agent_class).include?(name)
+
+      agent_class.describe(front_matter["description"].to_s)
+      agent_class.define_method(name) { "#{body}\n\nFiles for this skill are in #{directory}." }
+      name
+    end
+
+    # The front matter every SKILL.md in the wild is written with.
+    def parse(text)
+      match = text.match(/\A---\n(.*?)\n---\n(.*)\z/m)
+      return [{}, text.strip] unless match
+
+      [YAML.safe_load(match[1]), match[2].strip]
+    end
+  end
+end

data/lib/omakase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omakase
-  VERSION = "0.0.1.alpha"
+  VERSION = "0.0.2.alpha"
 end

data/lib/omakase.rb

@@ -8,9 +8,11 @@ require "schematist"
 require "stringio"
 require "timeout"
 require "zeitwerk"
+require "yaml"
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore("#{__dir__}/omakase-agents.rb")
+loader.inflector.inflect("mcp" => "MCP")
 loader.setup
 
 module Omakase

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha
+  version: 0.0.2.alpha
 platform: ruby
 authors:
 - eugeny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -73,8 +73,10 @@ files:
 - lib/omakase/executor.rb
 - lib/omakase/fake_chat.rb
 - lib/omakase/generation.rb
+- lib/omakase/mcp.rb
 - lib/omakase/request.rb
 - lib/omakase/schema.rb
+- lib/omakase/skills.rb
 - lib/omakase/strategies.rb
 - lib/omakase/strategies/code_act.rb
 - lib/omakase/strategies/predict.rb