gem-skill 0.1.1 → 0.1.3

data/docs/how-it-works.md

@@ -0,0 +1,160 @@
+# How It Works
+
+gem-skill is built as a pipeline of independent modules. Each has a single
+responsibility and can be used or tested in isolation.
+
+## Pipeline overview
+
+```
+Gemfile.lock / gem name
+      ↓
+  Lockfile          parse direct deps + gemspec deps
+      ↓
+  Fetcher           collect documentation from multiple sources
+      ↓
+  Generator         call LLM, produce SKILL.md content
+      ↓
+  Cache             write to ~/.gem/skills/<gem>/<version>/
+      ↓
+  Linker            symlink .claude/skills/<gem> → cache dir
+```
+
+`Runner.install_skill` is the glue that drives steps 2–5 for a single gem.
+The CLI commands (`gem skill`, `bundle skill`) fan it out concurrently across
+multiple gems using async fibers.
+
+---
+
+## Modules
+
+### Lockfile
+
+`lib/gem/skill/lockfile.rb`
+
+Parses `Gemfile.lock` to produce a `{ gem_name => version }` hash of the gems
+to process. Reads from two sections:
+
+- **`DEPENDENCIES`** — direct deps listed in `Gemfile`
+- **`PATH` → `specs:`** — runtime deps from any `gemspec` referenced by `gemspec` in `Gemfile`
+
+Versions are resolved from the `GEM → specs:` section, which contains the full
+lockfile-resolved version for every gem.
+
+### Fetcher
+
+`lib/gem/skill/fetcher.rb`
+
+Collects documentation from up to three sources, tried in priority order:
+
+1. **Local gem install** — reads `README` and `CHANGELOG` from the gem's install directory via `Gem::Specification`
+2. **RubyGems API** — fetches summary, runtime dependencies, source URI
+3. **GitHub raw README** — fetched when the gem is not installed locally; tries `main` then `master` branches, and four common README filename variants
+
+Content is truncated at 60,000 characters per source to avoid blowing the LLM
+context window.
+
+### Generator
+
+`lib/gem/skill/generator.rb`
+
+Calls the LLM via `ruby_llm`. Constructs a detailed prompt instructing the
+model to produce a structured `SKILL.md` covering:
+
+- Overview, Installation, Core API, Common Patterns, Gotchas, Configuration, Testing
+
+Supports both streaming (live output) and non-streaming modes. Strips any
+markdown code fence wrapper the model adds despite being told not to.
+
+The model is configurable via `GEMSKILL_MODEL` or `--model`.
+
+### Cache
+
+`lib/gem/skill/cache.rb`
+
+Manages the global skill cache. Structure:
+
+```
+~/.gem/skills/               (GEMSKILL_DIR)
+└── <gem_name>/
+    └── <version>/
+        ├── SKILL.md
+        └── metadata.json   (gem, version, model, generated_at, sources)
+```
+
+`Cache::ROOT` is set once at load time from `GEMSKILL_DIR` (default: `~/.gem/skills`).
+
+### Linker
+
+`lib/gem/skill/linker.rb`
+
+Creates and manages directory symlinks in `.claude/skills/` inside a project:
+
+```
+.claude/skills/<gem_name>  →  ~/.gem/skills/<gem_name>/<version>/
+```
+
+Symlinks point to the **version directory**, not directly to `SKILL.md`.
+Claude Code discovers `SKILL.md` by reading inside the linked directory.
+
+`Linker.prune_dead_links` removes any symlink whose target no longer exists
+in the cache (e.g. after `gem skill purge`).
+
+### Runner
+
+`lib/gem/skill/runner.rb`
+
+Shared core used by both CLI commands. Drives one gem through the
+cache-check → generate → link sequence:
+
+```ruby
+Runner.install_skill(gem_name, version, spinner, force:, model:)
+# Returns nil on success, error message string on failure
+```
+
+Returns the error message rather than raising, so the caller (the concurrent
+fiber) can record it without killing other in-flight fibers.
+
+---
+
+## Concurrency
+
+Both CLI commands use the `async` gem with `Async::Barrier`:
+
+```ruby
+Async do
+  barrier = Async::Barrier.new
+  gems.each do |gem_name, version|
+    barrier.async { Runner.install_skill(...) }
+  end
+  barrier.wait
+ensure
+  barrier.stop
+end
+```
+
+Each gem gets its own fiber. Fibers yield to the event loop during network I/O
+(HTTP fetches, LLM API calls), so all gems make progress concurrently on a
+single thread. This is more memory-efficient than one thread per gem.
+
+---
+
+## Plugin architecture
+
+gem-skill registers itself in two ways:
+
+### RubyGems plugin (`lib/rubygems_plugin.rb`)
+
+Auto-loaded by RubyGems on every `gem` command via the `rubygems_plugin`
+naming convention. Prepends `Gem::Skill::InstallSkillOption` onto
+`Gem::Commands::InstallCommand` to add the `--with-skill` flag.
+
+After all gem installs complete, `Gem.post_install` collects gem names/versions
+into a pending list, and `at_exit` fires `generate_pending_skills` to process
+them concurrently.
+
+### Bundler plugin (`plugins.rb`)
+
+Registered via `bundle plugin install gem-skill` (or `gem skill setup`).
+Bundler's plugin API loads `plugins.rb` and discovers the
+`Gem::Skill::BundlerPlugin` class, which routes `bundle skill SUBCOMMAND` to
+`Gem::Skill::BundlerCommand`.

data/docs/index.md

@@ -0,0 +1,69 @@
+<p align="center">
+<table style="width:38%;margin:0 auto;" border="0" cellpadding="8">
+  <tr>
+    <td width="40%"><img src="assets/images/gem-skill.jpg" alt="gem-skill logo" style="width:100%;display:block;"></td>
+    <td width="60%">
+      Generate Claude Code skill files from Ruby gem
+      documentation and caches them globally so every project that uses a gem
+      can share the same pre-built knowledge.<br><br>
+      <strong><a href="https://madbomber.github.io/gem-skill">Full documentation →</a></strong>
+    </td>
+  </tr>
+</table>
+</p>
+
+## The problem it solves
+
+Every time Claude Code encounters a gem it hasn't seen in the current context,
+it re-reads the README, scans examples, and figures out the API. That costs
+tokens and time — and the result evaporates when the conversation ends.
+
+`gem-skill` runs that pipeline once, offline, and stores the output as a
+`SKILL.md` in `~/.gem/skills`. Projects symlink to the cached version, so
+Claude has accurate, version-specific knowledge about each gem without
+repeating the ingestion work.
+
+## Quick start
+
+```bash
+# 1. Install
+gem install gem-skill
+
+# 2. Register the Bundler plugin (once per machine)
+gem skill setup
+
+# 3. Generate a skill for any installed gem
+gem skill install debug_me
+
+# 4. In a project — generate skills for all direct dependencies
+cd your-project
+bundle skill install
+```
+
+## How it works
+
+```
+gem README / changelog / RubyGems API
+        ↓
+   Fetcher collects docs
+        ↓
+   Generator calls LLM (ruby_llm)
+        ↓
+   SKILL.md cached at ~/.gem/skills/<gem>/<version>/
+        ↓
+   Linker creates .claude/skills/<gem> → cache dir
+        ↓
+   Claude Code reads SKILL.md automatically
+```
+
+All concurrent work is handled by async fibers — multiple gems are processed
+simultaneously with live TTY spinner progress.
+
+## Key features
+
+- **Global cache** — generate once, use everywhere; skills are version-specific
+- **Gemfile.lock awareness** — `bundle skill install` installs skills for every direct dependency including gemspec runtime deps
+- **Concurrent** — all LLM calls run concurrently via async fibers
+- **Two interfaces** — `gem skill` for global cache management, `bundle skill` for project-aware linking
+- **Auto-install** — `gem install --with-skill` generates skills during normal gem installation
+- **Configurable** — `GEMSKILL_DIR` and `GEMSKILL_MODEL` environment variables

data/docs/installation.md

@@ -0,0 +1,62 @@
+# Installation
+
+## Requirements
+
+- Ruby >= 3.2.0
+- At least one LLM provider API key (see [Configuration](configuration.md))
+
+## Install the gem
+
+```bash
+gem install gem-skill
+```
+
+This makes the `gem skill` subcommand available immediately.
+
+## Register the Bundler plugin
+
+To enable `bundle skill` in your projects, run once after installation:
+
+```bash
+gem skill setup
+```
+
+This registers gem-skill as a Bundler plugin globally. You only need to do this
+once per machine.
+
+!!! tip "Alternative: per-project plugin"
+    You can also add the plugin to a specific project's `Gemfile`:
+    ```ruby
+    plugin "gem-skill"
+    ```
+    This installs the plugin for that project only.
+
+## Verify installation
+
+```bash
+# Check gem skill is available
+gem skill
+
+# Check bundle skill is available (after gem skill setup)
+bundle skill
+```
+
+## Upgrading
+
+```bash
+gem update gem-skill
+gem skill setup    # re-register the Bundler plugin with the new version
+```
+
+## Development installation
+
+To run from source without building and releasing a gem:
+
+```bash
+git clone https://github.com/madbomber/gem-skill
+cd gem-skill
+bundle install
+bin/dev_install    # points both Bundler plugin indexes at the source tree
+```
+
+`bin/dev_install --reset` restores the indexes to the last released gem.

data/docs/skill-files.md

@@ -0,0 +1,78 @@
+# Skill Files
+
+A `SKILL.md` is a structured Markdown document that gives Claude Code deep,
+practical knowledge about a Ruby gem. Claude reads it automatically when it is
+present in `.claude/skills/`.
+
+## Format
+
+Every generated skill starts with a top-level heading identifying the gem and
+version, then covers seven sections:
+
+```markdown
+# faraday v2.14.3
+
+## Overview
+What the gem does and when to reach for it.
+
+## Installation
+Exact Gemfile/gemspec lines and any required post-install steps.
+
+## Core API
+Key classes, methods, and options with real method signatures and return values.
+
+## Common Patterns
+The 3–5 most frequent real-world usage patterns with working code examples.
+
+## Gotchas & Edge Cases
+Surprising defaults, version-specific behavior, thread safety, encoding issues.
+
+## Configuration
+Initializer patterns, environment variables, defaults worth knowing.
+
+## Testing
+How to test code that uses this gem: mocks, fakes, fixtures, VCR patterns.
+```
+
+## What Claude does with it
+
+When Claude Code opens a project containing `.claude/skills/`, it reads every
+`SKILL.md` it finds. This means:
+
+- Claude knows the correct API for the exact version you're using
+- No token cost re-deriving usage from READMEs mid-conversation
+- The knowledge persists across conversation turns
+- Multiple gems can be in scope simultaneously
+
+## Sources used to generate
+
+The LLM is given up to three sources per gem (in priority order):
+
+1. **Local README + CHANGELOG** — from the gem's install directory
+2. **RubyGems API** — summary, dependencies, source URI
+3. **GitHub raw README** — fetched when not installed locally
+
+Content is synthesized, not copied verbatim. The model is instructed to write
+as a knowledgeable colleague, not a marketing document.
+
+## Quality and regeneration
+
+Skill quality depends on the documentation available for the gem and the model
+used. For gems with poor upstream documentation, results will reflect that.
+
+To improve a skill:
+
+```bash
+# Use a more capable model
+gem skill install my_gem --force --model claude-opus-4-8
+
+# Or set it as the default
+export GEMSKILL_MODEL="claude-opus-4-8"
+gem skill install my_gem --force
+```
+
+## Version specificity
+
+Skills are cached per version. `faraday 2.12.0` and `faraday 2.14.3` each get
+their own `SKILL.md`. Symlinks in `.claude/skills/` point to the version
+matching your `Gemfile.lock`, so Claude always has the right version context.

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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "async"
 require "fileutils"
 require "json"
+require "tty-spinner"
 require "gem/skill"
 
 module Gem::Skill
@@ -15,6 +17,11 @@ module Gem::Skill
       opts, rest = parse_options(args)
       subcmd = rest.shift
 
+      if opts[:version]
+        puts Gem::Skill::VERSION
+        return
+      end
+
       case subcmd
       when "install" then install(opts)
       when "refresh" then refresh(opts)
@@ -35,42 +42,33 @@ module Gem::Skill
         return
       end
 
-      force = opts[:force]
-      model = opts[:model] || Generator::DEFAULT_MODEL
+      force  = opts[:force]
+      model  = opts[:model] || Generator::DEFAULT_MODEL
       errors = []
 
-      puts "Installing skills for #{gems.size} gem(s) (model: #{model})..."
-      puts ""
-
-      gems.each do |gem_name, version|
-        if Cache.cached?(gem_name, version) && !force
-          print "  skip  #{gem_name} #{version}"
-        else
-          print "  gen   #{gem_name} #{version}  "
-          $stdout.flush
-          Generator.new(gem_name, version, model: model).generate(force: force) do |chunk|
-            print chunk
-            $stdout.flush
+      multi = TTY::Spinner::Multi.new(
+        "[:spinner] Installing skills (#{model})",
+        format: :dots,
+        output: $stderr
+      )
+
+      Async do
+        barrier = Async::Barrier.new
+        gems.each do |gem_name, version|
+          sp = multi.register("  [:spinner] :title")
+          sp.update(title: "#{gem_name} #{version}")
+          barrier.async do
+            err = install_one(gem_name, version, sp, force: force, model: model)
+            errors << "#{gem_name} #{version}: #{err}" if err
           end
         end
-
-        Linker.link(gem_name, version)
-        puts "  ✓"
-      rescue Gem::Skill::Error => e
-        puts "  ✗ #{e.message}"
-        errors << "#{gem_name} #{version}: #{e.message}"
+        barrier.wait
+      ensure
+        barrier.stop
       end
 
       Linker.prune_dead_links
-
-      puts ""
-      puts "Done. #{gems.size - errors.size}/#{gems.size} skill(s) linked into .claude/skills/"
-
-      if errors.any?
-        puts ""
-        puts "Errors:"
-        errors.each { |e| puts "  #{e}" }
-      end
+      report_errors(errors)
     end
 
     def self.refresh(opts = {})
@@ -80,40 +78,35 @@ module Gem::Skill
       model  = opts[:model] || Generator::DEFAULT_MODEL
       errors = []
 
-      puts "Refreshing skills (model: #{model})..."
-      puts ""
-
-      gems.each do |gem_name, version|
-        if !force && linked[gem_name] == version
-          puts "  ok    #{gem_name} #{version}"
-          next
-        end
-
-        action = linked.key?(gem_name) ? "update" : "new"
-        print "  #{action.ljust(6)}#{gem_name} #{version}  "
-        $stdout.flush
-
-        Generator.new(gem_name, version, model: model).generate(force: force) do |chunk|
-          print chunk
-          $stdout.flush
+      multi = TTY::Spinner::Multi.new(
+        "[:spinner] Refreshing skills (#{model})",
+        format: :dots,
+        output: $stderr
+      )
+
+      Async do
+        barrier = Async::Barrier.new
+        gems.each do |gem_name, version|
+          sp = multi.register("  [:spinner] :title")
+          sp.update(title: "#{gem_name} #{version}")
+          barrier.async do
+            err = if !force && linked[gem_name] == version
+              sp.auto_spin
+              sp.success("up to date")
+              nil
+            else
+              install_one(gem_name, version, sp, force: force, model: model)
+            end
+            errors << "#{gem_name} #{version}: #{err}" if err
+          end
         end
-
-        Linker.link(gem_name, version)
-        puts "  ✓"
-      rescue Gem::Skill::Error => e
-        puts "  ✗ #{e.message}"
-        errors << "#{gem_name} #{version}: #{e.message}"
+        barrier.wait
+      ensure
+        barrier.stop
       end
 
       Linker.prune_dead_links
-
-      puts ""
-      puts "Refreshed."
-      if errors.any?
-        puts ""
-        puts "Errors:"
-        errors.each { |e| puts "  #{e}" }
-      end
+      report_errors(errors)
     end
 
     def self.list
@@ -124,8 +117,8 @@ module Gem::Skill
         return
       end
 
-      ok      = entries.count { |e| e[:valid] }
-      broken  = entries.size - ok
+      ok     = entries.count { |e| e[:valid] }
+      broken = entries.size - ok
 
       puts "Skills linked in .claude/skills/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
       puts ""
@@ -137,6 +130,20 @@ module Gem::Skill
 
     # --- private ---
 
+    def self.install_one(gem_name, version, spinner, force:, model:)
+      spinner.auto_spin
+      Runner.install_skill(gem_name, version, spinner, force: force, model: model)
+    end
+    private_class_method :install_one
+
+    def self.report_errors(errors)
+      return if errors.empty?
+      warn ""
+      warn "Errors (#{errors.size}):"
+      errors.each { |e| warn "  #{e}" }
+    end
+    private_class_method :report_errors
+
     def self.parse_options(args)
       opts      = {}
       remaining = []
@@ -144,6 +151,7 @@ module Gem::Skill
       args.each do |arg|
         case arg
         when "--force"           then opts[:force] = true
+        when "--version", "-v"   then opts[:version] = true
         when /\A--model(?:=(.+))?\z/
           opts[:model] = $1 || args[args.index(arg) + 1]
         else
@@ -168,6 +176,7 @@ module Gem::Skill
         Options:
           --force         Regenerate even if already cached
           --model MODEL   LLM model to use (default: #{Generator::DEFAULT_MODEL})
+          --version, -v   Print gem-skill version and exit
       USAGE
     end
     private_class_method :usage

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rubygems/command"
+require "async"
 require "fileutils"
 require "json"
 require "tty-spinner"
@@ -17,17 +18,19 @@ 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("-v", "--version",       "Print gem-skill version and exit") { |_, o| o[:version] = true }
   end
 
   def arguments
-    "SUBCOMMAND  one of: install, list, purge"
+    "SUBCOMMAND  one of: install, list, purge, setup"
   end
 
   def usage
     "#{program_name} install GEM_NAME [GEM_NAME ...]\n" \
     "       #{program_name} list\n" \
     "       #{program_name} purge GEM_NAME VERSION\n" \
-    "       #{program_name} purge GEM_NAME --all"
+    "       #{program_name} purge GEM_NAME --all\n" \
+    "       #{program_name} setup"
   end
 
   def description
@@ -35,19 +38,24 @@ class Gem::Commands::SkillCommand < Gem::Command
       install   Generate and cache a SKILL.md for a gem.
       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).
 
-      Use 'bundle skill install' (after: bundle plugin install gem-skill)
-      to generate and link skills for an entire project from Gemfile.lock.
+      Use 'bundle skill install' in any project after running 'gem skill setup'.
     DESC
   end
 
   def execute
+    if options[:version]
+      say Gem::Skill::VERSION
+      return
+    end
     Gem::Skill.configure_llm!
     subcmd = options[:args].shift
     case subcmd
     when "install" then cmd_install
     when "list"    then cmd_list
     when "purge"   then cmd_purge
+    when "setup"   then cmd_setup
     when nil
       say usage
     else
@@ -76,36 +84,33 @@ class Gem::Commands::SkillCommand < Gem::Command
       output: $stderr
     )
 
-    threads = gem_names.map do |gem_name|
-      spinner = multi.register("  [:spinner] :title")
-      spinner.update(title: gem_name)
-      Thread.new(gem_name, spinner) { |name, sp| install_one(name, spinner: sp, force: force, model: model) }
+    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) }
+      end
+      barrier.wait
+    ensure
+      barrier.stop
     end
-    threads.each(&:join)
 
     say "Tip: run 'bundle plugin install gem-skill' to enable 'bundle skill'."
   end
 
   def install_one(gem_name, spinner:, force:, model:)
     spinner.auto_spin
-
     version = resolve_installed_version(gem_name)
     if version.nil?
       spinner.update(title: "#{gem_name} (installing...)")
       version = install_gem(gem_name)
     end
-
-    if Gem::Skill::Cache.cached?(gem_name, version) && !force
-      spinner.update(title: "#{gem_name} #{version}")
-      spinner.success("already cached")
-      return
-    end
-
     spinner.update(title: "#{gem_name} #{version}")
-    Gem::Skill::Generator.new(gem_name, version, model: model).generate(force: force)
-    spinner.success("done")
-  rescue => e
-    spinner.error("#{gem_name} failed")
+    err = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model)
+    alert_error "#{gem_name}: #{err}" if err
+  rescue Gem::Skill::Error => e
+    spinner.error("failed")
     alert_error "#{gem_name}: #{e.message}"
   end
 
@@ -127,6 +132,15 @@ class Gem::Commands::SkillCommand < Gem::Command
     say "#{gems.size} gem(s), #{gems.sum { |n| Gem::Skill::Cache.versions(n).size }} version(s) total."
   end
 
+  def cmd_setup
+    say "Registering gem-skill as a Bundler plugin..."
+    if system("bundle", "plugin", "install", "gem-skill")
+      say "Done. Use 'bundle skill install' in any project."
+    else
+      alert_error "Failed. Try running manually: bundle plugin install gem-skill"
+    end
+  end
+
   def cmd_purge
     gem_name = options[:args].shift
     unless gem_name