gem-skill 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e537a3925c494c903dc9dd105d6a975d55d5fe55f963847cca3c363ce26120d6
-  data.tar.gz: 7f4fd4cff99d062ab50bf73b733aeddca903f23ffb657ccc7cc7616dcd7e2fe6
+  metadata.gz: 81806de91a59a0b2f9144dedebda65f568d61629064f6182f753229fced49583
+  data.tar.gz: 444441e8f081192ceb5b6201bc8c2c9428b243729df896a4405db562d435ad7d
 SHA512:
-  metadata.gz: 2d74ee4cdbf3b827984574580985426ec708e7dfd901f2ddb99f03268afdcc96a2ab9f8962781549c053e587f1ecbd4f0d5cab06189adb24603af475083ab54e
-  data.tar.gz: e012f26a513a5516d606c6664c1ccd470ed910bd57190850e96daf1bc88e686e00dfbfc2b6f9bd8a467bdde6d5ca938b3084697ca27d2a956043b05e9d8dac37
+  metadata.gz: 39ed27eb70e0036d097b01576a78a20a13ed337ddf05abfc5f5a63a0279b65c79d327907cc70fa96d132d7e72ae3d47ce5cdb5a0bb50e30cbfbb441ce428611d
+  data.tar.gz: 6c0fd5f43ffeac14efe923f9b1742ab469d3e08c50f86dd521c38d45d003800fe45a8447dcb682df0014419d1421d1b2f20eb326d3b6c7f2d3b1d7d0210974bb

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Deploy to GitHub Pages
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "Deploying from main branch"
+            mkdocs gh-deploy --force --clean
+          else
+            echo "Deploying from develop branch"
+            mkdocs gh-deploy --force --clean
+          fi

data/CHANGELOG.md

@@ -1,5 +1,33 @@
+# Changelog
+
+All notable changes to gem-skill are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
 ## [Unreleased]
 
+## [0.1.3] - 2026-06-17
+
+### Added
+- `gem skill setup` subcommand — registers gem-skill as a Bundler plugin in one step
+- `--version` / `-v` flag for both `gem skill` and `bundle skill`
+- `post_install_message` guiding users to run `gem skill setup` after install
+- `async` gem dependency — concurrent fiber-based LLM calls replace threads
+- `Gem::Skill::Runner` module — shared `install_skill` core extracted from both CLI commands
+- `test/support/cache_helpers.rb` — shared `stub_cache_root`/`restore_cache_root` test helpers
+- MkDocs documentation site (`docs/`) with full reference for all commands, cache layout, skill file format, and architecture
+
+### Changed
+- `bundle skill install` and `bundle skill refresh` now run all gems concurrently via `Async::Barrier` (previously sequential)
+- `gem skill install` also migrated from threads to async fibers
+- `Lockfile.gems` now includes runtime dependencies declared in gemspec files (via `gemspec` in `Gemfile`), not just direct `Gemfile` entries
+- `.claude/skills/` symlinks now point to version directories (e.g. `~/.gem/skills/faraday/2.14.3/`) instead of individual `SKILL.md` files
+- `GEMSKILL_DIR` environment variable controls the cache root (default: `~/.gem/skills`)
+- `GEMSKILL_MODEL` environment variable controls the default LLM model
+- `scripts/e2e_test` updated to exercise the full pipeline: Fetch → Runner → Cache → Linker
+
+### Removed
+- `thor` runtime dependency (was declared but never used)
+
 ## [0.1.0] - 2026-06-16
 
 - Initial release

data/README.md

@@ -1,7 +1,18 @@
 # 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.
+<p align="center">
+<table style="width:38%;margin:0 auto;" border="0" cellpadding="8">
+  <tr>
+    <td width="40%"><img src="docs/assets/images/gem-skill.jpg" alt="gem-skill logo" width="100%"></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>
+      <strong><a href="https://madbomber.github.io/gem-skill">Full documentation →</a></strong>
+    </td>
+  </tr>
+</table>
+</p>
 
 ## The problem it solves
 
@@ -110,6 +121,9 @@ gem skill purge chunker-ruby 1.2.3
 
 # Remove all cached versions of a gem
 gem skill purge chunker-ruby --all
+
+# Print the installed version
+gem skill --version
 ```
 
 If a gem isn't installed locally, `gem skill install` will install it first.
@@ -151,6 +165,9 @@ bundle skill list
 # Options available on install and refresh
 bundle skill install --force
 bundle skill install --model claude-haiku-4-5
+
+# Print the installed version
+bundle skill --version
 ```
 
 ## What gets generated

data/docs/cache.md

@@ -0,0 +1,108 @@
+# Cache
+
+## Location
+
+The global skill cache lives at `~/.gem/skills` by default. Override with:
+
+```bash
+export GEMSKILL_DIR="/path/to/your/cache"
+```
+
+## Structure
+
+```
+~/.gem/skills/
+├── debug_me/
+│   └── 1.1.0/
+│       ├── SKILL.md
+│       └── metadata.json
+├── faraday/
+│   ├── 2.12.0/
+│   │   ├── SKILL.md
+│   │   └── metadata.json
+│   └── 2.14.3/
+│       ├── SKILL.md
+│       └── metadata.json
+└── zeitwerk/
+    └── 2.8.2/
+        ├── SKILL.md
+        └── metadata.json
+```
+
+Each gem can have multiple cached versions. They coexist without conflict — two
+projects pinning different versions of the same gem each get the correct skill.
+
+## Files
+
+### `SKILL.md`
+
+The generated skill file. Contains structured documentation tailored for
+Claude Code. See [Skill Files](skill-files.md) for the format.
+
+### `metadata.json`
+
+Stores provenance information:
+
+```json
+{
+  "gem_name": "faraday",
+  "version": "2.14.3",
+  "model": "claude-sonnet-4-6",
+  "generated_at": "2026-06-17T10:23:45Z",
+  "sources": ["readme", "changelog", "rubygems"]
+}
+```
+
+## Cache commands
+
+```bash
+# List everything in the cache
+gem skill list
+
+# Remove a specific version
+gem skill purge faraday 2.12.0
+
+# Remove all versions of a gem
+gem skill purge faraday --all
+```
+
+## Sharing the cache
+
+You can share a skill cache across machines by pointing `GEMSKILL_DIR` at a
+shared location:
+
+```bash
+# Team-shared network drive
+export GEMSKILL_DIR="/Volumes/team-shared/gem-skills"
+```
+
+All machines with the same `GEMSKILL_DIR` will read and write to the same cache.
+Skills generated on one machine are immediately available on others.
+
+## Project symlinks
+
+Projects don't store skills locally — they hold symlinks into the global cache:
+
+```
+your-project/.claude/skills/
+├── faraday  →  ~/.gem/skills/faraday/2.14.3/
+└── zeitwerk →  ~/.gem/skills/zeitwerk/2.8.2/
+```
+
+Each symlink points to the **version directory**. Claude Code reads `SKILL.md`
+from inside the linked directory.
+
+`bundle skill refresh` updates symlinks when versions change after `bundle update`.
+`bundle skill list` shows the status of all current symlinks.
+
+## Regenerating skills
+
+Skills do not auto-expire. Regenerate explicitly when you want updated content:
+
+```bash
+# Regenerate one gem
+gem skill install faraday --force
+
+# Regenerate all project gems with a better model
+bundle skill install --force --model claude-opus-4-8
+```

data/docs/commands/bundle-skill.md

@@ -0,0 +1,147 @@
+# bundle skill
+
+The `bundle skill` command is project-aware: it reads `Gemfile.lock` to
+determine which gems and versions are in use, generates skills for all of them,
+and links the results into `.claude/skills/` in the project root.
+
+## Global options
+
+These flags work without a subcommand:
+
+```bash
+bundle skill --version    # print installed version and exit
+bundle skill -v           # same
+```
+
+## Prerequisites
+
+Run once after installing gem-skill:
+
+```bash
+gem skill setup
+```
+
+Or add to the project `Gemfile`:
+
+```ruby
+plugin "gem-skill"
+```
+
+## Subcommands
+
+### `bundle skill install`
+
+Generate and link skills for all direct dependencies in `Gemfile.lock`.
+
+```bash
+bundle skill install [OPTIONS]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Regenerate even if skills are already cached |
+| `--model MODEL` | LLM model to use (overrides `GEMSKILL_MODEL`) |
+| `--version`, `-v` | Print the installed gem-skill version and exit |
+
+**Example:**
+
+```bash
+cd your-project
+bundle skill install
+```
+
+**What it processes:**
+
+- All gems listed in the `DEPENDENCIES` section of `Gemfile.lock`
+- Runtime dependencies declared in any `gemspec` referenced by the `Gemfile` (via `gemspec` directive)
+
+All gems are processed concurrently:
+
+```
+⠋ Installing skills (claude-sonnet-4-6)
+  ✓ rake 13.4.2 already cached
+  ✓ zeitwerk 2.8.2 done
+  ✓ ruby_llm 1.16.0 done
+```
+
+After completion, each skill is symlinked into `.claude/skills/`:
+
+```
+your-project/.claude/skills/
+├── rake     →  ~/.gem/skills/rake/13.4.2/
+├── ruby_llm →  ~/.gem/skills/ruby_llm/1.16.0/
+└── zeitwerk →  ~/.gem/skills/zeitwerk/2.8.2/
+```
+
+Claude Code automatically reads `SKILL.md` from each linked directory.
+
+---
+
+### `bundle skill refresh`
+
+Re-sync `.claude/skills/` after `bundle update`.
+
+```bash
+bundle skill refresh [OPTIONS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Regenerate all skills, even those already at the correct version |
+| `--model MODEL` | LLM model to use |
+
+`refresh` skips gems that are already linked at the correct version (shows
+`up to date`), regenerates gems whose version changed, and removes dead symlinks
+for gems no longer in `Gemfile.lock`.
+
+**Typical workflow:**
+
+```bash
+bundle update
+bundle skill refresh
+```
+
+---
+
+### `bundle skill list`
+
+Show all skills currently linked in this project.
+
+```bash
+bundle skill list
+```
+
+**Example output:**
+
+```
+Skills linked in .claude/skills/  (3 ok):
+
+  [ok    ]  rake                           13.4.2
+  [ok    ]  ruby_llm                       1.16.0
+  [ok    ]  zeitwerk                       2.8.2
+```
+
+A `BROKEN` status means the symlink target no longer exists in the cache —
+run `bundle skill install` to regenerate.
+
+---
+
+## Typical project workflow
+
+```bash
+# First time setup
+bundle install
+bundle skill install
+
+# After bundle update
+bundle update
+bundle skill refresh
+
+# Check what's linked
+bundle skill list
+
+# Force full regeneration (e.g. after model upgrade)
+bundle skill install --force --model claude-opus-4-8
+```

data/docs/commands/gem-skill.md

@@ -0,0 +1,135 @@
+# 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 |
+| `--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
+```
+
+If a gem is not installed locally, gem-skill will install it automatically
+before generating the skill.
+
+---
+
+### `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`
+
+Register gem-skill as a Bundler plugin (run once after `gem install gem-skill`).
+
+```bash
+gem skill setup
+```
+
+This enables `bundle skill` in any project on the machine. See
+[Installation](../installation.md) for details.
+
+---
+
+### `gem skill list`
+
+Show all skills currently in the global cache.
+
+```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.
+```
+
+---
+
+### `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,75 @@
+# 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_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,160 @@
+# 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>/
+      ↓
+  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)
+```
+
+`Cache::ROOT` is set once at load time from `GEMSKILL_DIR` (default: `~/.gem/skills`).
+
+### Linker
+
+`lib/gem/skill/linker.rb`
+
+Creates and manages directory symlinks in `.claude/skills/` inside a project:
+
+```
+.claude/skills/<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.
+
+`Linker.prune_dead_links` removes any symlink whose target no longer exists
+in the cache (e.g. after `gem skill purge`).
+
+### 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:)
+# Returns nil on success, error message string on failure
+```
+
+Returns the error message rather than raising, so the caller (the concurrent
+fiber) can record it without killing other in-flight fibers.
+
+---
+
+## 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,69 @@
+<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 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>
+      <strong><a href="https://madbomber.github.io/gem-skill">Full documentation →</a></strong>
+    </td>
+  </tr>
+</table>
+</p>
+
+## 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.
+
+## 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
+        ↓
+   Claude Code reads SKILL.md automatically
+```
+
+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` and `GEMSKILL_MODEL` environment variables

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.

data/docs/skill-files.md

@@ -0,0 +1,78 @@
+# 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/`.
+
+## Format
+
+Every generated skill starts with a top-level heading identifying the gem and
+version, then covers seven sections:
+
+```markdown
+# faraday v2.14.3
+
+## Overview
+What the gem does and when to reach for it.
+
+## Installation
+Exact Gemfile/gemspec lines and any required post-install steps.
+
+## Core API
+Key classes, methods, and options with real method signatures and return values.
+
+## Common Patterns
+The 3–5 most frequent real-world usage patterns with working code examples.
+
+## Gotchas & Edge Cases
+Surprising defaults, version-specific behavior, thread safety, encoding issues.
+
+## Configuration
+Initializer patterns, environment variables, defaults worth knowing.
+
+## Testing
+How to test code that uses this gem: mocks, fakes, fixtures, VCR patterns.
+```
+
+## What Claude does with it
+
+When Claude Code opens a project containing `.claude/skills/`, it reads every
+`SKILL.md` it finds. This means:
+
+- Claude 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
+
+## Sources used to generate
+
+The LLM is given up to three sources per gem (in priority order):
+
+1. **Local README + CHANGELOG** — from the gem's install directory
+2. **RubyGems API** — summary, dependencies, source URI
+3. **GitHub raw README** — fetched when not installed locally
+
+Content is synthesized, not copied verbatim. The model is instructed to write
+as a knowledgeable colleague, not a marketing document.
+
+## Quality and regeneration
+
+Skill quality depends on the documentation available for the gem and the model
+used. For gems with poor upstream documentation, results will reflect that.
+
+To improve a skill:
+
+```bash
+# Use a more capable model
+gem skill install my_gem --force --model claude-opus-4-8
+
+# Or set it as the default
+export GEMSKILL_MODEL="claude-opus-4-8"
+gem skill install my_gem --force
+```
+
+## Version specificity
+
+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.

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

@@ -17,6 +17,11 @@ module Gem::Skill
       opts, rest = parse_options(args)
       subcmd = rest.shift
 
+      if opts[:version]
+        puts Gem::Skill::VERSION
+        return
+      end
+
       case subcmd
       when "install" then install(opts)
       when "refresh" then refresh(opts)
@@ -146,6 +151,7 @@ module Gem::Skill
       args.each do |arg|
         case arg
         when "--force"           then opts[:force] = true
+        when "--version", "-v"   then opts[:version] = true
         when /\A--model(?:=(.+))?\z/
           opts[:model] = $1 || args[args.index(arg) + 1]
         else
@@ -170,6 +176,7 @@ module Gem::Skill
         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
       USAGE
     end
     private_class_method :usage

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

@@ -18,6 +18,7 @@ class Gem::Commands::SkillCommand < Gem::Command
     add_option("-m", "--model MODEL",   "LLM model to use (default: #{Gem::Skill::Generator::DEFAULT_MODEL})") do |model, o|
       o[:model] = model
     end
+    add_option("-v", "--version",       "Print gem-skill version and exit") { |_, o| o[:version] = true }
   end
 
   def arguments
@@ -44,6 +45,10 @@ class Gem::Commands::SkillCommand < Gem::Command
   end
 
   def execute
+    if options[:version]
+      say Gem::Skill::VERSION
+      return
+    end
     Gem::Skill.configure_llm!
     subcmd = options[:args].shift
     case subcmd

data/lib/gem/skill/version.rb

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

data/mkdocs.yml

@@ -0,0 +1,115 @@
+site_name: gem-skill
+site_description: Generate and manage Claude Code AI skills from Ruby gem documentation
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/gem-skill
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+repo_name: madbomber/gem-skill
+repo_url: https://github.com/madbomber/gem-skill
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: gem-skill
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/gem-skill
+      name: gem-skill on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/gem-skill
+      name: gem-skill on RubyGems
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Configuration: configuration.md
+  - Commands:
+    - gem skill: commands/gem-skill.md
+    - bundle skill: commands/bundle-skill.md
+  - How It Works: how-it-works.md
+  - Cache: cache.md
+  - Skill Files: skill-files.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-skill
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -63,10 +63,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/assets/images/gem-skill.jpg
+- docs/cache.md
+- docs/commands/bundle-skill.md
+- docs/commands/gem-skill.md
+- docs/configuration.md
+- docs/how-it-works.md
+- docs/index.md
+- docs/installation.md
+- docs/skill-files.md
 - lib/gem/skill.rb
 - lib/gem/skill/cache.rb
 - lib/gem/skill/cli/bundle_command.rb
@@ -78,6 +88,7 @@ files:
 - lib/gem/skill/runner.rb
 - lib/gem/skill/version.rb
 - lib/rubygems_plugin.rb
+- mkdocs.yml
 - plugins.rb
 - scripts/e2e_test
 - sig/gem/skill.rbs
@@ -87,7 +98,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/madbomber/gem-skill
   source_code_uri: https://github.com/madbomber/gem-skill
-  changelog_uri: https://github.com/madbomber/gem-skill/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/madbomber/gem-skill/blob/main/CHANGELOG.md
 post_install_message: |
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     gem-skill installed!