gem-skill 0.1.3 → 0.2.2

data/lib/gem/skill/cli/gem_command.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require "rubygems/command"
+# gem/skill must be required first: activating the gem-skill spec resolves
+# json to < 3 (ruby_llm's constraint). A bare `require "json"` before that
+# activates the newest installed json and makes the activation raise
+# Gem::ConflictError, which RubyGems swallows — leaving `gem skill` unregistered.
+require "gem/skill"
 require "async"
 require "fileutils"
 require "json"
 require "tty-spinner"
-require "gem/skill"
 
 # Registered as `gem skill` via lib/rubygems_plugin.rb.
 # Manages the global ~/.gem/skills cache.
@@ -14,19 +18,27 @@ class Gem::Commands::SkillCommand < Gem::Command
     super "skill", "Manage Claude Code AI skills for Ruby gems"
 
     add_option("-f", "--force",         "Regenerate even if already cached") { |_, o| o[:force] = true }
+    add_option("--verify",              "Verify generated skill against gem source and fix mismatches (exit #{Gem::Skill::EXIT_VERIFY_FIXED} if fixes applied)") { |_, o| o[:verify] = true }
     add_option("-a", "--all",           "Purge all cached versions of a gem") { |_, o| o[:all] = true }
     add_option("-m", "--model MODEL",   "LLM model to use (default: #{Gem::Skill::Generator::DEFAULT_MODEL})") do |model, o|
       o[:model] = model
     end
+    add_option("--max-tokens TOKENS",   "Max output tokens (overrides GEMSKIL_MAX_TOKENS; default: #{Gem::Skill::Generator::MAX_TOKENS})") do |tokens, o|
+      o[:max_tokens] = tokens.to_i
+    end
+    add_option("--temperature TEMP",    "Sampling temperature; ignored by reasoning models (overrides GEMSKILL_TEMPERATURE; default: #{Gem::Skill::Generator::DEFAULT_TEMPERATURE})") do |temp, o|
+      o[:temperature] = temp.to_f
+    end
     add_option("-v", "--version",       "Print gem-skill version and exit") { |_, o| o[:version] = true }
   end
 
   def arguments
-    "SUBCOMMAND  one of: install, list, purge, setup"
+    "SUBCOMMAND  one of: install, verify, list, purge, setup"
   end
 
   def usage
     "#{program_name} install GEM_NAME [GEM_NAME ...]\n" \
+    "       #{program_name} verify GEM_NAME [GEM_NAME ...]\n" \
     "       #{program_name} list\n" \
     "       #{program_name} purge GEM_NAME VERSION\n" \
     "       #{program_name} purge GEM_NAME --all\n" \
@@ -36,6 +48,8 @@ class Gem::Commands::SkillCommand < Gem::Command
   def description
     <<~DESC
       install   Generate and cache a SKILL.md for a gem.
+      verify    Verify an already-cached skill against the gem's source and fix
+                mismatches (does not generate; errors if not cached).
       list      Show all skills in the global cache (~/.gem/skills).
       purge     Remove a specific cached version.
       setup     Register gem-skill as a Bundler plugin (run once after install).
@@ -53,6 +67,7 @@ class Gem::Commands::SkillCommand < Gem::Command
     subcmd = options[:args].shift
     case subcmd
     when "install" then cmd_install
+    when "verify"  then cmd_verify
     when "list"    then cmd_list
     when "purge"   then cmd_purge
     when "setup"   then cmd_setup
@@ -75,8 +90,11 @@ class Gem::Commands::SkillCommand < Gem::Command
       return
     end
 
-    force = options[:force]
-    model = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+    force       = options[:force]
+    verify      = options[:verify]
+    model       = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+    max_tokens  = options[:max_tokens] || Gem::Skill::Generator::MAX_TOKENS
+    temperature = options[:temperature] || Gem::Skill::Generator::DEFAULT_TEMPERATURE
 
     multi = TTY::Spinner::Multi.new(
       "[:spinner] Generating skills (#{model})",
@@ -84,12 +102,13 @@ class Gem::Commands::SkillCommand < Gem::Command
       output: $stderr
     )
 
+    results = []
     Async do
       barrier = Async::Barrier.new
       gem_names.each do |gem_name|
         spinner = multi.register("  [:spinner] :title")
         spinner.update(title: gem_name)
-        barrier.async { install_one(gem_name, spinner: spinner, force: force, model: model) }
+        barrier.async { results << install_one(gem_name, spinner: spinner, force: force, model: model, verify: verify, max_tokens: max_tokens, temperature: temperature) }
       end
       barrier.wait
     ensure
@@ -97,9 +116,15 @@ class Gem::Commands::SkillCommand < Gem::Command
     end
 
     say "Tip: run 'bundle plugin install gem-skill' to enable 'bundle skill'."
+
+    fixed = results.count(&:verify_fixed)
+    if verify && fixed.positive?
+      say "Verify corrected #{fixed} skill(s) against gem source."
+      terminate_interaction Gem::Skill::EXIT_VERIFY_FIXED
+    end
   end
 
-  def install_one(gem_name, spinner:, force:, model:)
+  def install_one(gem_name, spinner:, force:, model:, verify: false, max_tokens: Gem::Skill::Generator::MAX_TOKENS, temperature: Gem::Skill::Generator::DEFAULT_TEMPERATURE)
     spinner.auto_spin
     version = resolve_installed_version(gem_name)
     if version.nil?
@@ -107,11 +132,77 @@ class Gem::Commands::SkillCommand < Gem::Command
       version = install_gem(gem_name)
     end
     spinner.update(title: "#{gem_name} #{version}")
-    err = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model)
-    alert_error "#{gem_name}: #{err}" if err
+    result = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify, max_tokens: max_tokens, temperature: temperature)
+    alert_error "#{gem_name}: #{result.error}" if result.error
+    result
+  rescue Gem::Skill::Error => e
+    spinner.error("failed")
+    alert_error "#{gem_name}: #{e.message}"
+    Gem::Skill::Runner::Result.failure(e.message)
+  end
+
+  def cmd_verify
+    gem_names = options[:args].dup
+    options[:args].clear
+
+    if gem_names.empty?
+      alert_error "gem_name required. Usage: gem skill verify GEM_NAME [GEM_NAME ...]"
+      return
+    end
+
+    model = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+
+    multi = TTY::Spinner::Multi.new(
+      "[:spinner] Verifying skills (#{model})",
+      format: :dots,
+      output: $stderr
+    )
+
+    results = []
+    Async do
+      barrier = Async::Barrier.new
+      gem_names.each do |gem_name|
+        spinner = multi.register("  [:spinner] :title")
+        spinner.update(title: gem_name)
+        barrier.async { results << verify_one(gem_name, spinner: spinner, model: model) }
+      end
+      barrier.wait
+    ensure
+      barrier.stop
+    end
+
+    fixed = results.count(&:verify_fixed)
+    if fixed.positive?
+      say "Verify corrected #{fixed} skill(s) against gem source."
+      terminate_interaction Gem::Skill::EXIT_VERIFY_FIXED
+    end
+  end
+
+  # Verify an already-cached skill in place. Never generates: the gem must be
+  # installed (verification needs its source) and the skill must already be cached.
+  def verify_one(gem_name, spinner:, model:)
+    spinner.auto_spin
+    version = resolve_installed_version(gem_name)
+    if version.nil?
+      spinner.error("not installed")
+      alert_error "#{gem_name}: not installed locally; verification needs the gem's source. Run 'gem install #{gem_name}' first."
+      return Gem::Skill::Runner::Result.failure("not installed")
+    end
+
+    spinner.update(title: "#{gem_name} #{version}")
+    unless Gem::Skill::Cache.cached?(gem_name, version)
+      spinner.error("not cached")
+      alert_error "#{gem_name} #{version}: no cached skill to verify. Run 'gem skill install #{gem_name}' first."
+      return Gem::Skill::Runner::Result.failure("not cached")
+    end
+
+    result = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: false, model: model, verify: true)
+    alert_error "#{gem_name}: #{result.error}" if result.error
+    result
   rescue Gem::Skill::Error => e
     spinner.error("failed")
     alert_error "#{gem_name}: #{e.message}"
+    Gem::Skill::Runner::Result.failure(e.message)
   end
 
   def cmd_list
@@ -126,13 +217,54 @@ class Gem::Commands::SkillCommand < Gem::Command
     say ""
     gems.each do |name|
       versions = Gem::Skill::Cache.versions(name)
-      say "  %-30s %s" % [name, versions.join(", ")]
+      rendered = versions.map { |v| format_version(name, v) }.join(", ")
+      say "  %-30s %s" % [name, rendered]
     end
     say ""
     say "#{gems.size} gem(s), #{gems.sum { |n| Gem::Skill::Cache.versions(n).size }} version(s) total."
   end
 
+  CHECK_MARK = "✓" # ✓
+
+  # True when the cached skill for this gem/version was verified against source.
+  def skill_verified?(gem_name, version)
+    Gem::Skill::Cache.read_metadata(gem_name, version).dig("verification", "verified") == true
+  end
+
+  # A version label, with a green checkmark appended when the skill is verified.
+  def format_version(gem_name, version)
+    return version unless skill_verified?(gem_name, version)
+
+    "#{version} #{colorize_check}"
+  end
+
+  # The checkmark, ANSI-green only when writing to an interactive terminal so
+  # redirected/piped output stays clean.
+  def colorize_check
+    $stdout.tty? ? "\e[32m#{CHECK_MARK}\e[0m" : CHECK_MARK
+  end
+
+  # Default skill roots that assistants scan automatically. The router skill is
+  # copied into each one whose assistant home directory already exists.
+  ASSISTANT_SKILL_ROOTS = {
+    "Claude Code" => "~/.claude/skills",
+    "OpenAI Codex" => "~/.codex/skills",
+    "Agents (vendor-neutral)" => "~/.agents/skills"
+  }.freeze
+
   def cmd_setup
+    register_bundler_plugin
+    say ""
+    install_router_skill
+  end
+
+  def register_bundler_plugin
+    plugin_list = `bundle plugin list 2>/dev/null`
+    if plugin_list.include?("gem-skill")
+      say "gem-skill is already registered as a Bundler plugin."
+      return
+    end
+
     say "Registering gem-skill as a Bundler plugin..."
     if system("bundle", "plugin", "install", "gem-skill")
       say "Done. Use 'bundle skill install' in any project."
@@ -141,6 +273,36 @@ class Gem::Commands::SkillCommand < Gem::Command
     end
   end
 
+  # Copy the bundled '#{Gem::Skill::ROUTER_SKILL_NAME}' skill into the default
+  # skill root of each detected assistant, so it can discover cached gem skills.
+  def install_router_skill
+    source = File.join(Gem::Skill::ROUTER_SKILL_DIR, "SKILL.md")
+    unless File.exist?(source)
+      alert_error "Router skill not found at #{source}"
+      return
+    end
+
+    say "Installing the '#{Gem::Skill::ROUTER_SKILL_NAME}' skill so assistants can find cached gem skills:"
+    installed = 0
+    ASSISTANT_SKILL_ROOTS.each do |label, root|
+      base = File.expand_path(root)
+      unless Dir.exist?(File.dirname(base))
+        say "  - #{label}: not detected — skipped"
+        next
+      end
+
+      dest_dir = File.join(base, Gem::Skill::ROUTER_SKILL_NAME)
+      FileUtils.mkdir_p(dest_dir)
+      FileUtils.cp(source, File.join(dest_dir, "SKILL.md"))
+      say "  - #{label}: installed -> #{dest_dir.sub(Dir.home, '~')}"
+      installed += 1
+    end
+
+    return unless installed.zero?
+
+    say "  No assistant directories detected. Create ~/.claude or ~/.codex, then re-run 'gem skill setup'."
+  end
+
   def cmd_purge
     gem_name = options[:args].shift
     unless gem_name

data/lib/gem/skill/fetcher.rb

@@ -19,6 +19,10 @@ module Gem::Skill
     README_CANDIDATES    = %w[README.md README.rdoc README.txt README].freeze
     CHANGELOG_CANDIDATES = %w[CHANGELOG.md CHANGELOG.rdoc HISTORY.md CHANGES.md].freeze
 
+    # Cap on concatenated source size handed to the verifier, to protect the
+    # context window on large gems. Files are added whole until the cap is hit.
+    SOURCE_MAX_CHARS = 150_000
+
     attr_reader :gem_name, :version
 
     def initialize(gem_name, version)
@@ -52,8 +56,56 @@ module Gem::Skill
       @examples ||= local_examples
     end
 
+    # The gem's actual Ruby source (lib/**/*.rb), concatenated with per-file
+    # headers. This is the ground truth the verifier checks the skill against.
+    # Returns nil when the gem isn't installed locally or has no lib sources —
+    # verification is only possible against installed source.
+    def source_code
+      source_bundle&.fetch(:code)
+    end
+
     private
 
+    def source_bundle
+      return @source_bundle if defined?(@source_bundle)
+
+      @source_bundle = build_source_bundle
+    end
+
+    def build_source_bundle
+      dir = gem_dir
+      return nil unless dir
+
+      lib = File.join(dir, "lib")
+      return nil unless File.directory?(lib)
+
+      files = Dir.glob(File.join(lib, "**", "*.rb")).sort
+      return nil if files.empty?
+
+      out       = +""
+      included  = []
+      truncated = false
+
+      files.each do |path|
+        relative = path.delete_prefix("#{dir}/")
+        body     = File.read(path, encoding: "utf-8")
+        chunk    = "### #{relative}\n\n```ruby\n#{body}\n```\n\n"
+        if !out.empty? && out.length + chunk.length > SOURCE_MAX_CHARS
+          truncated = true
+          break
+        end
+
+        out << chunk
+        included << relative
+      end
+
+      return nil if out.empty?
+
+      { code: out, files: included, chars: out.length, truncated: truncated }
+    rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      nil
+    end
+
     # --- local gem spec ---
 
     def gem_spec

data/lib/gem/skill/frontmatter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Gem::Skill
+  # Builds the YAML frontmatter that makes a SKILL.md discoverable as an Agent
+  # Skill. Both Claude Code and OpenAI Codex require `name` + `description`
+  # frontmatter; without it the file is never registered/triggered as a skill.
+  #
+  # Constraints satisfied here (intersection of both assistants):
+  #   - name: lowercase letters, digits, hyphens only; no leading/trailing or
+  #     doubled hyphens; <= 40 chars (Claude Code's rule, also valid for Codex)
+  #   - description: single line, no angle brackets (Claude Code rejects < and >),
+  #     length-capped (Codex shortens long descriptions)
+  #
+  # Generation is deterministic (no LLM): the name is derived from the gem name
+  # and the description from the skill's Overview section, so the frontmatter is
+  # always valid regardless of what the model emitted.
+  module Frontmatter
+    MAX_NAME_LENGTH        = 40
+    MAX_DESCRIPTION_LENGTH = 500
+
+    module_function
+
+    # Return content with a freshly-built, valid frontmatter block. Any existing
+    # leading frontmatter is stripped and replaced, so this is idempotent.
+    def build(gem_name, version, content)
+      body = strip(content)
+      fm   = "---\nname: #{slug(gem_name)}\ndescription: #{yaml_quote(description_for(gem_name, version, body))}\n---\n"
+      "#{fm}\n#{body}"
+    end
+
+    # True when content already begins with a YAML frontmatter block.
+    def present?(content)
+      content.to_s.lstrip.start_with?("---")
+    end
+
+    # Remove a leading frontmatter block (if any) and return the body.
+    def strip(content)
+      content.to_s.sub(/\A\s*---\s*\n.*?\n---\s*\n+/m, "").lstrip
+    end
+
+    # Gem name -> valid skill name. "ruby_llm" -> "ruby-llm", "TTY-Spinner" ->
+    # "tty-spinner". Falls back to "skill" if nothing usable remains.
+    def slug(gem_name)
+      s = gem_name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      s = "skill" if s.empty?
+      s[0, MAX_NAME_LENGTH].sub(/-+\z/, "")
+    end
+
+    # Derive a trigger-oriented description from the body's Overview section,
+    # appending the version for context. Sanitized for both assistants.
+    def description_for(gem_name, version, body)
+      overview = body[/^##\s+Overview\s*\n+(.+?)(?=\n\s*\n|\n##\s|\z)/m, 1]
+      text     = overview || "Ruby gem #{gem_name}. Use when working with #{gem_name} in Ruby code."
+      text     = text.gsub(/\s+/, " ").delete("<>").strip
+      text     = "#{text} (#{gem_name} v#{version})" unless text.include?(version.to_s)
+      text[0, MAX_DESCRIPTION_LENGTH].strip
+    end
+
+    # Quote a string as a YAML double-quoted scalar, escaping \ and ".
+    def yaml_quote(str)
+      %("#{str.gsub(/[\\"]/) { |c| "\\#{c}" }}")
+    end
+  end
+end

data/lib/gem/skill/generator.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
+# Provider plugin gems self-register with RubyLLM only when required; without
+# these, "lms/..." and "apfel/..." models are unreachable.
+require "ruby_llm/providers/lms"
+require "ruby_llm/providers/apfel"
 
 module Gem::Skill
   # Drives the LLM pipeline: fetches docs, generates a SKILL.md, caches it.
   class Generator
-    DEFAULT_MODEL = ENV.fetch("GEMSKILL_MODEL", "gpt-5.5")
-    MAX_SOURCE_CHARS = 60_000  # guard against enormous READMEs blowing the context window
+    DEFAULT_MODEL       = ENV.fetch("GEMSKILL_MODEL", "gpt-5.5")
+    MAX_TOKENS          = ENV.fetch("GEMSKIL_MAX_TOKENS", 32_767).to_i
+    DEFAULT_TEMPERATURE = ENV.fetch("GEMSKILL_TEMPERATURE", 0.2).to_f
+    MAX_SOURCE_CHARS    = 60_000  # guard against enormous READMEs blowing the context window
 
     SYSTEM_INSTRUCTIONS = <<~SYSTEM
       You are a Ruby gem documentation specialist who generates Claude Code skill files.
@@ -56,12 +62,15 @@ module Gem::Skill
       %<sources>s
     PROMPT
 
-    attr_reader :gem_name, :version, :model
+    attr_reader :gem_name, :version, :model, :max_tokens, :temperature
 
-    def initialize(gem_name, version, model: DEFAULT_MODEL)
-      @gem_name = gem_name
-      @version  = version
-      @model    = model
+    def initialize(gem_name, version, model: DEFAULT_MODEL, max_tokens: MAX_TOKENS, temperature: DEFAULT_TEMPERATURE)
+      @gem_name    = gem_name
+      @version     = version
+      @model       = model
+      @model_id, @provider = Gem::Skill.parse_model(model)
+      @max_tokens  = max_tokens
+      @temperature = temperature
     end
 
     # Generate and cache a SKILL.md. Returns the skill content string.
@@ -73,6 +82,7 @@ module Gem::Skill
       raise Error, "No documentation found for #{gem_name} #{version}" if sources.empty?
 
       skill_content = block ? call_llm_streaming(sources, &block) : call_llm(sources)
+      skill_content = Frontmatter.build(gem_name, version, skill_content)
       Cache.store(gem_name, version, skill_content, { sources: sources.keys.map(&:to_s), model: model })
       skill_content
     rescue RubyLLM::Error => e
@@ -100,18 +110,41 @@ module Gem::Skill
       strip_wrapper_fence(content)
     end
 
-    # Removes a leading ```markdown (or ```) fence and its closing ```.
-    # Belt-and-suspenders: the prompt instructs the model not to wrap,
-    # but some models do it anyway.
+    # Removes a ```markdown (or ```) fence that wraps the ENTIRE document.
+    # Belt-and-suspenders: the prompt instructs the model not to wrap, but some
+    # models do it anyway. The trailing ``` is only stripped when a matching
+    # opening wrapper fence was present — otherwise a skill that legitimately
+    # ends with a code block would lose its closing fence and leave the block
+    # open.
     def strip_wrapper_fence(content)
-      content
-        .sub(/\A\s*```(?:markdown)?\s*\n/, "")
+      stripped = content.strip
+      return stripped unless stripped.match?(/\A```(?:markdown)?\s*\n/)
+
+      stripped
+        .sub(/\A```(?:markdown)?\s*\n/, "")
         .sub(/\n```\s*\z/, "")
         .strip
     end
 
     def build_chat
-      RubyLLM.chat(model: model).with_instructions(SYSTEM_INSTRUCTIONS)
+      # with_max_output_tokens (ruby_llm >= 2.0) maps to the right request
+      # parameter per provider (max_tokens vs max_completion_tokens).
+      chat = RubyLLM.chat(model: @model_id, provider: @provider).with_max_output_tokens(@max_tokens)
+      chat = chat.with_temperature(@temperature) if temperature_supported?
+      chat.with_instructions(SYSTEM_INSTRUCTIONS)
+    end
+
+    def model_info
+      @model_info ||= RubyLLM.models.find(@model_id, provider: @provider)
+    end
+
+    # Reasoning models (e.g. gpt-5.5) reject a temperature parameter outright.
+    # Only set it for models whose metadata doesn't explicitly mark temperature
+    # unsupported; treat absent metadata as supported.
+    def temperature_supported?
+      return false if @temperature.nil?
+
+      model_info.metadata.fetch(:temperature, true) != false
     end
 
     def format_prompt(sources)

data/lib/gem/skill/linker.rb

@@ -3,12 +3,26 @@
 require "fileutils"
 
 module Gem::Skill
-  # Manages .claude/skills/ symlinks in a project, pointing to ~/.gem/skills cache.
+  # Manages per-project skill symlinks pointing into the ~/.gem/skills cache.
   # Each symlink is a directory link: <gem_name> -> ~/.gem/skills/<gem>/<version>/
-  # Claude Code discovers skills by reading SKILL.md inside each linked directory.
+  # The assistant discovers skills by reading SKILL.md inside each linked directory.
+  #
+  # The project-relative directory is configurable via GEMSKILL_PROJECT_DIR
+  # (default ".claude/skills" for Claude Code). Codex users might set it to
+  # ".agents" or ".codex"; see the configuration docs.
   module Linker
+    DEFAULT_PROJECT_DIR = ".claude/skills"
+
+    # Project-relative directory where skill symlinks are written. Read from the
+    # environment each call so a changed GEMSKILL_PROJECT_DIR takes effect without
+    # reloading.
+    def self.project_dir
+      value = ENV.fetch("GEMSKILL_PROJECT_DIR", DEFAULT_PROJECT_DIR).to_s.strip
+      value.empty? ? DEFAULT_PROJECT_DIR : value
+    end
+
     def self.skills_dir(project_root = Dir.pwd)
-      File.join(project_root, ".claude", "skills")
+      File.join(project_root, project_dir)
     end
 
     def self.link(gem_name, version, project_root = Dir.pwd)

data/lib/gem/skill/runner.rb

@@ -1,24 +1,90 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Gem::Skill
   # Core install logic shared by gem_command and bundle_command.
   # Callers are responsible for spinner.auto_spin and title setup before calling.
   module Runner
-    # Generate + cache + link one skill.
-    # Returns nil on success, error message string on failure.
-    def self.install_skill(gem_name, version, spinner, force:, model:)
+    # error:        nil on success, message string on failure
+    # verify_fixed: true when --verify ran and corrected the skill
+    Result = Data.define(:error, :verify_fixed) do
+      def ok? = error.nil?
+
+      def self.failure(message) = new(error: message, verify_fixed: false)
+      def self.success(verify_fixed: false) = new(error: nil, verify_fixed: verify_fixed)
+    end
+
+    # Generate + cache + link one skill, optionally verifying it against source.
+    # Returns a Runner::Result.
+    def self.install_skill(gem_name, version, spinner, force:, model:, verify: false,
+                           max_tokens: Generator::MAX_TOKENS, temperature: Generator::DEFAULT_TEMPERATURE)
       if Cache.cached?(gem_name, version) && !force
         Linker.link(gem_name, version)
-        spinner.success("already cached")
-        return nil
+        content = Cache.read(gem_name, version)
+        return finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "already cached")
       end
-      Generator.new(gem_name, version, model: model).generate(force: force)
+
+      # Stream and discard chunks: a non-streaming request sends nothing over
+      # the socket until generation completes, so a slow local model (reasoning
+      # models especially) trips Net::ReadTimeout regardless of how high the
+      # timeout is set. Streaming keeps bytes flowing between chunks.
+      generator = Generator.new(gem_name, version, model: model, max_tokens: max_tokens, temperature: temperature)
+      content   = generator.generate(force: force) { |_chunk| }
       Linker.link(gem_name, version)
-      spinner.success("done")
-      nil
+      finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "done")
     rescue => e
       spinner.error("failed")
-      e.message
+      Result.failure(e.message)
+    end
+
+    # Run the optional verify pass and settle the spinner + metadata.
+    def self.finalize(gem_name, version, content, spinner, model:, verify:, status:)
+      unless verify
+        spinner.success(status)
+        return Result.success
+      end
+
+      result = Verifier.new(gem_name, version, model: model).verify(content)
+
+      unless result.verifiable
+        Cache.merge_metadata(gem_name, version, verification: {
+          verified:       false,
+          verified_at:    Time.now.iso8601,
+          model:          model,
+          skipped_reason: "no installed source available"
+        })
+        spinner.success("#{status} (no source to verify)")
+        return Result.success
+      end
+
+      Cache.write_skill(gem_name, version, result.content) if result.changed?
+      Cache.merge_metadata(gem_name, version, verification: verification_metadata(result))
+
+      if result.changed?
+        spinner.success("verified — fixed")
+        Result.success(verify_fixed: true)
+      else
+        spinner.success("verified — ok")
+        Result.success
+      end
+    rescue => e
+      spinner.error("verify failed")
+      Result.failure(e.message)
+    end
+    private_class_method :finalize
+
+    # Records that the skill was verified against real source and whether that
+    # verification changed anything. Intentionally minimal — the itemized list of
+    # what changed is not retained.
+    def self.verification_metadata(result)
+      {
+        verified:    true,
+        verified_at: Time.now.iso8601,
+        model:       result.model,
+        fixed:       result.changed?
+      }
     end
+    private_class_method :verification_metadata
   end
 end