gem-skill 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c425b88d925bd6ef993c1ea04581ffd0e457bebc9137cccf68cf3aacd6e00fde
-  data.tar.gz: ba39b45df96bc6f76c6b2ffa950a3a2cafbba4b7c0b2bfd94ecbd9cd4b38cd06
+  metadata.gz: 3cc3ecc8f770110cc9f8605e149ff2d78c44a388a76add0046c595b01ecbf882
+  data.tar.gz: 21ac18bb7bcc6de52ac9987561da30821be843cca322f0b45b8e04ed1a9af3a1
 SHA512:
-  metadata.gz: 7b4558c9312730d8d7218951591985d868db5bea5f4282f52702ad01feb5ec381c3cfe5af56cb9b50cfa5c45b58e5dbf54bbefee99d6c36d033598383977c35e
-  data.tar.gz: 7464f9cd590e6899ad7a4d2b5a464c42c054ce4287502625349f5cb438e3c66e53e4b56ab7291f8730404f9f9f9f4636a7412cf736a40f40e6dce9a94a5ff048
+  metadata.gz: 4f6fecb42f713486c2abddd7041c6a7294ed4e0cf07affd97457739fe0bd59c8fb080ee80b672817e9a182ff8359896235f2c2c56f16a54eca9528290a3fd07d
+  data.tar.gz: acd79346e7b20fcead6bfff93f4f21aa58f81ac203b3fec5616f2f5f55b6d4337c0919cd01a1790159c7e256ec579c14d8e25c2aaa4cd5d85479fea826c4e3fa

data/CHANGELOG.md

@@ -7,6 +7,22 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 - Bundled `ruby-gem-skills` "router" skill (shipped at the gem root) that teaches assistants how to find cached gem skills in `~/.gem/skills` — a directory neither Claude Code nor Codex scans by default. `gem skill setup` now also copies this skill into each detected assistant's default root (`~/.claude/skills`, `~/.codex/skills`, `~/.agents/skills`), creating none that don't already exist. `Gem::Skill::ROUTER_SKILL_NAME` / `ROUTER_SKILL_DIR` locate the bundled template.
+- `GEMSKIL_MAX_TOKENS` environment variable (default `32767`) — caps the number of output tokens the LLM may generate per skill file. Raise this if generated `SKILL.md` files are being truncated.
+- `--max-tokens TOKENS` CLI flag on `gem skill install`, `bundle skill install`, and `bundle skill refresh` — overrides `GEMSKIL_MAX_TOKENS` for a single invocation. Provider-correct parameter name is selected automatically (`max_completion_tokens` for OpenAI models, `max_tokens` for all others).
+- `GEMSKILL_TEMPERATURE` environment variable (default `0.2`) — sampling temperature for generation. Lower values produce more consistent, less variable output, appropriate for factual reference docs. Applied only to models that support a temperature parameter; reasoning models (e.g. `gpt-5.5`) report `temperature: false` in their RubyLLM metadata and the value is silently skipped for them.
+- `--temperature TEMP` CLI flag on `gem skill install` — overrides `GEMSKILL_TEMPERATURE` for a single invocation.
+
+### Fixed
+- `strip_wrapper_fence` no longer deletes the closing ``` of a skill that legitimately ends with a code block. The trailing wrapper fence is now stripped only when a matching opening wrapper fence (```` ```markdown ```` / ```` ``` ```` at the very start) was present. Previously the final ``` was removed unconditionally, leaving the last code block open at end-of-file — which looked like the LLM truncating its output but was entirely a post-processing bug. Regenerate affected skills with `gem skill install GEM --force`.
+
+### Changed
+- `Generator::MAX_TOKENS` constant reads from `GEMSKIL_MAX_TOKENS` and is passed via `with_params` to every `RubyLLM.chat` call, covering both streaming and non-streaming paths.
+- `Generator#initialize` now accepts `max_tokens:` and `temperature:` keywords so callers can override the token cap and sampling temperature per-instance without touching the environment.
+- `Generator` sets `with_temperature` only when the model's RubyLLM metadata does not mark temperature unsupported, avoiding API errors on reasoning models.
+- `Runner.install_skill` accepts and forwards `max_tokens:` and `temperature:` to `Generator.new`.
+- `README.md` Configuration section now lists all environment variables (gem-skill-specific and provider API keys) in a single reference table.
+- `docs/configuration.md` documents the new `GEMSKIL_MAX_TOKENS` and `GEMSKILL_TEMPERATURE` variables alongside the existing `GEMSKILL_MODEL` entry.
+- `docs/commands/gem-skill.md` and `docs/commands/bundle-skill.md` option tables updated with `--max-tokens` and `--temperature`.
 
 ## [0.2.0] - 2026-06-19
 

data/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem does
+
+`gem-skill` generates `SKILL.md` files from Ruby gem documentation using an LLM (via RubyLLM), caches them globally at `~/.gem/skills/<gem_name>/<version>/SKILL.md`, and symlinks them into projects as directory links: `.claude/skills/<gem_name>/ → ~/.gem/skills/<gem_name>/<version>/`. It registers two CLI entry points: `gem skill` (global cache management) and `bundle skill` (project-aware, driven by `Gemfile.lock`), plus a `gem install --with-skill` flag.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test                                 # run all tests (default task)
+ruby -Ilib:test test/gem/skill/cache_test.rb          # run a single test file
+bundle exec ruby scripts/e2e_test [GEM VERSION MODEL] # live LLM end-to-end test (needs a provider API key)
+bin/dev_install                                       # point Bundler's plugin indexes at this source tree so
+                                                      # `bundle skill` runs local code (no build/release needed)
+bin/dev_install --reset                               # restore to the released gem install
+```
+
+Docs site is MkDocs (`mkdocs.yml`, `docs/`), deployed by `.github/workflows/deploy-github-pages.yml`.
+
+## Architecture
+
+### Entry points
+
+- `lib/rubygems_plugin.rb` — loaded automatically by RubyGems; registers `gem skill` (`Gem::Commands::SkillCommand`) AND prepends `--with-skill` onto `gem install`, queuing installed gems and generating their skills in threads via a `Gem.post_install` hook + `at_exit`
+- `plugins.rb` — Bundler plugin entry point; registers `bundle skill` via `Gem::Skill::BundlerPlugin` → `Gem::Skill::BundlerCommand`
+
+### Core pipeline (in call order)
+
+1. **`Lockfile`** (`lib/gem/skill/lockfile.rb`) — parses `Gemfile.lock`; extracts direct-dependency name→version pairs by cross-referencing the `DEPENDENCIES` and `specs:` sections
+2. **`Fetcher`** (`lib/gem/skill/fetcher.rb`) — collects raw docs for a single gem/version in priority order: (1) local `Gem::Specification` gem_dir, (2) RubyGems API JSON, (3) GitHub raw README. Returns `{metadata:, readme:, changelog:}` with only populated keys
+3. **`Generator`** (`lib/gem/skill/generator.rb`) — formats fetched sources into a prompt, calls RubyLLM, strips any wrapping code fence, runs `Frontmatter.build`, stores result via `Cache`. Supports streaming via block
+4. **`Frontmatter`** (`lib/gem/skill/frontmatter.rb`) — deterministically (no LLM) builds/replaces the YAML frontmatter (`name` + `description`) that makes a SKILL.md discoverable by both Claude Code and Codex; enforces both assistants' name/description constraints
+5. **`Cache`** (`lib/gem/skill/cache.rb`) — reads/writes `~/.gem/skills/<name>/<version>/SKILL.md` and `metadata.json`; `merge_metadata` string-normalizes keys
+6. **`Verifier`** (`lib/gem/skill/verifier.rb`) — optional second LLM pass (`--verify` or `gem skill verify`) that re-checks a generated skill against the gem's actual installed source and corrects wrong signatures/claims. `changed?` is decided by a deterministic content diff, never the model's self-report; unverifiable (no local source) is recorded in metadata, not an error
+7. **`Linker`** (`lib/gem/skill/linker.rb`) — creates/updates directory symlinks in the project skills dir pointing into the cache; `prune_dead_links` removes broken symlinks after a refresh
+
+**`Runner`** (`lib/gem/skill/runner.rb`) is the shared generate+cache+link+verify orchestration used by both CLI commands; it returns a `Runner::Result` (`Data.define`) and drives a TTY spinner passed in by the caller.
+
+### CLI layer
+
+- `lib/gem/skill/cli/gem_command.rb` — `Gem::Commands::SkillCommand`; subcommands: `install`, `verify`, `list`, `purge`, `setup`. Multi-gem installs run concurrently with the `async` gem (`Async::Barrier`). `setup` registers the Bundler plugin and copies the bundled router skill (`ruby-gem-skills/SKILL.md` at repo root) into each detected assistant's global skill root
+- `lib/gem/skill/cli/bundle_command.rb` — `Gem::Skill::BundlerCommand`; subcommands: `install`, `refresh`, `list`. `install` = generate + link all direct lockfile gems; `refresh` = skip gems already linked at the correct version. Parses its own flags (`--force`, `--verify`, `--model`, `--max-tokens`, `--temperature`, `--version`)
+
+### LLM configuration
+
+`Gem::Skill.configure_llm!` reads provider API keys from environment variables (see `ENV_KEY_MAP` in `lib/gem/skill.rb`) and configures RubyLLM. Called automatically by both CLI entry points. No-op if already configured.
+
+## Key constants & environment variables
+
+- `Cache::ROOT` = `~/.gem/skills` (override: `GEMSKILL_DIR`)
+- `Linker::DEFAULT_PROJECT_DIR` = `.claude/skills` (override: `GEMSKILL_PROJECT_DIR`, re-read on every call — e.g. `.agents` for Codex)
+- `Generator::DEFAULT_MODEL` = `"gpt-5.5"` (override: `GEMSKILL_MODEL` or `--model`)
+- `Generator::MAX_TOKENS` = 32,767 (override: `GEMSKIL_MAX_TOKENS` — note the single-L spelling — or `--max-tokens`)
+- `Generator::DEFAULT_TEMPERATURE` = 0.2 (override: `GEMSKILL_TEMPERATURE` or `--temperature`; skipped for models that reject temperature)
+- `Generator::MAX_SOURCE_CHARS` = 60,000 (README truncation guard)
+- `Gem::Skill::EXIT_VERIFY_FIXED` = 2 — grep-style exit status when `--verify` applied fixes (0 = clean, 1 = error)
+
+## Testing
+
+Uses Minitest (`Minitest::TestTask`). Unit tests live in `test/gem/skill/`; shared cache-sandboxing helpers in `test/support/cache_helpers.rb`. `scripts/e2e_test` runs a full live pipeline (fetch → generate → cache → link) against a real LLM and requires at least one provider API key.

data/README.md

@@ -104,13 +104,22 @@ export GEMINI_API_KEY="..."      # or Gemini
 
 ## Configuration
 
-Two environment variables control `gem-skill`'s behaviour:
+All environment variables and their defaults:
 
 | Variable | Default | Description |
 |---|---|---|
 | `GEMSKILL_DIR` | `~/.gem/skills` | Root directory for the global skill cache |
 | `GEMSKILL_PROJECT_DIR` | `.claude/skills` | Project-relative directory where `bundle skill` writes symlinks |
 | `GEMSKILL_MODEL` | `gpt-5.5` | LLM model used when generating skills |
+| `GEMSKIL_MAX_TOKENS` | `32767` | Maximum output tokens per generated skill file |
+| `GEMSKILL_TEMPERATURE` | `0.2` | Sampling temperature (skipped for reasoning models that reject it) |
+| `ANTHROPIC_API_KEY` | _(none)_ | API key for Anthropic / Claude models |
+| `OPENAI_API_KEY` | _(none)_ | API key for OpenAI / GPT models |
+| `GEMINI_API_KEY` | _(none)_ | API key for Google Gemini models |
+| `MISTRAL_API_KEY` | _(none)_ | API key for Mistral models |
+| `DEEPSEEK_API_KEY` | _(none)_ | API key for DeepSeek models |
+| `OPENROUTER_API_KEY` | _(none)_ | API key for OpenRouter |
+| `XAI_API_KEY` | _(none)_ | API key for xAI (Grok) models |
 
 ```bash
 # Store skills on a shared drive accessible to all projects
@@ -121,6 +130,9 @@ export GEMSKILL_MODEL="claude-sonnet-4-6"
 
 # Codex users: link skills into a Codex project root instead of .claude/skills
 export GEMSKILL_PROJECT_DIR=".agents"   # or ".codex"
+
+# Raise the output token cap if generated skill files are being truncated
+export GEMSKIL_MAX_TOKENS=65536
 ```
 
 The `--model` flag on any command overrides `GEMSKILL_MODEL` for that

data/docs/commands/bundle-skill.md

@@ -46,6 +46,7 @@ bundle skill install [OPTIONS]
 | `--force` | Regenerate even if skills are already cached |
 | `--verify` | Verify generated skills against each gem's source and fix mismatches (exit `2` if any fixes applied) |
 | `--model MODEL` | LLM model to use (overrides `GEMSKILL_MODEL`) |
+| `--max-tokens TOKENS` | Max output tokens per skill (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
 **Example:**
@@ -98,6 +99,7 @@ bundle skill refresh [OPTIONS]
 |------|-------------|
 | `--force` | Regenerate all skills, even those already at the correct version |
 | `--model MODEL` | LLM model to use |
+| `--max-tokens TOKENS` | Max output tokens per skill (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
 
 `refresh` skips gems that are already linked at the correct version (shows
 `up to date`), regenerates gems whose version changed, and removes dead symlinks

data/docs/commands/gem-skill.md

@@ -20,6 +20,8 @@ gem skill install GEM_NAME [GEM_NAME ...]
 | `--force`, `-f` | Regenerate even if a skill is already cached |
 | `--verify` | After generating, verify the skill's code against the gem's actual source and fix mismatches |
 | `--model MODEL`, `-m MODEL` | LLM model to use (overrides `GEMSKILL_MODEL`) |
+| `--max-tokens TOKENS` | Max output tokens for this run (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
+| `--temperature TEMP` | Sampling temperature, skipped by reasoning models (overrides `GEMSKILL_TEMPERATURE`; default: 0.2) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
 **Examples:**
@@ -36,6 +38,12 @@ gem skill install rails --force --model claude-opus-4-8
 
 # Generate, then verify the result against the gem's source code
 gem skill install tty-spinner --verify
+
+# Raise the token cap to avoid truncated output
+gem skill install rails --max-tokens 65536
+
+# Lower the temperature for more reproducible output (temperature-capable models)
+gem skill install faraday --model claude-sonnet-4-6 --temperature 0.0
 ```
 
 If a gem is not installed locally, gem-skill will install it automatically

data/docs/configuration.md

@@ -74,6 +74,30 @@ A blank or unset value falls back to the `.claude/skills` default.
     available-skills list or referenced explicitly. See
     [Using with other assistants](skill-files.md#using-with-other-assistants).
 
+### `GEMSKIL_MAX_TOKENS`
+
+Controls the maximum number of output tokens the LLM may generate for each skill file.
+Increase this if generated `SKILL.md` files are being truncated.
+
+| | |
+|---|---|
+| **Default** | `32767` |
+| **Example** | `export GEMSKIL_MAX_TOKENS=65536` |
+
+### `GEMSKILL_TEMPERATURE`
+
+Sampling temperature for generation. Lower values produce more consistent,
+deterministic output — appropriate for factual reference documentation.
+
+| | |
+|---|---|
+| **Default** | `0.2` |
+| **Example** | `export GEMSKILL_TEMPERATURE=0.0` |
+
+Only applied to models that support a temperature parameter. Reasoning models
+(e.g. `gpt-5.5`) reject it, so the value is silently skipped for them — switch to
+a temperature-supporting model (Claude, Gemini, older GPT) to benefit.
+
 ### `GEMSKILL_MODEL`
 
 Controls which LLM model is used when generating skills.

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

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+# gem/skill first — see gem_command.rb: activation must resolve json < 3
+# before a bare `require "json"` can activate a newer version.
+require "gem/skill"
 require "async"
 require "fileutils"
 require "json"
 require "tty-spinner"
-require "gem/skill"
 
 module Gem::Skill
   # Handles `bundle skill SUBCOMMAND` via Bundler's plugin API (plugins.rb).
@@ -43,11 +45,12 @@ module Gem::Skill
         return
       end
 
-      force   = opts[:force]
-      verify  = opts[:verify]
-      model   = opts[:model] || Generator::DEFAULT_MODEL
-      errors  = []
-      results = []
+      force      = opts[:force]
+      verify     = opts[:verify]
+      model      = opts[:model] || Generator::DEFAULT_MODEL
+      max_tokens = opts[:max_tokens] || Generator::MAX_TOKENS
+      errors     = []
+      results    = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Installing skills (#{model})",
@@ -61,7 +64,7 @@ module Gem::Skill
           sp = multi.register("  [:spinner] :title")
           sp.update(title: "#{gem_name} #{version}")
           barrier.async do
-            result = install_one(gem_name, version, sp, force: force, model: model, verify: verify)
+            result = install_one(gem_name, version, sp, force: force, model: model, verify: verify, max_tokens: max_tokens)
             results << result
             errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
@@ -79,11 +82,12 @@ module Gem::Skill
     def self.refresh(opts = {})
       gems   = Lockfile.gems
       linked  = Linker.linked_gems.to_h { |e| [e[:gem_name], e[:version]] }
-      force   = opts[:force]
-      verify  = opts[:verify]
-      model   = opts[:model] || Generator::DEFAULT_MODEL
-      errors  = []
-      results = []
+      force      = opts[:force]
+      verify     = opts[:verify]
+      model      = opts[:model] || Generator::DEFAULT_MODEL
+      max_tokens = opts[:max_tokens] || Generator::MAX_TOKENS
+      errors     = []
+      results    = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Refreshing skills (#{model})",
@@ -102,7 +106,7 @@ module Gem::Skill
               sp.success("up to date")
               Runner::Result.success
             else
-              install_one(gem_name, version, sp, force: force, model: model, verify: verify)
+              install_one(gem_name, version, sp, force: force, model: model, verify: verify, max_tokens: max_tokens)
             end
             results << result
             errors << "#{gem_name} #{version}: #{result.error}" if result.error
@@ -139,9 +143,9 @@ module Gem::Skill
 
     # --- private ---
 
-    def self.install_one(gem_name, version, spinner, force:, model:, verify: false)
+    def self.install_one(gem_name, version, spinner, force:, model:, verify: false, max_tokens: Generator::MAX_TOKENS)
       spinner.auto_spin
-      Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify)
+      Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify, max_tokens: max_tokens)
     end
     private_class_method :install_one
 
@@ -178,6 +182,8 @@ module Gem::Skill
         when "--version", "-v"   then opts[:version] = true
         when /\A--model(?:=(.+))?\z/
           opts[:model] = $1 || args[args.index(arg) + 1]
+        when /\A--max-tokens(?:=(.+))?\z/
+          opts[:max_tokens] = ($1 || args[args.index(arg) + 1]).to_i
         else
           remaining << arg unless opts[:model].nil? && arg !~ /\A--/
           remaining << arg if arg !~ /\A--/
@@ -198,10 +204,11 @@ module Gem::Skill
           list      Show skills linked in this project
 
         Options:
-          --force         Regenerate even if already cached
-          --verify        Verify generated skills against gem source and fix mismatches
-          --model MODEL   LLM model to use (default: #{Generator::DEFAULT_MODEL})
-          --version, -v   Print gem-skill version and exit
+          --force                Regenerate even if already cached
+          --verify               Verify generated skills against gem source and fix mismatches
+          --model MODEL          LLM model to use (default: #{Generator::DEFAULT_MODEL})
+          --max-tokens TOKENS    Max output tokens (overrides GEMSKIL_MAX_TOKENS; default: #{Generator::MAX_TOKENS})
+          --version, -v          Print gem-skill version and exit
 
         Env:
           GEMSKILL_PROJECT_DIR   Project dir for symlinks (default: .claude/skills)

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.
@@ -19,6 +23,12 @@ class Gem::Commands::SkillCommand < Gem::Command
     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
 
@@ -80,9 +90,11 @@ class Gem::Commands::SkillCommand < Gem::Command
       return
     end
 
-    force  = options[:force]
-    verify = options[:verify]
-    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})",
@@ -96,7 +108,7 @@ class Gem::Commands::SkillCommand < Gem::Command
       gem_names.each do |gem_name|
         spinner = multi.register("  [:spinner] :title")
         spinner.update(title: gem_name)
-        barrier.async { results << install_one(gem_name, spinner: spinner, force: force, model: model, verify: verify) }
+        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
@@ -112,7 +124,7 @@ class Gem::Commands::SkillCommand < Gem::Command
     end
   end
 
-  def install_one(gem_name, spinner:, force:, model:, verify: false)
+  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?
@@ -120,7 +132,7 @@ class Gem::Commands::SkillCommand < Gem::Command
       version = install_gem(gem_name)
     end
     spinner.update(title: "#{gem_name} #{version}")
-    result = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify)
+    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

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.
@@ -101,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/runner.rb

@@ -17,14 +17,20 @@ module Gem::Skill
 
     # 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)
+    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)
         content = Cache.read(gem_name, version)
         return finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "already cached")
       end
 
-      content = 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)
       finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "done")
     rescue => e

data/lib/gem/skill/verifier.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
+require "ruby_llm/providers/lms"
+require "ruby_llm/providers/apfel"
 
 module Gem::Skill
   # Second-pass quality gate for a generated SKILL.md.
@@ -100,7 +102,8 @@ module Gem::Skill
     private
 
     def build_chat
-      RubyLLM.chat(model: model).with_instructions(SYSTEM_INSTRUCTIONS)
+      model_id, provider = Gem::Skill.parse_model(model)
+      RubyLLM.chat(model: model_id, provider: provider).with_instructions(SYSTEM_INSTRUCTIONS)
     end
 
     def format_prompt(skill_content, source)

data/lib/gem/skill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gem::Skill
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/gem/skill.rb

@@ -30,14 +30,37 @@ module Gem::Skill
     mistral_api_key:    "MISTRAL_API_KEY",
     deepseek_api_key:   "DEEPSEEK_API_KEY",
     openrouter_api_key: "OPENROUTER_API_KEY",
-    xai_api_key:        "XAI_API_KEY"
+    xai_api_key:        "XAI_API_KEY",
+    lms_api_base:       "LMS_API_BASE",
+    lms_api_key:        "LMS_API_KEY",
+    apfel_api_base:     "APFEL_API_BASE",
+    apfel_api_key:      "APFEL_API_KEY"
   }.freeze
 
+  # Split a "provider/model" string into [model_id, provider_symbol] when the
+  # prefix names a registered RubyLLM provider, e.g.
+  #   "lms/qwen/qwen3.8-27b" -> ["qwen/qwen3.8-27b", :lms]
+  # Otherwise the string is a bare model id: ["gpt-5.5", nil]. A bare id is
+  # resolved by RubyLLM's own provider preference, so ids that contain a "/"
+  # but don't start with a provider slug (e.g. "qwen/...") pass through intact.
+  def self.parse_model(model_string)
+    prefix, rest = model_string.to_s.split("/", 2)
+    return [model_string, nil] unless rest && RubyLLM::Provider.providers.key?(prefix.to_sym)
+
+    [rest, prefix.to_sym]
+  end
+
+  # HTTP read timeout in seconds (GEMSKILL_REQUEST_TIMEOUT to override).
+  # RubyLLM's default of 300 is tuned for hosted APIs; a local model (lms/apfel)
+  # can legitimately take longer than that to finish one skill generation.
+  REQUEST_TIMEOUT = ENV.fetch("GEMSKILL_REQUEST_TIMEOUT", 900).to_i
+
   # Configure RubyLLM from environment variables. Called automatically by the
   # CLI commands so users don't need a separate initializer for standalone use.
   # No-op if RubyLLM is already configured (e.g. in a Rails app).
   def self.configure_llm!
     RubyLLM.configure do |config|
+      config.request_timeout = REQUEST_TIMEOUT
       ENV_KEY_MAP.each do |attr, env_var|
         value = ENV[env_var]
         config.public_send(:"#{attr}=", value) if value

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-skill
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -29,14 +29,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-providers-apfel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-providers-lms
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tty-spinner
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +93,7 @@ files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -120,14 +149,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Generate and manage Claude Code AI skills from Ruby gem documentation.
 test_files: []