gem-skill

Generate SKILL.md 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. Full documentation →

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 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.

~/.gem/skills/
└── chunker-ruby/
    ├── 1.2.3/
    │   ├── SKILL.md        ← generated skill
    │   └── metadata.json   ← gem name, version, model used, generated_at
    └── 1.4.0/
        ├── SKILL.md
        └── metadata.json

Each project's .claude/skills/ directory (Claude Code's convention) holds symlinks that point into this cache:

your-app/.claude/skills/
└── chunker-ruby/  →  ~/.gem/skills/chunker-ruby/1.2.3/

Two projects that pin different versions of the same gem each get the right skill; the underlying content is generated once and shared.

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:

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.

gem install gem-skill
gem skill setup

gem install gives you the gem skill subcommand. gem skill setup registers gem-skill as a Bundler plugin, enabling bundle skill in any project.

You only need to run gem skill setup once per machine. Alternatively, you can add the plugin directly to a project's Gemfile:

plugin "gem-skill"

gem-skill uses RubyLLM to generate skills. Configure at least one provider API key before running:

export OPENAI_API_KEY="..."      # default model: gpt-5.5
export ANTHROPIC_API_KEY="..."   # or use Claude
export GEMINI_API_KEY="..."      # or Gemini

Two environment variables control gem-skill's behaviour:

# Store skills on a shared drive accessible to all projects
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 invocation. GEMSKILL_DIR applies everywhere the cache is read or written.

# Generate a skill for an installed gem (version auto-detected)
gem skill install chunker-ruby

# Install skills for multiple gems at once (runs concurrently)
gem skill install chunker-ruby faraday debug_me

# Force regeneration even if already cached
gem skill install chunker-ruby --force

# Use a different model
gem skill install chunker-ruby --model claude-haiku-4-5

# 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
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.

Run once after gem install gem-skill:

gem skill setup

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.

Generate skills for gems as you install them:

gem install faraday debug_me --with-skill

Skills are generated concurrently after all gems finish installing.

Run from your project root after bundle install:

# Generate and link skills for all direct dependencies
bundle skill install

# Re-sync after bundle update (skips gems already at the correct version)
bundle skill refresh

# Show what's linked in this project
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

Each SKILL.md covers:

• Overview — what the gem does and when to use it
• Installation — exact Gemfile lines and post-install steps
• Core API — key classes and methods with real code examples
• Common Patterns — the 3–5 most frequent real-world usage patterns
• Gotchas & Edge Cases — surprising defaults, version-specific behavior, thread safety, encoding issues
• Configuration — initializer patterns and environment variables
• Testing — how to test code that uses the gem

The content is synthesized from three sources, tried in priority order:

1. Local gem install (Gem::Specification → gem_dir) — README and CHANGELOG
2. RubyGems API — summary, runtime dependencies, source URI
3. GitHub raw README — fetched when the gem isn't installed locally

git clone https://github.com/madbomber/gem-skill
cd gem-skill
bundle install
bundle exec rake test

Bug reports and pull requests welcome at https://github.com/madbomber/gem-skill.

MIT. See LICENSE.txt.