gem-skill 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e549225e7af0a6d96b302304225a274d5f5aa6074e8546c64034b3aba056d675
-  data.tar.gz: f2791cd10d4e1483763a890bb864cb5169ab6fc1c5239ae697e104d70ec1d898
+  metadata.gz: 81806de91a59a0b2f9144dedebda65f568d61629064f6182f753229fced49583
+  data.tar.gz: 444441e8f081192ceb5b6201bc8c2c9428b243729df896a4405db562d435ad7d
 SHA512:
-  metadata.gz: 7a75fec793180d52a07e7eb42c84d79eca1ba720aec44c33ec13f6783678ec96770f0bbe0ce4789ecdfdafc6c7df882c392fcea9e48f55fb99d47877dff0b7b6
-  data.tar.gz: d605f135da72c0bcdf5cb5f85c42b1f40bc5d13f46330264fd420401faa43dc67503949592c3dd15cfba0b62115b8a14a97d1850072a32309ad10a1833cbfb9c
+  metadata.gz: 39ed27eb70e0036d097b01576a78a20a13ed337ddf05abfc5f5a63a0279b65c79d327907cc70fa96d132d7e72ae3d47ce5cdb5a0bb50e30cbfbb441ce428611d
+  data.tar.gz: 6c0fd5f43ffeac14efe923f9b1742ab469d3e08c50f86dd521c38d45d003800fe45a8447dcb682df0014419d1421d1b2f20eb326d3b6c7f2d3b1d7d0210974bb

data/.envrc

@@ -0,0 +1 @@
+export RR=`pwd`

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
 
@@ -31,7 +42,7 @@ Each project's `.claude/skills/` holds symlinks that point into this cache:
 
 ```
 your-app/.claude/skills/
-└── chunker-ruby.md  →  ~/.gem/skills/chunker-ruby/1.2.3/SKILL.md
+└── chunker-ruby/  →  ~/.gem/skills/chunker-ruby/1.2.3/
 ```
 
 Two projects that pin different versions of the same gem each get the right
@@ -41,17 +52,14 @@ skill; the underlying content is generated once and shared.
 
 ```bash
 gem install gem-skill
+gem skill setup
 ```
 
-This gives you the `gem skill` subcommand.
+`gem install` gives you the `gem skill` subcommand.
+`gem skill setup` registers gem-skill as a Bundler plugin, enabling `bundle skill` in any project.
 
-For `bundle skill` support (project-aware, reads `Gemfile.lock`), also run:
-
-```bash
-bundle plugin install gem-skill
-```
-
-or add it to your `Gemfile`:
+You only need to run `gem skill setup` once per machine. Alternatively, you can
+add the plugin directly to a project's `Gemfile`:
 
 ```ruby
 plugin "gem-skill"
@@ -113,10 +121,23 @@ 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.
 
+### `gem skill setup`
+
+Run once after `gem install gem-skill` to enable `bundle skill` globally:
+
+```bash
+gem skill setup
+```
+
+This registers gem-skill as a Bundler plugin so `bundle skill` works in every project.
+
 ### `gem install --with-skill`
 
 Generate skills for gems as you install them:
@@ -144,10 +165,10 @@ bundle skill list
 # Options available on install and refresh
 bundle skill install --force
 bundle skill install --model claude-haiku-4-5
-```
 
-The `install` and `refresh` commands stream LLM output as it is generated, so
-you see progress rather than a silent wait.
+# 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
+```