gem-skill 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d438a4ff4e7229ac130284f672c464bbaf770f04ba640177f0effce8822f9ec
+  data.tar.gz: 7f86cbc1951664f5ba80602238db6d671450adb3bf7776ec2be0323df342de05
+SHA512:
+  metadata.gz: c120f84db49f729f342a6640375cbd12b9fceb525645406b64488d209973ca77e09d111ed6c92ae9ec9c4107ea060cf32ce4b1726ccb9064fd78b5223b88995d
+  data.tar.gz: a6747e0d10b773bfdd3ee7b9c562da01e061cd2fb40341c8c99e41c56be931dff27642d738f4f8e49afff85efa3fec1242ed2f6de036ab9a2880677be598b3de

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-16
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,186 @@
+# gem-skill
+
+Generates 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.
+
+## 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.
+
+## How the cache is laid out
+
+```
+~/.gem/skills/
+└── chunker-ruby/
+    ├── 1.2.3/
+    │   ├── SKILL.md        ← generated skill
+    │   └── metadata.json   ← gem name, version, model used, generated_at
+    └── 1.4.0/
+        ├── SKILL.md
+        └── metadata.json
+```
+
+Each project's `.claude/skills/` holds symlinks that point into this cache:
+
+```
+your-app/.claude/skills/
+└── chunker-ruby.md  →  ~/.gem/skills/chunker-ruby/1.2.3/SKILL.md
+```
+
+Two projects that pin different versions of the same gem each get the right
+skill; the underlying content is generated once and shared.
+
+## Installation
+
+```bash
+gem install gem-skill
+```
+
+This gives you the `gem skill` subcommand.
+
+For `bundle skill` support (project-aware, reads `Gemfile.lock`), also run:
+
+```bash
+bundle plugin install gem-skill
+```
+
+or add it to your `Gemfile`:
+
+```ruby
+plugin "gem-skill"
+```
+
+## Requirements
+
+`gem-skill` uses [RubyLLM](https://github.com/crmne/ruby_llm) to generate
+skills. Configure at least one provider API key before running:
+
+```bash
+export OPENAI_API_KEY="..."      # default model: gpt-5.5
+export ANTHROPIC_API_KEY="..."   # or use Claude
+export GEMINI_API_KEY="..."      # or Gemini
+```
+
+## Configuration
+
+Two environment variables control `gem-skill`'s behaviour:
+
+| Variable | Default | Description |
+|---|---|---|
+| `GEMSKILL_DIR` | `~/.gem/skills` | Root directory for the skill cache |
+| `GEMSKILL_MODEL` | `gpt-5.5` | LLM model used when generating skills |
+
+```bash
+# Store skills on a shared drive accessible to all projects
+export GEMSKILL_DIR="/Volumes/shared/gem-skills"
+
+# Switch the default model to Claude
+export GEMSKILL_MODEL="claude-sonnet-4-6"
+```
+
+The `--model` flag on any command overrides `GEMSKILL_MODEL` for that
+invocation. `GEMSKILL_DIR` applies everywhere the cache is read or written.
+
+## Usage
+
+### `gem skill` — global cache management
+
+```bash
+# Generate a skill for an installed gem (version auto-detected)
+gem skill install chunker-ruby
+
+# Install skills for multiple gems at once (runs concurrently)
+gem skill install chunker-ruby faraday debug_me
+
+# Force regeneration even if already cached
+gem skill install chunker-ruby --force
+
+# Use a different model
+gem skill install chunker-ruby --model claude-haiku-4-5
+
+# Show everything in the cache
+gem skill list
+
+# Remove a specific cached version
+gem skill purge chunker-ruby 1.2.3
+
+# Remove all cached versions of a gem
+gem skill purge chunker-ruby --all
+```
+
+If a gem isn't installed locally, `gem skill install` will install it first.
+
+### `gem install --with-skill`
+
+Generate skills for gems as you install them:
+
+```bash
+gem install faraday debug_me --with-skill
+```
+
+Skills are generated concurrently after all gems finish installing.
+
+### `bundle skill` — project-aware, driven by Gemfile.lock
+
+Run from your project root after `bundle install`:
+
+```bash
+# Generate and link skills for all direct dependencies
+bundle skill install
+
+# Re-sync after bundle update (skips gems already at the correct version)
+bundle skill refresh
+
+# Show what's linked in this project
+bundle skill list
+
+# Options available on install and refresh
+bundle skill install --force
+bundle skill install --model claude-haiku-4-5
+```
+
+The `install` and `refresh` commands stream LLM output as it is generated, so
+you see progress rather than a silent wait.
+
+## What gets generated
+
+Each `SKILL.md` covers:
+
+- **Overview** — what the gem does and when to use it
+- **Installation** — exact Gemfile lines and post-install steps
+- **Core API** — key classes and methods with real code examples
+- **Common Patterns** — the 3–5 most frequent real-world usage patterns
+- **Gotchas & Edge Cases** — surprising defaults, version-specific behavior,
+  thread safety, encoding issues
+- **Configuration** — initializer patterns and environment variables
+- **Testing** — how to test code that uses the gem
+
+The content is synthesized from three sources, tried in priority order:
+
+1. Local gem install (`Gem::Specification` → `gem_dir`) — README and CHANGELOG
+2. RubyGems API — summary, runtime dependencies, source URI
+3. GitHub raw README — fetched when the gem isn't installed locally
+
+## Development
+
+```bash
+git clone https://github.com/madbomber/gem-skill
+cd gem-skill
+bundle install
+bundle exec rake test
+```
+
+## Contributing
+
+Bug reports and pull requests welcome at https://github.com/madbomber/gem-skill.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/gem/skill/cache.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Gem::Skill
+  # Manages the global ~/.gem/skills cache.
+  # Structure: ~/.gem/skills/<gem_name>/<version>/SKILL.md
+  module Cache
+    ROOT = File.expand_path(ENV.fetch("GEMSKILL_DIR", "~/.gem/skills")).freeze
+
+    def self.root = ROOT
+
+    def self.skill_path(gem_name, version)
+      File.join(ROOT, gem_name, version, "SKILL.md")
+    end
+
+    def self.metadata_path(gem_name, version)
+      File.join(ROOT, gem_name, version, "metadata.json")
+    end
+
+    def self.cached?(gem_name, version)
+      File.exist?(skill_path(gem_name, version))
+    end
+
+    def self.store(gem_name, version, skill_content, metadata = {})
+      dir = File.join(ROOT, gem_name, version)
+      FileUtils.mkdir_p(dir)
+      File.write(skill_path(gem_name, version), skill_content)
+      File.write(metadata_path(gem_name, version), JSON.generate(metadata.merge(
+        gem_name: gem_name,
+        version: version,
+        generated_at: Time.now.iso8601
+      )))
+    end
+
+    def self.read(gem_name, version)
+      path = skill_path(gem_name, version)
+      raise Error, "No cached skill for #{gem_name} #{version}" unless File.exist?(path)
+
+      File.read(path)
+    end
+
+    def self.versions(gem_name)
+      dir = File.join(ROOT, gem_name)
+      return [] unless Dir.exist?(dir)
+
+      Dir.children(dir).sort
+    end
+
+    def self.all_gems
+      return [] unless Dir.exist?(ROOT)
+
+      Dir.children(ROOT).sort
+    end
+
+    def self.purge(gem_name, version)
+      dir = File.join(ROOT, gem_name, version)
+      FileUtils.rm_rf(dir)
+      parent = File.join(ROOT, gem_name)
+      Dir.rmdir(parent) if Dir.exist?(parent) && Dir.empty?(parent)
+    end
+  end
+end

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "gem/skill"
+
+module Gem::Skill
+  # Handles `bundle skill SUBCOMMAND` via Bundler's plugin API (plugins.rb).
+  # Project-aware: reads Gemfile.lock and manages .claude/skills/ symlinks.
+  module BundlerCommand
+    SUBCOMMANDS = %w[install refresh list].freeze
+
+    def self.run(args)
+      Gem::Skill.configure_llm!
+      opts, rest = parse_options(args)
+      subcmd = rest.shift
+
+      case subcmd
+      when "install" then install(opts)
+      when "refresh" then refresh(opts)
+      when "list"    then list
+      when nil, "help", "--help"
+        puts usage
+      else
+        warn "gem-skill: unknown subcommand #{subcmd.inspect}"
+        warn usage
+        exit 1
+      end
+    end
+
+    def self.install(opts = {})
+      gems = Lockfile.gems
+      if gems.empty?
+        puts "No gems found in Gemfile.lock."
+        return
+      end
+
+      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
+          end
+        end
+
+        Linker.link(gem_name, version)
+        puts "  ✓"
+      rescue Gem::Skill::Error => e
+        puts "  ✗ #{e.message}"
+        errors << "#{gem_name} #{version}: #{e.message}"
+      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
+    end
+
+    def self.refresh(opts = {})
+      gems   = Lockfile.gems
+      linked = Linker.linked_gems.to_h { |e| [e[:gem_name], e[:version]] }
+      force  = opts[:force]
+      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
+        end
+
+        Linker.link(gem_name, version)
+        puts "  ✓"
+      rescue Gem::Skill::Error => e
+        puts "  ✗ #{e.message}"
+        errors << "#{gem_name} #{version}: #{e.message}"
+      end
+
+      Linker.prune_dead_links
+
+      puts ""
+      puts "Refreshed."
+      if errors.any?
+        puts ""
+        puts "Errors:"
+        errors.each { |e| puts "  #{e}" }
+      end
+    end
+
+    def self.list
+      entries = Linker.linked_gems
+      if entries.empty?
+        puts "No skills linked in this project."
+        puts "Run: bundle skill install"
+        return
+      end
+
+      ok      = entries.count { |e| e[:valid] }
+      broken  = entries.size - ok
+
+      puts "Skills linked in .claude/skills/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
+      puts ""
+      entries.each do |e|
+        status = e[:valid] ? "ok    " : "BROKEN"
+        puts "  [#{status}]  %-30s %s" % [e[:gem_name], e[:version]]
+      end
+    end
+
+    # --- private ---
+
+    def self.parse_options(args)
+      opts      = {}
+      remaining = []
+
+      args.each do |arg|
+        case arg
+        when "--force"           then opts[:force] = true
+        when /\A--model(?:=(.+))?\z/
+          opts[:model] = $1 || args[args.index(arg) + 1]
+        else
+          remaining << arg unless opts[:model].nil? && arg !~ /\A--/
+          remaining << arg if arg !~ /\A--/
+        end
+      end
+
+      [opts, remaining]
+    end
+    private_class_method :parse_options
+
+    def self.usage
+      <<~USAGE
+        Usage: bundle skill SUBCOMMAND [OPTIONS]
+
+        Subcommands:
+          install   Generate and link skills for all gems in Gemfile.lock
+          refresh   Re-sync .claude/skills/ after bundle update
+          list      Show skills linked in this project
+
+        Options:
+          --force         Regenerate even if already cached
+          --model MODEL   LLM model to use (default: #{Generator::DEFAULT_MODEL})
+      USAGE
+    end
+    private_class_method :usage
+  end
+end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "rubygems/command"
+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.
+class Gem::Commands::SkillCommand < Gem::Command
+  def initialize
+    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("-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
+  end
+
+  def arguments
+    "SUBCOMMAND  one of: install, list, purge"
+  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"
+  end
+
+  def description
+    <<~DESC
+      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.
+
+      Use 'bundle skill install' (after: bundle plugin install gem-skill)
+      to generate and link skills for an entire project from Gemfile.lock.
+    DESC
+  end
+
+  def execute
+    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 nil
+      say usage
+    else
+      alert_error "Unknown subcommand: #{subcmd.inspect}"
+      say usage
+    end
+  end
+
+  private
+
+  def cmd_install
+    gem_names = options[:args].dup
+    options[:args].clear
+
+    if gem_names.empty?
+      alert_error "gem_name required. Usage: gem skill install GEM_NAME [GEM_NAME ...]"
+      return
+    end
+
+    force = options[:force]
+    model = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+
+    multi = TTY::Spinner::Multi.new(
+      "[:spinner] Generating skills (#{model})",
+      format: :dots,
+      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) }
+    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")
+    alert_error "#{gem_name}: #{e.message}"
+  end
+
+  def cmd_list
+    gems = Gem::Skill::Cache.all_gems
+    if gems.empty?
+      say "No skills cached yet."
+      say "Run: gem skill install GEM_NAME"
+      return
+    end
+
+    say "Cached skills in #{Gem::Skill::Cache.root}:"
+    say ""
+    gems.each do |name|
+      versions = Gem::Skill::Cache.versions(name)
+      say "  %-30s %s" % [name, versions.join(", ")]
+    end
+    say ""
+    say "#{gems.size} gem(s), #{gems.sum { |n| Gem::Skill::Cache.versions(n).size }} version(s) total."
+  end
+
+  def cmd_purge
+    gem_name = options[:args].shift
+    unless gem_name
+      alert_error "Usage: gem skill purge GEM_NAME VERSION\n       gem skill purge GEM_NAME --all"
+      return
+    end
+
+    if options[:all]
+      versions = Gem::Skill::Cache.versions(gem_name)
+      if versions.empty?
+        alert_error "No cached versions for '#{gem_name}'"
+        return
+      end
+      versions.each { |v| Gem::Skill::Cache.purge(gem_name, v) }
+      say "Purged #{versions.size} version(s) of #{gem_name}"
+      return
+    end
+
+    version = options[:args].shift
+    unless version
+      alert_error "Usage: gem skill purge GEM_NAME VERSION\n       gem skill purge GEM_NAME --all"
+      return
+    end
+
+    unless Gem::Skill::Cache.cached?(gem_name, version)
+      alert_error "Not cached: #{gem_name} #{version}"
+      return
+    end
+
+    Gem::Skill::Cache.purge(gem_name, version)
+    say "Purged: #{gem_name} #{version}"
+  end
+
+  def resolve_installed_version(gem_name)
+    Gem::Specification.find_by_name(gem_name)&.version&.to_s
+  rescue Gem::MissingSpecError
+    nil
+  end
+
+  def install_gem(gem_name, version = nil)
+    req   = version ? Gem::Requirement.new("= #{version}") : Gem::Requirement.default
+    specs = Gem.install(gem_name, req)
+    specs.find { |s| s.name == gem_name }&.version&.to_s
+  rescue Gem::InstallError, Gem::GemNotFoundException, StandardError => e
+    raise Gem::Skill::Error, "Could not install '#{gem_name}': #{e.message}"
+  end
+end