gem-skill 0.1.3 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81806de91a59a0b2f9144dedebda65f568d61629064f6182f753229fced49583
-  data.tar.gz: 444441e8f081192ceb5b6201bc8c2c9428b243729df896a4405db562d435ad7d
+  metadata.gz: 3cc3ecc8f770110cc9f8605e149ff2d78c44a388a76add0046c595b01ecbf882
+  data.tar.gz: 21ac18bb7bcc6de52ac9987561da30821be843cca322f0b45b8e04ed1a9af3a1
 SHA512:
-  metadata.gz: 39ed27eb70e0036d097b01576a78a20a13ed337ddf05abfc5f5a63a0279b65c79d327907cc70fa96d132d7e72ae3d47ce5cdb5a0bb50e30cbfbb441ce428611d
-  data.tar.gz: 6c0fd5f43ffeac14efe923f9b1742ab469d3e08c50f86dd521c38d45d003800fe45a8447dcb682df0014419d1421d1b2f20eb326d3b6c7f2d3b1d7d0210974bb
+  metadata.gz: 4f6fecb42f713486c2abddd7041c6a7294ed4e0cf07affd97457739fe0bd59c8fb080ee80b672817e9a182ff8359896235f2c2c56f16a54eca9528290a3fd07d
+  data.tar.gz: acd79346e7b20fcead6bfff93f4f21aa58f81ac203b3fec5616f2f5f55b6d4337c0919cd01a1790159c7e256ec579c14d8e25c2aaa4cd5d85479fea826c4e3fa

data/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.
+- `GEMSKIL_MAX_TOKENS` environment variable (default `32767`) — caps the number of output tokens the LLM may generate per skill file. Raise this if generated `SKILL.md` files are being truncated.
+- `--max-tokens TOKENS` CLI flag on `gem skill install`, `bundle skill install`, and `bundle skill refresh` — overrides `GEMSKIL_MAX_TOKENS` for a single invocation. Provider-correct parameter name is selected automatically (`max_completion_tokens` for OpenAI models, `max_tokens` for all others).
+- `GEMSKILL_TEMPERATURE` environment variable (default `0.2`) — sampling temperature for generation. Lower values produce more consistent, less variable output, appropriate for factual reference docs. Applied only to models that support a temperature parameter; reasoning models (e.g. `gpt-5.5`) report `temperature: false` in their RubyLLM metadata and the value is silently skipped for them.
+- `--temperature TEMP` CLI flag on `gem skill install` — overrides `GEMSKILL_TEMPERATURE` for a single invocation.
+
+### Fixed
+- `strip_wrapper_fence` no longer deletes the closing ``` of a skill that legitimately ends with a code block. The trailing wrapper fence is now stripped only when a matching opening wrapper fence (```` ```markdown ```` / ```` ``` ```` at the very start) was present. Previously the final ``` was removed unconditionally, leaving the last code block open at end-of-file — which looked like the LLM truncating its output but was entirely a post-processing bug. Regenerate affected skills with `gem skill install GEM --force`.
+
+### Changed
+- `Generator::MAX_TOKENS` constant reads from `GEMSKIL_MAX_TOKENS` and is passed via `with_params` to every `RubyLLM.chat` call, covering both streaming and non-streaming paths.
+- `Generator#initialize` now accepts `max_tokens:` and `temperature:` keywords so callers can override the token cap and sampling temperature per-instance without touching the environment.
+- `Generator` sets `with_temperature` only when the model's RubyLLM metadata does not mark temperature unsupported, avoiding API errors on reasoning models.
+- `Runner.install_skill` accepts and forwards `max_tokens:` and `temperature:` to `Generator.new`.
+- `README.md` Configuration section now lists all environment variables (gem-skill-specific and provider API keys) in a single reference table.
+- `docs/configuration.md` documents the new `GEMSKIL_MAX_TOKENS` and `GEMSKILL_TEMPERATURE` variables alongside the existing `GEMSKILL_MODEL` entry.
+- `docs/commands/gem-skill.md` and `docs/commands/bundle-skill.md` option tables updated with `--max-tokens` and `--temperature`.
+
+## [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

data/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem does
+
+`gem-skill` generates `SKILL.md` files from Ruby gem documentation using an LLM (via RubyLLM), caches them globally at `~/.gem/skills/<gem_name>/<version>/SKILL.md`, and symlinks them into projects as directory links: `.claude/skills/<gem_name>/ → ~/.gem/skills/<gem_name>/<version>/`. It registers two CLI entry points: `gem skill` (global cache management) and `bundle skill` (project-aware, driven by `Gemfile.lock`), plus a `gem install --with-skill` flag.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test                                 # run all tests (default task)
+ruby -Ilib:test test/gem/skill/cache_test.rb          # run a single test file
+bundle exec ruby scripts/e2e_test [GEM VERSION MODEL] # live LLM end-to-end test (needs a provider API key)
+bin/dev_install                                       # point Bundler's plugin indexes at this source tree so
+                                                      # `bundle skill` runs local code (no build/release needed)
+bin/dev_install --reset                               # restore to the released gem install
+```
+
+Docs site is MkDocs (`mkdocs.yml`, `docs/`), deployed by `.github/workflows/deploy-github-pages.yml`.
+
+## Architecture
+
+### Entry points
+
+- `lib/rubygems_plugin.rb` — loaded automatically by RubyGems; registers `gem skill` (`Gem::Commands::SkillCommand`) AND prepends `--with-skill` onto `gem install`, queuing installed gems and generating their skills in threads via a `Gem.post_install` hook + `at_exit`
+- `plugins.rb` — Bundler plugin entry point; registers `bundle skill` via `Gem::Skill::BundlerPlugin` → `Gem::Skill::BundlerCommand`
+
+### Core pipeline (in call order)
+
+1. **`Lockfile`** (`lib/gem/skill/lockfile.rb`) — parses `Gemfile.lock`; extracts direct-dependency name→version pairs by cross-referencing the `DEPENDENCIES` and `specs:` sections
+2. **`Fetcher`** (`lib/gem/skill/fetcher.rb`) — collects raw docs for a single gem/version in priority order: (1) local `Gem::Specification` gem_dir, (2) RubyGems API JSON, (3) GitHub raw README. Returns `{metadata:, readme:, changelog:}` with only populated keys
+3. **`Generator`** (`lib/gem/skill/generator.rb`) — formats fetched sources into a prompt, calls RubyLLM, strips any wrapping code fence, runs `Frontmatter.build`, stores result via `Cache`. Supports streaming via block
+4. **`Frontmatter`** (`lib/gem/skill/frontmatter.rb`) — deterministically (no LLM) builds/replaces the YAML frontmatter (`name` + `description`) that makes a SKILL.md discoverable by both Claude Code and Codex; enforces both assistants' name/description constraints
+5. **`Cache`** (`lib/gem/skill/cache.rb`) — reads/writes `~/.gem/skills/<name>/<version>/SKILL.md` and `metadata.json`; `merge_metadata` string-normalizes keys
+6. **`Verifier`** (`lib/gem/skill/verifier.rb`) — optional second LLM pass (`--verify` or `gem skill verify`) that re-checks a generated skill against the gem's actual installed source and corrects wrong signatures/claims. `changed?` is decided by a deterministic content diff, never the model's self-report; unverifiable (no local source) is recorded in metadata, not an error
+7. **`Linker`** (`lib/gem/skill/linker.rb`) — creates/updates directory symlinks in the project skills dir pointing into the cache; `prune_dead_links` removes broken symlinks after a refresh
+
+**`Runner`** (`lib/gem/skill/runner.rb`) is the shared generate+cache+link+verify orchestration used by both CLI commands; it returns a `Runner::Result` (`Data.define`) and drives a TTY spinner passed in by the caller.
+
+### CLI layer
+
+- `lib/gem/skill/cli/gem_command.rb` — `Gem::Commands::SkillCommand`; subcommands: `install`, `verify`, `list`, `purge`, `setup`. Multi-gem installs run concurrently with the `async` gem (`Async::Barrier`). `setup` registers the Bundler plugin and copies the bundled router skill (`ruby-gem-skills/SKILL.md` at repo root) into each detected assistant's global skill root
+- `lib/gem/skill/cli/bundle_command.rb` — `Gem::Skill::BundlerCommand`; subcommands: `install`, `refresh`, `list`. `install` = generate + link all direct lockfile gems; `refresh` = skip gems already linked at the correct version. Parses its own flags (`--force`, `--verify`, `--model`, `--max-tokens`, `--temperature`, `--version`)
+
+### LLM configuration
+
+`Gem::Skill.configure_llm!` reads provider API keys from environment variables (see `ENV_KEY_MAP` in `lib/gem/skill.rb`) and configures RubyLLM. Called automatically by both CLI entry points. No-op if already configured.
+
+## Key constants & environment variables
+
+- `Cache::ROOT` = `~/.gem/skills` (override: `GEMSKILL_DIR`)
+- `Linker::DEFAULT_PROJECT_DIR` = `.claude/skills` (override: `GEMSKILL_PROJECT_DIR`, re-read on every call — e.g. `.agents` for Codex)
+- `Generator::DEFAULT_MODEL` = `"gpt-5.5"` (override: `GEMSKILL_MODEL` or `--model`)
+- `Generator::MAX_TOKENS` = 32,767 (override: `GEMSKIL_MAX_TOKENS` — note the single-L spelling — or `--max-tokens`)
+- `Generator::DEFAULT_TEMPERATURE` = 0.2 (override: `GEMSKILL_TEMPERATURE` or `--temperature`; skipped for models that reject temperature)
+- `Generator::MAX_SOURCE_CHARS` = 60,000 (README truncation guard)
+- `Gem::Skill::EXIT_VERIFY_FIXED` = 2 — grep-style exit status when `--verify` applied fixes (0 = clean, 1 = error)
+
+## Testing
+
+Uses Minitest (`Minitest::TestTask`). Unit tests live in `test/gem/skill/`; shared cache-sandboxing helpers in `test/support/cache_helpers.rb`. `scripts/e2e_test` runs a full live pipeline (fetch → generate → cache → link) against a real LLM and requires at least one provider API key.

data/README.md

@@ -5,9 +5,10 @@
   <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>
+      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>
@@ -16,14 +17,15 @@
 
 ## The problem it solves
 
-Every time Claude Code encounters a gem it hasn't seen in the current context, it
-re-reads the README, scans examples, and figures out the API. That costs tokens
-and time — and the result evaporates when the conversation ends.
+Every time an AI coding assistant encounters a gem it hasn't seen in the current
+context, it re-reads the README, scans examples, and figures out the API. That
+costs tokens and time — and the result evaporates when the conversation ends.
 
 `gem-skill` runs that pipeline once, offline, and stores the output as a
-`SKILL.md` in `~/.gem/skills`. Projects symlink to the cached version, so Claude
-has accurate, version-specific knowledge about each gem without repeating the
-ingestion work.
+`SKILL.md` in `~/.gem/skills`. Projects symlink to the cached version, so your
+assistant has accurate, version-specific knowledge about each gem without
+repeating the ingestion work. `SKILL.md` is a shared format — Claude Code,
+OpenAI Codex, and other assistants all read it.
 
 ## How the cache is laid out
 
@@ -38,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/
@@ -48,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
@@ -78,12 +104,22 @@ export GEMINI_API_KEY="..."      # or Gemini
 
 ## Configuration
 
-Two environment variables control `gem-skill`'s behaviour:
+All environment variables and their defaults:
 
 | 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 |
+| `GEMSKIL_MAX_TOKENS` | `32767` | Maximum output tokens per generated skill file |
+| `GEMSKILL_TEMPERATURE` | `0.2` | Sampling temperature (skipped for reasoning models that reject it) |
+| `ANTHROPIC_API_KEY` | _(none)_ | API key for Anthropic / Claude models |
+| `OPENAI_API_KEY` | _(none)_ | API key for OpenAI / GPT models |
+| `GEMINI_API_KEY` | _(none)_ | API key for Google Gemini models |
+| `MISTRAL_API_KEY` | _(none)_ | API key for Mistral models |
+| `DEEPSEEK_API_KEY` | _(none)_ | API key for DeepSeek models |
+| `OPENROUTER_API_KEY` | _(none)_ | API key for OpenRouter |
+| `XAI_API_KEY` | _(none)_ | API key for xAI (Grok) models |
 
 ```bash
 # Store skills on a shared drive accessible to all projects
@@ -91,6 +127,12 @@ 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"
+
+# Raise the output token cap if generated skill files are being truncated
+export GEMSKIL_MAX_TOKENS=65536
 ```
 
 The `--model` flag on any command overrides `GEMSKILL_MODEL` for that
@@ -113,7 +155,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
@@ -130,13 +175,21 @@ 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`
 

data/docs/cache.md

@@ -36,8 +36,9 @@ projects pinning different versions of the same gem each get the correct skill.
 
 ### `SKILL.md`
 
-The generated skill file. Contains structured documentation tailored for
-Claude Code. See [Skill Files](skill-files.md) for the format.
+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`
 
@@ -53,6 +54,52 @@ Stores provenance information:
 }
 ```
 
+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
@@ -81,7 +128,10 @@ 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:
+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/
@@ -89,12 +139,39 @@ your-project/.claude/skills/
 └── zeitwerk →  ~/.gem/skills/zeitwerk/2.8.2/
 ```
 
-Each symlink points to the **version directory**. Claude Code reads `SKILL.md`
-from inside the linked directory.
+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:

data/docs/commands/bundle-skill.md

@@ -2,7 +2,9 @@
 
 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.
+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
 
@@ -42,7 +44,9 @@ bundle skill install [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`) |
+| `--max-tokens TOKENS` | Max output tokens per skill (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
 **Example:**
@@ -66,7 +70,10 @@ All gems are processed concurrently:
   ✓ ruby_llm 1.16.0 done
 ```
 
-After completion, each skill is symlinked into `.claude/skills/`:
+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/
@@ -75,7 +82,8 @@ your-project/.claude/skills/
 └── zeitwerk →  ~/.gem/skills/zeitwerk/2.8.2/
 ```
 
-Claude Code automatically reads `SKILL.md` from each linked directory.
+The assistant automatically reads `SKILL.md` from each linked directory (Claude
+Code reads `.claude/skills/`; other assistants use their own roots).
 
 ---
 
@@ -91,6 +99,7 @@ bundle skill refresh [OPTIONS]
 |------|-------------|
 | `--force` | Regenerate all skills, even those already at the correct version |
 | `--model MODEL` | LLM model to use |
+| `--max-tokens TOKENS` | Max output tokens per skill (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
 
 `refresh` skips gems that are already linked at the correct version (shows
 `up to date`), regenerates gems whose version changed, and removes dead symlinks

data/docs/commands/gem-skill.md

@@ -18,7 +18,10 @@ gem skill install GEM_NAME [GEM_NAME ...]
 | 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`) |
+| `--max-tokens TOKENS` | Max output tokens for this run (overrides `GEMSKIL_MAX_TOKENS`; default: 32767) |
+| `--temperature TEMP` | Sampling temperature, skipped by reasoning models (overrides `GEMSKILL_TEMPERATURE`; default: 0.2) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
 **Examples:**
@@ -32,11 +35,72 @@ 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
+
+# Raise the token cap to avoid truncated output
+gem skill install rails --max-tokens 65536
+
+# Lower the temperature for more reproducible output (temperature-capable models)
+gem skill install faraday --model claude-sonnet-4-6 --temperature 0.0
 ```
 
 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`
@@ -63,20 +127,35 @@ All gems are processed concurrently — you'll see a live spinner per gem:
 
 ### `gem skill setup`
 
-Register gem-skill as a Bundler plugin (run once after `gem install gem-skill`).
+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.
+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.
+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
@@ -88,12 +167,18 @@ gem skill list
 Cached skills in /Users/you/.gem/skills:
 
   debug_me                       1.1.0
-  faraday                        2.12.0, 2.14.3
-  zeitwerk                       2.8.2
+  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`

data/docs/configuration.md

@@ -37,6 +37,67 @@ Controls where generated skills are cached.
 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).
+
+### `GEMSKIL_MAX_TOKENS`
+
+Controls the maximum number of output tokens the LLM may generate for each skill file.
+Increase this if generated `SKILL.md` files are being truncated.
+
+| | |
+|---|---|
+| **Default** | `32767` |
+| **Example** | `export GEMSKIL_MAX_TOKENS=65536` |
+
+### `GEMSKILL_TEMPERATURE`
+
+Sampling temperature for generation. Lower values produce more consistent,
+deterministic output — appropriate for factual reference documentation.
+
+| | |
+|---|---|
+| **Default** | `0.2` |
+| **Example** | `export GEMSKILL_TEMPERATURE=0.0` |
+
+Only applied to models that support a temperature parameter. Reasoning models
+(e.g. `gpt-5.5`) reject it, so the value is silently skipped for them — switch to
+a temperature-supporting model (Claude, Gemini, older GPT) to benefit.
+
 ### `GEMSKILL_MODEL`
 
 Controls which LLM model is used when generating skills.