gem-skill 0.1.0

data/lib/gem/skill/fetcher.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Gem::Skill
+  # Fetches documentation for a gem from multiple sources, in priority order:
+  #   1. Local gem installation (Gem::Specification) — metadata + README + CHANGELOG + examples
+  #   2. RubyGems API — metadata only, when gem isn't installed locally
+  #   3. GitHub raw README — when gem isn't installed locally
+  class Fetcher
+    RUBYGEMS_API  = "https://rubygems.org/api/v1/gems/%s.json"
+    GITHUB_RAW    = "https://raw.githubusercontent.com/%s/%s/%s"
+    MAX_REDIRECTS = 5
+    OPEN_TIMEOUT  = 5
+    READ_TIMEOUT  = 10
+
+    README_CANDIDATES    = %w[README.md README.rdoc README.txt README].freeze
+    CHANGELOG_CANDIDATES = %w[CHANGELOG.md CHANGELOG.rdoc HISTORY.md CHANGES.md].freeze
+
+    attr_reader :gem_name, :version
+
+    def initialize(gem_name, version)
+      @gem_name = gem_name
+      @version  = version
+    end
+
+    # Returns a hash of source_name => content strings (only populated keys).
+    def fetch_all
+      {
+        metadata:  metadata,
+        readme:    readme,
+        changelog: changelog,
+        examples:  examples
+      }.compact
+    end
+
+    def metadata
+      @metadata ||= local_metadata || rubygems_metadata
+    end
+
+    def readme
+      @readme ||= local_file(*README_CANDIDATES) || github_readme
+    end
+
+    def changelog
+      @changelog ||= local_file(*CHANGELOG_CANDIDATES)
+    end
+
+    def examples
+      @examples ||= local_examples
+    end
+
+    private
+
+    # --- local gem spec ---
+
+    def gem_spec
+      @gem_spec ||= Gem::Specification.find_by_name(gem_name, version)
+    rescue Gem::MissingSpecError, Gem::MissingSpecVersionError
+      nil
+    end
+
+    def gem_dir
+      @gem_dir ||= gem_spec&.gem_dir || locate_gem_dir
+    end
+
+    def locate_gem_dir
+      dir_name = "#{gem_name}-#{version}"
+      Gem.path.each do |base|
+        path = File.join(base, "gems", dir_name)
+        return path if File.directory?(path)
+      end
+      nil
+    end
+
+    def local_file(*candidates)
+      dir = gem_dir
+      return nil unless dir
+
+      candidates.each do |name|
+        path = File.join(dir, name)
+        return File.read(path, encoding: "utf-8") if File.exist?(path)
+      end
+      nil
+    end
+
+    def local_metadata
+      return nil unless gem_spec
+
+      spec  = gem_spec
+      lines = []
+      lines << "**Gem:** #{spec.name} #{spec.version}"
+      lines << "**Summary:** #{spec.summary}"                              if spec.summary.to_s.strip.length > 0
+      lines << "**Description:** #{spec.description}"                     if spec.description.to_s.strip.length > 0
+      lines << "**Author(s):** #{spec.authors.join(', ')}"                if spec.authors.any?
+      lines << "**Homepage:** #{spec.homepage}"                           if spec.homepage.to_s.strip.length > 0
+      lines << "**License(s):** #{spec.licenses.join(', ')}"              if spec.licenses.any?
+      lines << "**Source:** #{spec.metadata['source_code_uri']}"          if spec.metadata["source_code_uri"]
+      lines << "**Documentation:** #{spec.metadata['documentation_uri']}" if spec.metadata["documentation_uri"]
+
+      runtime_deps = spec.runtime_dependencies
+      if runtime_deps.any?
+        dep_list = runtime_deps.map { |d| "#{d.name} (#{d.requirement})" }.join(", ")
+        lines << "**Runtime dependencies:** #{dep_list}"
+      end
+
+      lines.join("\n")
+    end
+
+    def local_examples
+      dir = gem_dir
+      return nil unless dir
+
+      examples_dir = File.join(dir, "examples")
+      return nil unless File.directory?(examples_dir)
+
+      files = Dir.glob(File.join(examples_dir, "**", "*.{rb,md}")).sort
+      return nil if files.empty?
+
+      files.map do |path|
+        relative = path.delete_prefix("#{examples_dir}/")
+        content  = File.read(path, encoding: "utf-8")
+        "### #{relative}\n\n```\n#{content.strip}\n```"
+      end.join("\n\n")
+    rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      nil
+    end
+
+    # --- RubyGems API ---
+
+    def rubygems_data
+      @rubygems_data ||= begin
+        body = fetch_url(format(RUBYGEMS_API, gem_name))
+        body ? JSON.parse(body) : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    def rubygems_metadata
+      data = rubygems_data
+      return nil unless data
+
+      lines = []
+      lines << "**Gem:** #{data['name']} #{data['version']}"
+      lines << "**Summary:** #{data['info']}"                     if data["info"].to_s.strip.length > 0
+      lines << "**Homepage:** #{data['homepage_uri']}"            if data["homepage_uri"]
+      lines << "**Source:** #{data['source_code_uri']}"           if data["source_code_uri"]
+      lines << "**Documentation:** #{data['documentation_uri']}"  if data["documentation_uri"]
+
+      runtime_deps = data.dig("dependencies", "runtime") || []
+      if runtime_deps.any?
+        dep_list = runtime_deps.map { |d| "#{d['name']} (#{d['requirements']})" }.join(", ")
+        lines << "**Runtime dependencies:** #{dep_list}"
+      end
+
+      lines.join("\n")
+    end
+
+    # --- GitHub raw README ---
+
+    def github_readme
+      repo = github_repo
+      return nil unless repo
+
+      README_CANDIDATES.each do |filename|
+        %w[main master].each do |branch|
+          url     = format(GITHUB_RAW, repo, branch, filename)
+          content = fetch_url(url)
+          return content if content
+        end
+      end
+      nil
+    end
+
+    def github_repo
+      data = rubygems_data
+      return nil unless data
+
+      candidate_uris = [data["source_code_uri"], data["homepage_uri"]].compact
+      candidate_uris.each do |uri|
+        match = uri.match(%r{github\.com[/:](?<owner>[^/]+)/(?<repo>[^/.\s]+?)(?:\.git)?(?:/|$)})
+        return "#{match[:owner]}/#{match[:repo]}" if match
+      end
+      nil
+    end
+
+    # --- HTTP ---
+
+    def fetch_url(url, redirects_left: MAX_REDIRECTS)
+      return nil if redirects_left.zero?
+
+      uri        = URI(url)
+      uri.scheme = "https" if uri.scheme == "http"
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                 open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+        http.get(uri.request_uri, "User-Agent" => "gem-skill/#{Gem::Skill::VERSION}")
+      end
+
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        fetch_url(response["location"], redirects_left: redirects_left - 1)
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/gem/skill/generator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+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
+
+    SYSTEM_INSTRUCTIONS = <<~SYSTEM
+      You are a Ruby gem documentation specialist who generates Claude Code skill files.
+      A skill file gives Claude Code deep, practical knowledge about a library so it can
+      use it correctly without re-reading source docs. Be accurate, concise, and complete
+      for the most common use cases. No filler, no marketing language.
+    SYSTEM
+
+    SKILL_PROMPT = <<~PROMPT
+      Generate a SKILL.md for the Ruby gem "%<gem_name>s" version %<version>s.
+
+      Output raw Markdown directly. Do NOT wrap the output in a code fence or any
+      other container — the file is Markdown, so no ```markdown wrapper.
+
+      Begin immediately with the first section heading. Use exactly these sections:
+
+      ## Overview
+      One paragraph: what the gem does and when to reach for it.
+
+      ## Installation
+      Exact Gemfile/gemspec lines and any required post-install steps.
+
+      ## Core API
+      The most important classes, methods, and options. Show real method signatures
+      and return values. Prefer code over prose.
+
+      ## Common Patterns
+      The 3-5 most frequent real-world usage patterns with working code examples.
+
+      ## Gotchas & Edge Cases
+      Things that surprise developers: unexpected defaults, version-specific behavior,
+      thread safety concerns, performance cliffs, encoding issues.
+
+      ## Configuration
+      Initializer patterns, environment variables, defaults worth knowing.
+
+      ## Testing
+      How to test code that uses this gem: mocks, fakes, fixtures, VCR patterns.
+
+      Synthesize the sources below — do not copy them verbatim.
+      Write as a knowledgeable colleague, not a marketing document.
+
+      ---
+
+      %<sources>s
+    PROMPT
+
+    attr_reader :gem_name, :version, :model
+
+    def initialize(gem_name, version, model: DEFAULT_MODEL)
+      @gem_name = gem_name
+      @version  = version
+      @model    = model
+    end
+
+    # Generate and cache a SKILL.md. Returns the skill content string.
+    # Pass a block to stream output chunks to the caller for live feedback.
+    def generate(force: false, &block)
+      return Cache.read(gem_name, version) if Cache.cached?(gem_name, version) && !force
+
+      sources = Fetcher.new(gem_name, version).fetch_all
+      raise Error, "No documentation found for #{gem_name} #{version}" if sources.empty?
+
+      skill_content = block ? call_llm_streaming(sources, &block) : call_llm(sources)
+      Cache.store(gem_name, version, skill_content, { sources: sources.keys.map(&:to_s), model: model })
+      skill_content
+    rescue RubyLLM::Error => e
+      raise Error, e.message
+    end
+
+    private
+
+    def call_llm(sources)
+      chat = build_chat
+      response = chat.ask(format_prompt(sources))
+      strip_wrapper_fence(response.content)
+    end
+
+    def call_llm_streaming(sources)
+      content = +""
+      chat = build_chat
+      chat.ask(format_prompt(sources)) do |chunk|
+        text = chunk.content.to_s
+        next if text.empty?
+
+        yield text
+        content << text
+      end
+      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.
+    def strip_wrapper_fence(content)
+      content
+        .sub(/\A\s*```(?:markdown)?\s*\n/, "")
+        .sub(/\n```\s*\z/, "")
+        .strip
+    end
+
+    def build_chat
+      RubyLLM.chat(model: model).with_instructions(SYSTEM_INSTRUCTIONS)
+    end
+
+    def format_prompt(sources)
+      formatted = sources.map do |name, content|
+        body = content.length > MAX_SOURCE_CHARS ? "#{content[0, MAX_SOURCE_CHARS]}\n[... truncated ...]" : content
+        "### #{name.to_s.upcase}\n\n#{body}"
+      end.join("\n\n---\n\n")
+
+      format(SKILL_PROMPT, gem_name: gem_name, version: version, sources: formatted)
+    end
+  end
+end

data/lib/gem/skill/linker.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Gem::Skill
+  # Manages .claude/skills/ symlinks in a project, pointing to ~/.gem/skills cache.
+  module Linker
+    def self.skills_dir(project_root = Dir.pwd)
+      File.join(project_root, ".claude", "skills")
+    end
+
+    def self.link(gem_name, version, project_root = Dir.pwd)
+      target = Cache.skill_path(gem_name, version)
+      raise Error, "No cached skill for #{gem_name} #{version}. Run: gem skill install #{gem_name}" \
+        unless File.exist?(target)
+
+      dir = skills_dir(project_root)
+      FileUtils.mkdir_p(dir)
+
+      link_path = File.join(dir, "#{gem_name}.md")
+      File.unlink(link_path) if File.symlink?(link_path)
+      File.symlink(target, link_path)
+    end
+
+    def self.unlink(gem_name, project_root = Dir.pwd)
+      link_path = File.join(skills_dir(project_root), "#{gem_name}.md")
+      File.unlink(link_path) if File.symlink?(link_path)
+    end
+
+    def self.linked_gems(project_root = Dir.pwd)
+      dir = skills_dir(project_root)
+      return [] unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.md")).filter_map do |path|
+        next unless File.symlink?(path)
+
+        gem_name = File.basename(path, ".md")
+        target   = File.readlink(path)
+        version  = target.match(%r{/([^/]+)/SKILL\.md$})&.captures&.first
+        { gem_name: gem_name, version: version, target: target, valid: File.exist?(target) }
+      end
+    end
+
+    def self.prune_dead_links(project_root = Dir.pwd)
+      linked_gems(project_root)
+        .reject { |entry| entry[:valid] }
+        .each   { |entry| unlink(entry[:gem_name], project_root) }
+    end
+  end
+end

data/lib/gem/skill/lockfile.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Gem::Skill
+  # Parses Gemfile.lock to extract direct dependency gem name/version pairs.
+  # Direct deps are listed in the DEPENDENCIES section; versions come from specs.
+  module Lockfile
+    def self.gems(lockfile_path = "Gemfile.lock")
+      raise Error, "Gemfile.lock not found at #{lockfile_path}" unless File.exist?(lockfile_path)
+
+      parse(File.read(lockfile_path))
+    end
+
+    def self.parse(content)
+      specs   = parse_specs(content)
+      direct  = parse_direct_names(content)
+      direct.each_with_object({}) do |name, hash|
+        hash[name] = specs[name] if specs.key?(name)
+      end
+    end
+
+    def self.parse_specs(content)
+      in_specs = false
+      specs    = {}
+
+      content.each_line do |line|
+        if line.strip == "specs:"
+          in_specs = true
+          next
+        elsif in_specs && line =~ /\A {4}(\S+) \(([^)]+)\)/
+          specs[Regexp.last_match(1)] = Regexp.last_match(2)
+        elsif in_specs && line !~ /\A /
+          in_specs = false
+        end
+      end
+
+      specs
+    end
+
+    def self.parse_direct_names(content)
+      in_deps = false
+      names   = []
+
+      content.each_line do |line|
+        if line.strip == "DEPENDENCIES"
+          in_deps = true
+          next
+        elsif in_deps && line =~ /\A  (\S+)/
+          # Strip version constraints from dep names like "ruby_llm (>= 1.0)"
+          names << Regexp.last_match(1)
+        elsif in_deps && !line.strip.empty?
+          in_deps = false
+        end
+      end
+
+      names
+    end
+  end
+end

data/lib/gem/skill/version.rb

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

data/lib/gem/skill.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "skill/version"
+require_relative "skill/cache"
+require_relative "skill/fetcher"
+require_relative "skill/generator"
+require_relative "skill/linker"
+require_relative "skill/lockfile"
+
+module Gem::Skill
+  class Error < StandardError; end
+
+  ENV_KEY_MAP = {
+    anthropic_api_key:  "ANTHROPIC_API_KEY",
+    openai_api_key:     "OPENAI_API_KEY",
+    gemini_api_key:     "GEMINI_API_KEY",
+    mistral_api_key:    "MISTRAL_API_KEY",
+    deepseek_api_key:   "DEEPSEEK_API_KEY",
+    openrouter_api_key: "OPENROUTER_API_KEY",
+    xai_api_key:        "XAI_API_KEY"
+  }.freeze
+
+  # 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|
+      ENV_KEY_MAP.each do |attr, env_var|
+        value = ENV[env_var]
+        config.public_send(:"#{attr}=", value) if value
+      end
+    end
+  end
+end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "gem/skill/cli/gem_command"
+Gem::CommandManager.instance.register_command :skill
+
+require "rubygems/commands/install_command"
+require "tty-spinner"
+
+module Gem::Skill
+  module InstallSkillOption
+    def initialize
+      super
+      add_option("--with-skill", "Generate Claude Code SKILL.md files after installation") do |_, opts|
+        opts[:generate_skill] = true
+      end
+    end
+  end
+end
+
+Gem::Commands::InstallCommand.prepend(Gem::Skill::InstallSkillOption)
+
+module Gem::Skill
+  @pending_skills = []
+  @pending_lock   = Mutex.new
+
+  class << self
+    attr_reader :pending_skills, :pending_lock
+
+    def generate_pending_skills
+      return if @pending_skills.empty?
+
+      configure_llm!
+
+      multi = TTY::Spinner::Multi.new(
+        "[:spinner] Writing skills",
+        format: :dots,
+        output: $stderr
+      )
+
+      threads = @pending_skills.map do |gem_info|
+        name    = gem_info[:name]
+        version = gem_info[:version]
+        sp = multi.register("  [:spinner] :title")
+        sp.update(title: "#{name} #{version}")
+        Thread.new(name, version, sp) { |n, v, spinner| generate_one_skill(n, v, spinner) }
+      end
+      threads.each(&:join)
+    rescue => e
+      warn "gem-skill: #{e.message}"
+    end
+
+    def generate_one_skill(name, version, spinner)
+      spinner.auto_spin
+      Generator.new(name, version).generate
+      spinner.success("done")
+    rescue => e
+      spinner.error("failed")
+      warn "gem-skill: #{name}: #{e.message}"
+    end
+  end
+end
+
+Gem.post_install do |installer|
+  next unless installer.options[:generate_skill]
+  Gem::Skill.pending_lock.synchronize do
+    Gem::Skill.pending_skills << { name: installer.spec.name, version: installer.spec.version.to_s }
+  end
+end
+
+at_exit { Gem::Skill.generate_pending_skills }

data/plugins.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Bundler plugin entry point — loaded by `bundle plugin install gem-skill`
+# or `plugin 'gem-skill'` in Gemfile. Registers the `bundle skill` command.
+
+require_relative "lib/gem/skill/cli/bundle_command"
+
+Bundler::Plugin::API.commands "skill" do |_command, args|
+  Gem::Skill::BundlerCommand.run(args)
+end

data/scripts/e2e_test

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# End-to-end test: fetch docs for a gem and generate a SKILL.md
+# Usage: bundle exec ruby bin/e2e_test [GEM_NAME [VERSION]]
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "gem/skill"
+require "ruby_llm"
+
+GEM_NAME = ARGV[0] || "zeitwerk"
+VERSION  = ARGV[1] || Gem::Specification.find_by_name(GEM_NAME)&.version&.to_s
+MODEL    = ARGV[2] || "gpt-4o-mini"
+
+abort "Gem '#{GEM_NAME}' not installed. Run: gem install #{GEM_NAME}" unless VERSION
+
+Gem::Skill.configure_llm!
+
+puts "=" * 60
+puts "gem-skill end-to-end test"
+puts "Gem:   #{GEM_NAME} #{VERSION}"
+puts "Model: #{MODEL}"
+puts "Cache: #{Gem::Skill::Cache.root}"
+puts "=" * 60
+puts ""
+
+# --- Phase 1: Fetch ---
+
+puts "[ FETCH ]"
+fetcher = Gem::Skill::Fetcher.new(GEM_NAME, VERSION)
+sources = fetcher.fetch_all
+
+if sources.empty?
+  abort "No sources found — nothing to generate from."
+end
+
+sources.each do |name, content|
+  puts "  %-12s %d chars" % [name, content.length]
+end
+puts ""
+
+# --- Phase 2: Generate ---
+
+puts "[ GENERATE ]  streaming output below"
+puts "-" * 60
+
+skill_content = ""
+generator = Gem::Skill::Generator.new(GEM_NAME, VERSION, model: MODEL)
+skill_content = generator.generate(force: true) do |chunk|
+  print chunk
+  $stdout.flush
+end
+
+puts ""
+puts "-" * 60
+puts ""
+
+# --- Phase 3: Verify cache ---
+
+puts "[ CACHE ]"
+cached_path = Gem::Skill::Cache.skill_path(GEM_NAME, VERSION)
+if File.exist?(cached_path)
+  puts "  Written: #{cached_path}"
+  puts "  Size:    #{File.size(cached_path)} bytes"
+else
+  puts "  ERROR: cache file not found at #{cached_path}"
+  exit 1
+end
+
+puts ""
+puts "Done."

data/sig/gem/skill.rbs

@@ -0,0 +1,4 @@
+module Gem::Skill
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end