gem-skill 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81806de91a59a0b2f9144dedebda65f568d61629064f6182f753229fced49583
-  data.tar.gz: 444441e8f081192ceb5b6201bc8c2c9428b243729df896a4405db562d435ad7d
+  metadata.gz: c425b88d925bd6ef993c1ea04581ffd0e457bebc9137cccf68cf3aacd6e00fde
+  data.tar.gz: ba39b45df96bc6f76c6b2ffa950a3a2cafbba4b7c0b2bfd94ecbd9cd4b38cd06
 SHA512:
-  metadata.gz: 39ed27eb70e0036d097b01576a78a20a13ed337ddf05abfc5f5a63a0279b65c79d327907cc70fa96d132d7e72ae3d47ce5cdb5a0bb50e30cbfbb441ce428611d
-  data.tar.gz: 6c0fd5f43ffeac14efe923f9b1742ab469d3e08c50f86dd521c38d45d003800fe45a8447dcb682df0014419d1421d1b2f20eb326d3b6c7f2d3b1d7d0210974bb
+  metadata.gz: 7b4558c9312730d8d7218951591985d868db5bea5f4282f52702ad01feb5ec381c3cfe5af56cb9b50cfa5c45b58e5dbf54bbefee99d6c36d033598383977c35e
+  data.tar.gz: 7464f9cd590e6899ad7a4d2b5a464c42c054ce4287502625349f5cb438e3c66e53e4b56ab7291f8730404f9f9f9f4636a7412cf736a40f40e6dce9a94a5ff048

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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

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
@@ -82,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
@@ -91,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
@@ -113,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
@@ -130,13 +163,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,6 +44,7 @@ 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`) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
@@ -66,7 +69,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 +81,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).
 
 ---
 

data/docs/commands/gem-skill.md

@@ -18,6 +18,7 @@ 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`) |
 | `--version`, `-v` | Print the installed gem-skill version and exit |
 
@@ -32,11 +33,66 @@ gem skill install faraday zeitwerk dry-validation
 
 # Force regeneration with a specific model
 gem skill install rails --force --model claude-opus-4-8
+
+# Generate, then verify the result against the gem's source code
+gem skill install tty-spinner --verify
 ```
 
 If a gem is not installed locally, gem-skill will install it automatically
 before generating the skill.
 
+### Verifying against source (`--verify`)
+
+The generation pass synthesizes a skill from a gem's README, changelog, and
+examples. That prose is sometimes stale or wrong about exact method signatures,
+default argument values, and behavior. `--verify` adds a second pass that checks
+the generated skill against the gem's **actual installed source code** (the only
+source of truth) and rewrites anything the source contradicts.
+
+Verification requires the gem to be installed locally (it reads `lib/**/*.rb`).
+If no source is available, the skill is left untouched.
+
+**Exit status** (so CI can detect README/source drift):
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success — skill was clean, or `--verify` not used |
+| `1` | Error |
+| `2` | `--verify` found and corrected problems |
+
+Either way, `metadata.json` gains a `verification` block recording that the gem's
+actual source was consulted, which files were examined, and — when fixes were
+applied — an array of structured, issue-ready corrections (affected symbol,
+source location, what the skill said vs. the truth, and the proving source
+snippet). See [Cache layout](cache.md#metadatajson) for the full schema.
+
+A verified skill is flagged with a green checkmark in
+[`gem skill list`](#gem-skill-list).
+
+---
+
+### `gem skill verify`
+
+Verify an **already-cached** skill against the gem's source, in place, without
+regenerating it.
+
+```bash
+gem skill verify GEM_NAME [GEM_NAME ...]
+```
+
+This runs the same source-truth check as `--verify`, but never generates: the
+gem must be installed (verification reads its source) and the skill must already
+be cached. It errors if either is missing rather than generating a new skill.
+
+```bash
+# Verify the cached tty-spinner skill against its installed source
+gem skill verify tty-spinner
+```
+
+Exit status matches `--verify`: `0` clean, `1` error, `2` when corrections were
+applied. Verified versions are flagged with a green checkmark in
+[`gem skill list`](#gem-skill-list).
+
 ---
 
 ### `gem skill --version`
@@ -63,20 +119,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 +159,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,43 @@ 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).
+
 ### `GEMSKILL_MODEL`
 
 Controls which LLM model is used when generating skills.

data/docs/how-it-works.md

@@ -16,6 +16,9 @@ Gemfile.lock / gem name
       ↓
   Cache             write to ~/.gem/skills/<gem>/<version>/
       ↓
+  Verifier          (optional, --verify) check the skill's code against the
+                    gem's actual source; correct mismatches in place
+      ↓
   Linker            symlink .claude/skills/<gem> → cache dir
 ```
 
@@ -78,27 +81,71 @@ Manages the global skill cache. Structure:
 └── <gem_name>/
     └── <version>/
         ├── SKILL.md
-        └── metadata.json   (gem, version, model, generated_at, sources)
+        └── metadata.json   (gem, version, model, generated_at, sources,
+                             and after --verify: a "verification" block with
+                             source provenance + structured changes)
 ```
 
 `Cache::ROOT` is set once at load time from `GEMSKILL_DIR` (default: `~/.gem/skills`).
 
+`read_metadata` / `write_skill` / `merge_metadata` let the verifier rewrite a
+cached skill and annotate its metadata without clobbering the original
+`generated_at`, `model`, or `sources`.
+
+### Verifier
+
+`lib/gem/skill/verifier.rb`
+
+Optional second pass, enabled by `--verify`. Generation synthesizes prose
+sources (README, changelog, examples) which are frequently stale or wrong about
+exact signatures. The verifier re-checks the generated skill against the gem's
+**actual source code** — the only source of truth — and corrects mismatched
+method signatures, default argument values, visibility, return values, and
+behavioral claims.
+
+```ruby
+Verifier.new(gem_name, version, model:).verify(skill_content)
+# => Result(content:, changes:, changed:, verifiable:, source:, model:)
+```
+
+Ground truth comes from `Fetcher#source_code` (the gem's `lib/**/*.rb`), and
+`Fetcher#source_manifest` records which files were examined. Whether the skill
+actually changed is decided by a **deterministic diff** of the content before and
+after — not by trusting the model's self-report — so the exit code is reliable.
+If no installed source is available, `verifiable` is false and the skill is left
+untouched.
+
+Each correction in `changes` is a structured, issue-ready Hash
+(`category`, `symbol`, `skill_section`, `source_location`, `was`, `now`,
+`detail`, `source_evidence`) — detailed enough to file a documentation bug
+against the gem. The Runner writes these, plus source provenance, into the
+`verification` block of `metadata.json`.
+
 ### Linker
 
 `lib/gem/skill/linker.rb`
 
-Creates and manages directory symlinks in `.claude/skills/` inside a project:
+Creates and manages directory symlinks in the project's skill directory
+(default `.claude/skills/`, Claude Code's convention):
 
 ```
-.claude/skills/<gem_name>  →  ~/.gem/skills/<gem_name>/<version>/
+<project_dir>/<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.
+The directory is `Linker.project_dir`, read from `GEMSKILL_PROJECT_DIR` each call
+(default `.claude/skills`). Codex users set it to `.agents` or `.codex` so
+`bundle skill` links into a Codex root instead. Symlinks point to the **version
+directory**, not directly to `SKILL.md`; the assistant discovers `SKILL.md` by
+reading inside the linked directory.
 
 `Linker.prune_dead_links` removes any symlink whose target no longer exists
 in the cache (e.g. after `gem skill purge`).
 
+The cache itself is assistant-neutral. `SKILL.md` is a shared format; other
+assistants read it from their own roots. Note that linking only makes a skill
+*available* — some assistants (e.g. Codex) require it to be in the available-skills
+list or referenced explicitly before it's *active*.
+
 ### Runner
 
 `lib/gem/skill/runner.rb`
@@ -107,12 +154,14 @@ 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
+Runner.install_skill(gem_name, version, spinner, force:, model:, verify:)
+# => Runner::Result(error:, verify_fixed:, change_count:)
 ```
 
-Returns the error message rather than raising, so the caller (the concurrent
-fiber) can record it without killing other in-flight fibers.
+Captures errors into the result rather than raising, so the caller (the
+concurrent fiber) can record them without killing other in-flight fibers. When
+`verify:` is set, the result's `verify_fixed` lets the CLI aggregate across all
+gems and exit `2` (`EXIT_VERIFY_FIXED`) if any skill was corrected.
 
 ---