gem-skill 0.1.3 → 0.2.0

data/docs/index.md

@@ -3,9 +3,10 @@
   <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>
+      Generate <code>SKILL.md</code> files for AI coding assistants
+      (Claude Code, OpenAI Codex, and others) from Ruby gem documentation,
+      and cache 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>
@@ -14,14 +15,15 @@
 
 ## 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.
+Every time an AI coding assistant 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.
+`SKILL.md` in `~/.gem/skills`. Projects symlink to the cached version, so your
+assistant has accurate, version-specific knowledge about each gem without
+repeating the ingestion work. `SKILL.md` is a shared format — Claude Code,
+OpenAI Codex, and other assistants all read it.
 
 ## Quick start
 
@@ -53,7 +55,8 @@ gem README / changelog / RubyGems API
         ↓
    Linker creates .claude/skills/<gem> → cache dir
         ↓
-   Claude Code reads SKILL.md automatically
+   The assistant reads SKILL.md automatically
+   (Claude Code from .claude/skills/; other assistants from their own roots)
 ```
 
 All concurrent work is handled by async fibers — multiple gems are processed
@@ -66,4 +69,5 @@ simultaneously with live TTY spinner progress.
 - **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
+- **Configurable** — `GEMSKILL_DIR`, `GEMSKILL_PROJECT_DIR`, and `GEMSKILL_MODEL` environment variables
+- **Multi-assistant** — `SKILL.md` works with Claude Code, OpenAI Codex, and others; `GEMSKILL_PROJECT_DIR` points project links at the right directory

data/docs/skill-files.md

@@ -1,15 +1,23 @@
 # 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/`.
+A `SKILL.md` is a structured Markdown document that gives an AI coding assistant
+deep, practical knowledge about a Ruby gem. It's a shared format — assistants
+such as Claude Code and OpenAI Codex read it automatically when it is present in
+the skills directory they look in (Claude Code uses `.claude/skills/`; see
+[Using the cache with other assistants](#using-with-other-assistants)).
 
 ## Format
 
-Every generated skill starts with a top-level heading identifying the gem and
-version, then covers seven sections:
+Every generated skill begins with **YAML frontmatter** — the `name` and
+`description` that make it discoverable as an Agent Skill — followed by a
+top-level heading and seven sections:
 
 ```markdown
+---
+name: faraday
+description: "HTTP client library for Ruby with pluggable adapters and middleware; use when making HTTP requests... (faraday v2.14.3)"
+---
+
 # faraday v2.14.3
 
 ## Overview
@@ -34,12 +42,27 @@ Initializer patterns, environment variables, defaults worth knowing.
 How to test code that uses this gem: mocks, fakes, fixtures, VCR patterns.
 ```
 
-## What Claude does with it
+### Frontmatter
+
+The frontmatter is what registers the file as a skill — both Claude Code and
+OpenAI Codex require it, and the `description` is the text loaded into the
+assistant's context to decide *when* the skill applies. gem-skill generates it
+deterministically:
+
+- **`name`** — the gem name normalized to hyphen-case (lowercase letters,
+  digits, hyphens). For example `ruby_llm` becomes `ruby-llm`, since underscores
+  aren't allowed in skill names.
+- **`description`** — a one-line, trigger-oriented summary derived from the
+  Overview, with the version appended, sanitized to satisfy both assistants
+  (single line, no angle brackets).
 
-When Claude Code opens a project containing `.claude/skills/`, it reads every
-`SKILL.md` it finds. This means:
+## What an assistant does with it
 
-- Claude knows the correct API for the exact version you're using
+When an assistant opens a project whose skills directory contains `SKILL.md`
+files, it reads every one it finds (Claude Code, for instance, reads everything
+in `.claude/skills/`). This means:
+
+- The assistant 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
@@ -75,4 +98,44 @@ gem skill install my_gem --force
 
 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.
+matching your `Gemfile.lock`, so the assistant always has the right version
+context.
+
+## Using with other assistants
+
+`SKILL.md` is not specific to one assistant. The `~/.gem/skills` cache is
+assistant-neutral; `bundle skill` links skills into `.claude/skills/`, which
+Claude Code reads automatically. Other assistants discover skills in their own
+roots:
+
+| Assistant | Global roots | Project-local roots |
+|---|---|---|
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| OpenAI Codex | `~/.codex/skills`, `~/.agents/skills` | `.agents/`, `.codex/` |
+
+**Project-local (recommended):** point `bundle skill` at the right directory with
+the `GEMSKILL_PROJECT_DIR` environment variable (default `.claude/skills`):
+
+```bash
+export GEMSKILL_PROJECT_DIR=".agents"   # or ".codex"
+bundle skill install                    # symlinks now land in .agents/
+```
+
+See [`GEMSKILL_PROJECT_DIR`](configuration.md#gemskill_project_dir) for the full
+table of suggested values.
+
+**Global:** to share cached skills across all projects for an assistant, symlink
+a cached version directory into its global root:
+
+```bash
+ln -s ~/.gem/skills/faraday/2.14.3 ~/.agents/skills/faraday
+```
+
+!!! note "Availability is not the same as activation"
+    Assistants differ in how a present `SKILL.md` becomes active. **Claude Code**
+    treats every `SKILL.md` under `.claude/skills/` as active automatically.
+    **OpenAI Codex** does *not* auto-activate a skill just because the file
+    exists — it must appear in the session's available-skills list, or you must
+    explicitly point Codex at it. So linking a skill into a Codex root makes it
+    *available* but may not make it *active* on its own; check your assistant's
+    skill-discovery rules.

data/lib/gem/skill/cache.rb

@@ -42,6 +42,30 @@ module Gem::Skill
       File.read(path)
     end
 
+    # Read metadata.json back as a Hash with string keys. Returns {} if absent
+    # or unparseable.
+    def self.read_metadata(gem_name, version)
+      path = metadata_path(gem_name, version)
+      return {} unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Overwrite just the SKILL.md content, leaving metadata untouched.
+    def self.write_skill(gem_name, version, skill_content)
+      File.write(skill_path(gem_name, version), skill_content)
+    end
+
+    # Merge additional keys into the existing metadata.json, preserving
+    # generated_at, model, sources, etc. Keys are normalized to strings so a
+    # symbol key never collides with its string twin.
+    def self.merge_metadata(gem_name, version, extra)
+      data = read_metadata(gem_name, version).merge(extra.transform_keys(&:to_s))
+      File.write(metadata_path(gem_name, version), JSON.generate(data))
+    end
+
     def self.versions(gem_name)
       dir = File.join(ROOT, gem_name)
       return [] unless Dir.exist?(dir)

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

@@ -8,7 +8,8 @@ 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.
+  # Project-aware: reads Gemfile.lock and manages project skill symlinks
+  # (directory set by GEMSKILL_PROJECT_DIR, default .claude/skills/).
   module BundlerCommand
     SUBCOMMANDS = %w[install refresh list].freeze
 
@@ -42,9 +43,11 @@ module Gem::Skill
         return
       end
 
-      force  = opts[:force]
-      model  = opts[:model] || Generator::DEFAULT_MODEL
-      errors = []
+      force   = opts[:force]
+      verify  = opts[:verify]
+      model   = opts[:model] || Generator::DEFAULT_MODEL
+      errors  = []
+      results = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Installing skills (#{model})",
@@ -58,8 +61,9 @@ module Gem::Skill
           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
+            result = install_one(gem_name, version, sp, force: force, model: model, verify: verify)
+            results << result
+            errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
         end
         barrier.wait
@@ -69,14 +73,17 @@ module Gem::Skill
 
       Linker.prune_dead_links
       report_errors(errors)
+      report_verify(results, verify)
     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 = []
+      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 = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Refreshing skills (#{model})",
@@ -90,14 +97,15 @@ module Gem::Skill
           sp = multi.register("  [:spinner] :title")
           sp.update(title: "#{gem_name} #{version}")
           barrier.async do
-            err = if !force && linked[gem_name] == version
+            result = if !force && linked[gem_name] == version
               sp.auto_spin
               sp.success("up to date")
-              nil
+              Runner::Result.success
             else
-              install_one(gem_name, version, sp, force: force, model: model)
+              install_one(gem_name, version, sp, force: force, model: model, verify: verify)
             end
-            errors << "#{gem_name} #{version}: #{err}" if err
+            results << result
+            errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
         end
         barrier.wait
@@ -107,6 +115,7 @@ module Gem::Skill
 
       Linker.prune_dead_links
       report_errors(errors)
+      report_verify(results, verify)
     end
 
     def self.list
@@ -120,7 +129,7 @@ module Gem::Skill
       ok     = entries.count { |e| e[:valid] }
       broken = entries.size - ok
 
-      puts "Skills linked in .claude/skills/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
+      puts "Skills linked in #{Linker.project_dir}/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
       puts ""
       entries.each do |e|
         status = e[:valid] ? "ok    " : "BROKEN"
@@ -130,9 +139,9 @@ module Gem::Skill
 
     # --- private ---
 
-    def self.install_one(gem_name, version, spinner, force:, model:)
+    def self.install_one(gem_name, version, spinner, force:, model:, verify: false)
       spinner.auto_spin
-      Runner.install_skill(gem_name, version, spinner, force: force, model: model)
+      Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify)
     end
     private_class_method :install_one
 
@@ -144,6 +153,20 @@ module Gem::Skill
     end
     private_class_method :report_errors
 
+    # When --verify applied fixes, report and exit non-zero so callers/CI can
+    # detect that the README-derived skill disagreed with the source.
+    def self.report_verify(results, verify)
+      return unless verify
+
+      fixed = results.count(&:verify_fixed)
+      return if fixed.zero?
+
+      warn ""
+      warn "Verify corrected #{fixed} skill(s) against gem source."
+      exit Gem::Skill::EXIT_VERIFY_FIXED
+    end
+    private_class_method :report_verify
+
     def self.parse_options(args)
       opts      = {}
       remaining = []
@@ -151,6 +174,7 @@ module Gem::Skill
       args.each do |arg|
         case arg
         when "--force"           then opts[:force] = true
+        when "--verify"          then opts[:verify] = true
         when "--version", "-v"   then opts[:version] = true
         when /\A--model(?:=(.+))?\z/
           opts[:model] = $1 || args[args.index(arg) + 1]
@@ -170,13 +194,17 @@ module Gem::Skill
 
         Subcommands:
           install   Generate and link skills for all gems in Gemfile.lock
-          refresh   Re-sync .claude/skills/ after bundle update
+          refresh   Re-sync the project skill directory after bundle update
           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
+
+        Env:
+          GEMSKILL_PROJECT_DIR   Project dir for symlinks (default: .claude/skills)
       USAGE
     end
     private_class_method :usage

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

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

data/lib/gem/skill/fetcher.rb

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