gem-skill 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e537a3925c494c903dc9dd105d6a975d55d5fe55f963847cca3c363ce26120d6
-  data.tar.gz: 7f4fd4cff99d062ab50bf73b733aeddca903f23ffb657ccc7cc7616dcd7e2fe6
+  metadata.gz: c425b88d925bd6ef993c1ea04581ffd0e457bebc9137cccf68cf3aacd6e00fde
+  data.tar.gz: ba39b45df96bc6f76c6b2ffa950a3a2cafbba4b7c0b2bfd94ecbd9cd4b38cd06
 SHA512:
-  metadata.gz: 2d74ee4cdbf3b827984574580985426ec708e7dfd901f2ddb99f03268afdcc96a2ab9f8962781549c053e587f1ecbd4f0d5cab06189adb24603af475083ab54e
-  data.tar.gz: e012f26a513a5516d606c6664c1ccd470ed910bd57190850e96daf1bc88e686e00dfbfc2b6f9bd8a467bdde6d5ca938b3084697ca27d2a956043b05e9d8dac37
+  metadata.gz: 7b4558c9312730d8d7218951591985d868db5bea5f4282f52702ad01feb5ec381c3cfe5af56cb9b50cfa5c45b58e5dbf54bbefee99d6c36d033598383977c35e
+  data.tar.gz: 7464f9cd590e6899ad7a4d2b5a464c42c054ce4287502625349f5cb438e3c66e53e4b56ab7291f8730404f9f9f9f4636a7412cf736a40f40e6dce9a94a5ff048

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,60 @@
+# Changelog
+
+All notable changes to gem-skill are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
 ## [Unreleased]
 
+### Added
+- Bundled `ruby-gem-skills` "router" skill (shipped at the gem root) that teaches assistants how to find cached gem skills in `~/.gem/skills` — a directory neither Claude Code nor Codex scans by default. `gem skill setup` now also copies this skill into each detected assistant's default root (`~/.claude/skills`, `~/.codex/skills`, `~/.agents/skills`), creating none that don't already exist. `Gem::Skill::ROUTER_SKILL_NAME` / `ROUTER_SKILL_DIR` locate the bundled template.
+
+## [0.2.0] - 2026-06-19
+
+### Added
+- `--verify` flag for `gem skill install` and `bundle skill install`/`refresh` — runs a second LLM pass that checks the generated skill's code against the gem's **actual source code** (the source of truth) and corrects mismatched method signatures, default argument values, visibility, return values, and behavioral claims. READMEs and docstrings are frequently stale; this catches it.
+- `gem skill verify GEM_NAME [GEM_NAME ...]` subcommand — verify an already-cached skill in place (never generates; errors if the gem isn't installed or the skill isn't cached).
+- `gem skill list` flags verified versions with a green checkmark (`✓`); unverified versions show no mark. The checkmark is colored only for interactive terminals.
+- `GEMSKILL_PROJECT_DIR` env var (default `.claude/skills`) — controls the project-relative directory `bundle skill` writes symlinks into. Codex users can set it to `.agents` or `.codex` to link skills into a Codex project root.
+- `Gem::Skill::Verifier` — the verification pass. Whether the skill changed is decided by a deterministic diff (not the model's self-report), so the result is trustworthy.
+- `Gem::Skill::Frontmatter` — deterministic, idempotent frontmatter builder shared by the generator and verifier, so a skill always carries valid frontmatter even if the model omits it.
+- `Fetcher#source_code` — concatenates the gem's `lib/**/*.rb` (size-capped) as the ground truth the verifier checks against.
+- `Cache.read_metadata`, `Cache.write_skill`, `Cache.merge_metadata` — support verifying/rewriting a cached skill without clobbering `generated_at`/`model`/`sources`.
+- Verified skills gain a `verification` block in `metadata.json` recording that the skill was checked against the gem's actual source: `verified`, `verified_at`, `model`, and `fixed` (whether the check changed anything). When no installed source is available to check against, it records `verified: false` with a `skipped_reason`.
+- Exit status `2` (`Gem::Skill::EXIT_VERIFY_FIXED`) when `--verify` found and corrected problems, so CI can detect README/source drift. `0` = clean, `1` = error.
+
+### Changed
+- `Runner.install_skill` now accepts `verify:` and returns a `Runner::Result` (`error`, `verify_fixed`) instead of a nil/error-string.
+- Documentation reworded to be assistant-neutral: `SKILL.md` is a shared format read by Claude Code, OpenAI Codex, and other AI coding assistants. Added guidance for pointing non-Claude assistants (e.g. Codex's `~/.codex/skills`, the vendor-neutral `~/.agents/skills`) at the shared cache. `bundle skill` still links into `.claude/skills/` (Claude Code's convention).
+
+### Fixed
+- Generated `SKILL.md` files now include the required YAML frontmatter (`name` + `description`). Without it, the files were never registered/triggered as skills by Claude Code or OpenAI Codex — they were just markdown in a skills folder. `name` is the gem name normalized to hyphen-case (e.g. `ruby_llm` → `ruby-llm`); `description` is a trigger-oriented one-liner derived from the Overview (sanitized for both assistants: single line, no angle brackets). Verified against Claude Code's skill validator and OpenAI's Codex skill spec.
+
+### Note
+- Skills cached before this change lack frontmatter; regenerate them with `gem skill install GEM --force` (or `bundle skill refresh --force`) to add it.
+
+## [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,18 +1,31 @@
 # 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 <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 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.
 
 ## How the cache is laid out
 
@@ -27,7 +40,8 @@ ingestion work.
         └── metadata.json
 ```
 
-Each project's `.claude/skills/` holds symlinks that point into this cache:
+Each project's `.claude/skills/` directory (Claude Code's convention) holds
+symlinks that point into this cache:
 
 ```
 your-app/.claude/skills/
@@ -37,6 +51,29 @@ your-app/.claude/skills/
 Two projects that pin different versions of the same gem each get the right
 skill; the underlying content is generated once and shared.
 
+### Using the cache with other assistants
+
+The `~/.gem/skills` cache is assistant-neutral — `SKILL.md` is a shared format.
+By default `bundle skill` links skills into `.claude/skills/`, which Claude Code
+reads automatically. Other assistants discover skills in their own roots; for
+example, OpenAI Codex looks in `~/.codex/skills` and the vendor-neutral
+`~/.agents/skills` (and project-local `.agents/` / `.codex/`).
+
+To make `bundle skill` link into a different project directory, set
+`GEMSKILL_PROJECT_DIR`:
+
+```bash
+export GEMSKILL_PROJECT_DIR=".agents"   # Codex project root
+bundle skill install                    # symlinks now land in .agents/
+```
+
+> **Availability ≠ activation.** Claude Code treats every `SKILL.md` under
+> `.claude/skills/` as active automatically. Some assistants (e.g. Codex) only
+> activate a skill if it's in the session's available-skills list or you point
+> at it explicitly — so linking makes a skill *available*, not necessarily
+> *active*. See
+> [Using with other assistants](https://madbomber.github.io/gem-skill/skill-files/#using-with-other-assistants).
+
 ## Installation
 
 ```bash
@@ -71,7 +108,8 @@ Two environment variables control `gem-skill`'s behaviour:
 
 | Variable | Default | Description |
 |---|---|---|
-| `GEMSKILL_DIR` | `~/.gem/skills` | Root directory for the skill cache |
+| `GEMSKILL_DIR` | `~/.gem/skills` | Root directory for the global skill cache |
+| `GEMSKILL_PROJECT_DIR` | `.claude/skills` | Project-relative directory where `bundle skill` writes symlinks |
 | `GEMSKILL_MODEL` | `gpt-5.5` | LLM model used when generating skills |
 
 ```bash
@@ -80,6 +118,9 @@ export GEMSKILL_DIR="/Volumes/shared/gem-skills"
 
 # Switch the default model to Claude
 export GEMSKILL_MODEL="claude-sonnet-4-6"
+
+# Codex users: link skills into a Codex project root instead of .claude/skills
+export GEMSKILL_PROJECT_DIR=".agents"   # or ".codex"
 ```
 
 The `--model` flag on any command overrides `GEMSKILL_MODEL` for that
@@ -102,7 +143,10 @@ gem skill install chunker-ruby --force
 # Use a different model
 gem skill install chunker-ruby --model claude-haiku-4-5
 
-# Show everything in the cache
+# Verify an already-cached skill against the gem's source (fixes mismatches)
+gem skill verify chunker-ruby
+
+# Show everything in the cache (verified versions are flagged with a ✓)
 gem skill list
 
 # Remove a specific cached version
@@ -110,19 +154,30 @@ 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:
+Run once after `gem install gem-skill`:
 
 ```bash
 gem skill setup
 ```
 
-This registers gem-skill as a Bundler plugin so `bundle skill` works in every project.
+This does two things:
+
+1. Registers gem-skill as a Bundler plugin so `bundle skill` works in every project.
+2. Installs the **`ruby-gem-skills`** router skill into the default skill root of
+   each detected assistant (`~/.claude/skills`, `~/.codex/skills`,
+   `~/.agents/skills`). Cached gem skills live in `~/.gem/skills`, which
+   assistants don't scan by default — this small always-on skill teaches Claude
+   Code and Codex how to find and load a gem's `SKILL.md` on demand. Re-run
+   `gem skill setup` after upgrading gem-skill to refresh it.
 
 ### `gem install --with-skill`
 
@@ -151,6 +206,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,185 @@
+# 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 for AI coding
+assistants (Claude Code, OpenAI Codex, and others). 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"]
+}
+```
+
+When a skill is generated with `--verify`, a `verification` block is added that
+records that the gem's actual source code was consulted, exactly which files were
+examined, and the issue-ready corrections that resulted:
+
+```json
+{
+  "gem_name": "tty-spinner",
+  "version": "0.9.3",
+  "model": "gpt-5.5",
+  "generated_at": "2026-06-17T10:23:45Z",
+  "sources": ["metadata", "readme", "changelog"],
+  "verification": {
+    "verified": true,
+    "verified_at": "2026-06-19T14:02:11Z",
+    "model": "gpt-5.5",
+    "used_source_code": true,
+    "source": {
+      "files": ["lib/tty/spinner.rb", "lib/tty/spinner/multi.rb", "lib/tty/spinner/formats.rb"],
+      "file_count": 3,
+      "chars": 26452,
+      "truncated": false
+    },
+    "fixed": true,
+    "change_count": 1,
+    "changes": [
+      {
+        "category": "default_value",
+        "symbol": "TTY::Spinner#stop",
+        "skill_section": "Core API",
+        "source_location": "lib/tty/spinner.rb:387",
+        "was": "stop(message = nil)",
+        "now": "stop(message = '')",
+        "detail": "Default argument is an empty string, not nil; the README implied nil.",
+        "source_evidence": "def stop(stop_message = '')"
+      }
+    ]
+  }
+}
+```
+
+Each entry in `changes` is detailed enough to open a documentation issue against
+the gem: it names the affected symbol, where the skill was wrong, what it claimed
+versus the truth, and the source snippet that proves it. When source isn't
+available locally, `verification` instead records `"verified": false`,
+`"used_source_code": false`, and a `"skipped_reason"`.
+
+## 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.
+`bundle skill` writes these into the directory named by
+[`GEMSKILL_PROJECT_DIR`](configuration.md#gemskill_project_dir), which defaults
+to `.claude/skills/` (Claude Code's convention):
+
+```
+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**, and the assistant 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.
+
+### Other assistants
+
+`SKILL.md` is a shared format and the cache is assistant-neutral. Assistants
+other than Claude Code look in their own skill roots — for example, OpenAI Codex
+uses `~/.codex/skills` and the vendor-neutral `~/.agents/skills` globally, or
+project-local `.agents/` / `.codex/`.
+
+For project links, set `GEMSKILL_PROJECT_DIR` so `bundle skill` writes straight
+into the right directory:
+
+```bash
+export GEMSKILL_PROJECT_DIR=".agents"
+bundle skill install
+```
+
+For a global, cross-project link, symlink a cached version directory into the
+assistant's global root:
+
+```bash
+ln -s ~/.gem/skills/faraday/2.14.3 ~/.agents/skills/faraday
+```
+
+Note that linking only makes a skill *available*; some assistants (e.g. Codex)
+won't *activate* it unless it's in the session's available-skills list or you
+reference it explicitly. See
+[Using with other assistants](skill-files.md#using-with-other-assistants).
+
+## 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,154 @@
+# 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/` (Claude Code's skill directory) in
+the project root. The generated `SKILL.md` files are a shared format that other
+assistants read too — see [Using with other assistants](../skill-files.md#using-with-other-assistants).
+
+## 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 |
+| `--verify` | Verify generated skills against each gem's source and fix mismatches (exit `2` if any fixes applied) |
+| `--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 the project skill directory
+(`.claude/skills/` by default; set
+[`GEMSKILL_PROJECT_DIR`](../configuration.md#gemskill_project_dir) to change it,
+e.g. `.agents` for Codex):
+
+```
+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/
+```
+
+The assistant automatically reads `SKILL.md` from each linked directory (Claude
+Code reads `.claude/skills/`; other assistants use their own roots).
+
+---
+
+### `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
+```