gem-skill 0.1.3 → 0.2.2

data/docs/how-it-works.md

@@ -16,6 +16,9 @@ Gemfile.lock / gem name
       ↓
   Cache             write to ~/.gem/skills/<gem>/<version>/
       ↓
+  Verifier          (optional, --verify) check the skill's code against the
+                    gem's actual source; correct mismatches in place
+      ↓
   Linker            symlink .claude/skills/<gem> → cache dir
 ```
 
@@ -78,27 +81,71 @@ Manages the global skill cache. Structure:
 └── <gem_name>/
     └── <version>/
         ├── SKILL.md
-        └── metadata.json   (gem, version, model, generated_at, sources)
+        └── metadata.json   (gem, version, model, generated_at, sources,
+                             and after --verify: a "verification" block with
+                             source provenance + structured changes)
 ```
 
 `Cache::ROOT` is set once at load time from `GEMSKILL_DIR` (default: `~/.gem/skills`).
 
+`read_metadata` / `write_skill` / `merge_metadata` let the verifier rewrite a
+cached skill and annotate its metadata without clobbering the original
+`generated_at`, `model`, or `sources`.
+
+### Verifier
+
+`lib/gem/skill/verifier.rb`
+
+Optional second pass, enabled by `--verify`. Generation synthesizes prose
+sources (README, changelog, examples) which are frequently stale or wrong about
+exact signatures. The verifier re-checks the generated skill against the gem's
+**actual source code** — the only source of truth — and corrects mismatched
+method signatures, default argument values, visibility, return values, and
+behavioral claims.
+
+```ruby
+Verifier.new(gem_name, version, model:).verify(skill_content)
+# => Result(content:, changes:, changed:, verifiable:, source:, model:)
+```
+
+Ground truth comes from `Fetcher#source_code` (the gem's `lib/**/*.rb`), and
+`Fetcher#source_manifest` records which files were examined. Whether the skill
+actually changed is decided by a **deterministic diff** of the content before and
+after — not by trusting the model's self-report — so the exit code is reliable.
+If no installed source is available, `verifiable` is false and the skill is left
+untouched.
+
+Each correction in `changes` is a structured, issue-ready Hash
+(`category`, `symbol`, `skill_section`, `source_location`, `was`, `now`,
+`detail`, `source_evidence`) — detailed enough to file a documentation bug
+against the gem. The Runner writes these, plus source provenance, into the
+`verification` block of `metadata.json`.
+
 ### Linker
 
 `lib/gem/skill/linker.rb`
 
-Creates and manages directory symlinks in `.claude/skills/` inside a project:
+Creates and manages directory symlinks in the project's skill directory
+(default `.claude/skills/`, Claude Code's convention):
 
 ```
-.claude/skills/<gem_name>  →  ~/.gem/skills/<gem_name>/<version>/
+<project_dir>/<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.
+The directory is `Linker.project_dir`, read from `GEMSKILL_PROJECT_DIR` each call
+(default `.claude/skills`). Codex users set it to `.agents` or `.codex` so
+`bundle skill` links into a Codex root instead. Symlinks point to the **version
+directory**, not directly to `SKILL.md`; the assistant 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`).
 
+The cache itself is assistant-neutral. `SKILL.md` is a shared format; other
+assistants read it from their own roots. Note that linking only makes a skill
+*available* — some assistants (e.g. Codex) require it to be in the available-skills
+list or referenced explicitly before it's *active*.
+
 ### Runner
 
 `lib/gem/skill/runner.rb`
@@ -107,12 +154,14 @@ 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
+Runner.install_skill(gem_name, version, spinner, force:, model:, verify:)
+# => Runner::Result(error:, verify_fixed:, change_count:)
 ```
 
-Returns the error message rather than raising, so the caller (the concurrent
-fiber) can record it without killing other in-flight fibers.
+Captures errors into the result rather than raising, so the caller (the
+concurrent fiber) can record them without killing other in-flight fibers. When
+`verify:` is set, the result's `verify_fixed` lets the CLI aggregate across all
+gems and exit `2` (`EXIT_VERIFY_FIXED`) if any skill was corrected.
 
 ---
 

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

@@ -1,14 +1,17 @@
 # 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).
-  # 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 +45,12 @@ 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
+      max_tokens = opts[:max_tokens] || Generator::MAX_TOKENS
+      errors     = []
+      results    = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Installing skills (#{model})",
@@ -58,8 +64,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, max_tokens: max_tokens)
+            results << result
+            errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
         end
         barrier.wait
@@ -69,14 +76,18 @@ 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
+      max_tokens = opts[:max_tokens] || Generator::MAX_TOKENS
+      errors     = []
+      results    = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Refreshing skills (#{model})",
@@ -90,14 +101,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, max_tokens: max_tokens)
             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 +119,7 @@ module Gem::Skill
 
       Linker.prune_dead_links
       report_errors(errors)
+      report_verify(results, verify)
     end
 
     def self.list
@@ -120,7 +133,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 +143,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, max_tokens: Generator::MAX_TOKENS)
       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, max_tokens: max_tokens)
     end
     private_class_method :install_one
 
@@ -144,6 +157,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,9 +178,12 @@ 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]
+        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--/
@@ -170,13 +200,18 @@ 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
-          --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)
       USAGE
     end
     private_class_method :usage