gem-skill 0.1.2 → 0.2.0

data/docs/commands/gem-skill.md

@@ -0,0 +1,212 @@
+# gem skill
+
+The `gem skill` command manages the global skill cache at `~/.gem/skills`.
+It works with any installed gem regardless of project context.
+
+## Subcommands
+
+### `gem skill install`
+
+Generate and cache a `SKILL.md` for one or more gems.
+
+```bash
+gem skill install GEM_NAME [GEM_NAME ...]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--force`, `-f` | Regenerate even if a skill is already cached |
+| `--verify` | After generating, verify the skill's code against the gem's actual source and fix mismatches |
+| `--model MODEL`, `-m MODEL` | LLM model to use (overrides `GEMSKILL_MODEL`) |
+| `--version`, `-v` | Print the installed gem-skill version and exit |
+
+**Examples:**
+
+```bash
+# Single gem (version auto-detected from installed gems)
+gem skill install debug_me
+
+# Multiple gems concurrently
+gem skill install faraday zeitwerk dry-validation
+
+# Force regeneration with a specific model
+gem skill install rails --force --model claude-opus-4-8
+
+# Generate, then verify the result against the gem's source code
+gem skill install tty-spinner --verify
+```
+
+If a gem is not installed locally, gem-skill will install it automatically
+before generating the skill.
+
+### Verifying against source (`--verify`)
+
+The generation pass synthesizes a skill from a gem's README, changelog, and
+examples. That prose is sometimes stale or wrong about exact method signatures,
+default argument values, and behavior. `--verify` adds a second pass that checks
+the generated skill against the gem's **actual installed source code** (the only
+source of truth) and rewrites anything the source contradicts.
+
+Verification requires the gem to be installed locally (it reads `lib/**/*.rb`).
+If no source is available, the skill is left untouched.
+
+**Exit status** (so CI can detect README/source drift):
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success — skill was clean, or `--verify` not used |
+| `1` | Error |
+| `2` | `--verify` found and corrected problems |
+
+Either way, `metadata.json` gains a `verification` block recording that the gem's
+actual source was consulted, which files were examined, and — when fixes were
+applied — an array of structured, issue-ready corrections (affected symbol,
+source location, what the skill said vs. the truth, and the proving source
+snippet). See [Cache layout](cache.md#metadatajson) for the full schema.
+
+A verified skill is flagged with a green checkmark in
+[`gem skill list`](#gem-skill-list).
+
+---
+
+### `gem skill verify`
+
+Verify an **already-cached** skill against the gem's source, in place, without
+regenerating it.
+
+```bash
+gem skill verify GEM_NAME [GEM_NAME ...]
+```
+
+This runs the same source-truth check as `--verify`, but never generates: the
+gem must be installed (verification reads its source) and the skill must already
+be cached. It errors if either is missing rather than generating a new skill.
+
+```bash
+# Verify the cached tty-spinner skill against its installed source
+gem skill verify tty-spinner
+```
+
+Exit status matches `--verify`: `0` clean, `1` error, `2` when corrections were
+applied. Verified versions are flagged with a green checkmark in
+[`gem skill list`](#gem-skill-list).
+
+---
+
+### `gem skill --version`
+
+Print the installed gem-skill version and exit.
+
+```bash
+gem skill --version
+# 0.1.3
+gem skill -v
+# 0.1.3
+```
+
+All gems are processed concurrently — you'll see a live spinner per gem:
+
+```
+⠋ Generating skills (claude-sonnet-4-6)
+  ✓ debug_me 1.1.0 done
+  ✓ faraday 2.12.0 done
+  ⠋ zeitwerk 2.8.2
+```
+
+---
+
+### `gem skill setup`
+
+Run once after `gem install gem-skill`.
+
+```bash
+gem skill setup
+```
+
+It does two things:
+
+1. **Registers gem-skill as a Bundler plugin** so `bundle skill` works in any
+   project on the machine.
+2. **Installs the `ruby-gem-skills` router skill** into the default skill root of
+   each detected assistant — `~/.claude/skills` (Claude Code), `~/.codex/skills`
+   and `~/.agents/skills` (Codex). A root is only written if its assistant home
+   (`~/.claude`, `~/.codex`, `~/.agents`) already exists.
+
+The router skill matters because cached gem skills live in `~/.gem/skills`, a
+directory assistants don't scan by default. This small always-on skill triggers
+when you work with a Ruby gem and tells the assistant how to find and read that
+gem's cached `SKILL.md` (resolving the version from `Gemfile.lock` or the
+installed gem). Re-run `gem skill setup` after upgrading gem-skill to refresh the
+copy. See [Installation](../installation.md) for details.
+
+---
+
+### `gem skill list`
+
+Show all skills currently in the global cache. A green checkmark (`✓`) appears
+next to any version whose skill has been verified against the gem's source (via
+`--verify` or `gem skill verify`); unverified versions show no mark.
+
+```bash
+gem skill list
+```
+
+**Example output:**
+
+```
+Cached skills in /Users/you/.gem/skills:
+
+  debug_me                       1.1.0
+  faraday                        2.12.0, 2.14.3 ✓
+  zeitwerk                       2.8.2 ✓
+
+3 gem(s), 4 version(s) total.
+```
+
+Here `faraday 2.14.3` and `zeitwerk 2.8.2` have verified skills, while
+`faraday 2.12.0` and `debug_me 1.1.0` have not been verified. The checkmark is
+shown in green when the output is an interactive terminal, and as a plain `✓`
+when piped or redirected. "Verified" means the skill was checked against the
+gem's actual source — see [`gem skill verify`](#gem-skill-verify).
+
+---
+
+### `gem skill purge`
+
+Remove a cached skill version.
+
+```bash
+# Remove a specific version
+gem skill purge GEM_NAME VERSION
+
+# Remove all cached versions of a gem
+gem skill purge GEM_NAME --all
+```
+
+**Examples:**
+
+```bash
+gem skill purge faraday 2.12.0
+gem skill purge rails --all
+```
+
+---
+
+## `gem install --with-skill`
+
+Generate skills automatically as you install gems:
+
+```bash
+gem install faraday zeitwerk --with-skill
+```
+
+All gems install normally first. Skills are then generated concurrently after
+all installs complete — same spinner UI as `gem skill install`.
+
+This works for any `gem install` command, including version-pinned installs:
+
+```bash
+gem install rails --version "~> 7.1" --with-skill
+```

data/docs/configuration.md

@@ -0,0 +1,112 @@
+# Configuration
+
+## LLM provider API keys
+
+gem-skill uses [RubyLLM](https://github.com/crmne/ruby_llm) to generate skills.
+Set at least one provider API key before running any `install` command:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."   # Claude models
+export OPENAI_API_KEY="sk-..."          # GPT models
+export GEMINI_API_KEY="..."             # Gemini models
+```
+
+Other supported providers:
+
+| Environment variable    | Provider     |
+|------------------------|--------------|
+| `ANTHROPIC_API_KEY`    | Anthropic    |
+| `OPENAI_API_KEY`       | OpenAI       |
+| `GEMINI_API_KEY`       | Google Gemini|
+| `MISTRAL_API_KEY`      | Mistral      |
+| `DEEPSEEK_API_KEY`     | DeepSeek     |
+| `OPENROUTER_API_KEY`   | OpenRouter   |
+| `XAI_API_KEY`          | xAI (Grok)   |
+
+## gem-skill environment variables
+
+### `GEMSKILL_DIR`
+
+Controls where generated skills are cached.
+
+| | |
+|---|---|
+| **Default** | `~/.gem/skills` |
+| **Example** | `export GEMSKILL_DIR="/Volumes/shared/gem-skills"` |
+
+Useful for sharing a skill cache across machines via a network drive, or for
+keeping skills in a non-standard location.
+
+### `GEMSKILL_PROJECT_DIR`
+
+The project-relative directory where `bundle skill` writes its symlinks into the
+cache. Change it to match whichever assistant you use.
+
+| | |
+|---|---|
+| **Default** | `.claude/skills` (Claude Code) |
+| **Example** | `export GEMSKILL_PROJECT_DIR=".agents"` |
+
+`SKILL.md` is a shared format, but each assistant looks for skills in its own
+project directory:
+
+| Assistant    | Suggested `GEMSKILL_PROJECT_DIR` |
+|--------------|----------------------------------|
+| Claude Code  | `.claude/skills` (default)       |
+| OpenAI Codex | `.agents` or `.codex`            |
+
+```bash
+# Claude Code (default — no need to set anything)
+bundle skill install
+
+# OpenAI Codex — link into a Codex project root instead
+export GEMSKILL_PROJECT_DIR=".agents"
+bundle skill install        # symlinks now land in .agents/
+```
+
+A blank or unset value falls back to the `.claude/skills` default.
+
+!!! note "Availability is not activation"
+    Setting `GEMSKILL_PROJECT_DIR` controls *where the symlinks are written*. It
+    does not change how an assistant decides a skill is active. Claude Code
+    activates every `SKILL.md` under `.claude/skills/` automatically; other
+    assistants (e.g. Codex) may require the skill to be in the session's
+    available-skills list or referenced explicitly. See
+    [Using with other assistants](skill-files.md#using-with-other-assistants).
+
+### `GEMSKILL_MODEL`
+
+Controls which LLM model is used when generating skills.
+
+| | |
+|---|---|
+| **Default** | `gpt-5.5` |
+| **Example** | `export GEMSKILL_MODEL="claude-opus-4-8"` |
+
+The `--model` flag on any command overrides `GEMSKILL_MODEL` for that single
+invocation only.
+
+## Recommended shell configuration
+
+Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GEMSKILL_MODEL="claude-sonnet-4-6"   # or whichever model you prefer
+```
+
+## Model selection guidance
+
+| Model | Best for |
+|-------|----------|
+| Claude Opus 4.8 | Highest quality skills; comprehensive coverage |
+| Claude Sonnet 4.6 | Good balance of quality and speed |
+| Claude Haiku 4.5 | Fast, cheap; good for simple gems |
+| GPT-5.5 | Default; strong general-purpose coverage |
+
+Pass `--model MODEL` to any install command to override for one run:
+
+```bash
+gem skill install rails --model claude-opus-4-8
+bundle skill install --model claude-haiku-4-5
+```

data/docs/how-it-works.md

@@ -0,0 +1,209 @@
+# 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>/
+      ↓
+  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
+```
+
+`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,
+                             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 the project's skill directory
+(default `.claude/skills/`, Claude Code's convention):
+
+```
+<project_dir>/<gem_name>  →  ~/.gem/skills/<gem_name>/<version>/
+```
+
+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`
+
+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:, verify:)
+# => Runner::Result(error:, verify_fixed:, change_count:)
+```
+
+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.
+
+---
+
+## 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,73 @@
+<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 <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>
+</table>
+</p>
+
+## The problem it solves
+
+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 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
+
+```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
+        ↓
+   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
+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`, `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/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.