gem-skill 0.1.3 → 0.2.0

data/lib/gem/skill/frontmatter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Gem::Skill
+  # Builds the YAML frontmatter that makes a SKILL.md discoverable as an Agent
+  # Skill. Both Claude Code and OpenAI Codex require `name` + `description`
+  # frontmatter; without it the file is never registered/triggered as a skill.
+  #
+  # Constraints satisfied here (intersection of both assistants):
+  #   - name: lowercase letters, digits, hyphens only; no leading/trailing or
+  #     doubled hyphens; <= 40 chars (Claude Code's rule, also valid for Codex)
+  #   - description: single line, no angle brackets (Claude Code rejects < and >),
+  #     length-capped (Codex shortens long descriptions)
+  #
+  # Generation is deterministic (no LLM): the name is derived from the gem name
+  # and the description from the skill's Overview section, so the frontmatter is
+  # always valid regardless of what the model emitted.
+  module Frontmatter
+    MAX_NAME_LENGTH        = 40
+    MAX_DESCRIPTION_LENGTH = 500
+
+    module_function
+
+    # Return content with a freshly-built, valid frontmatter block. Any existing
+    # leading frontmatter is stripped and replaced, so this is idempotent.
+    def build(gem_name, version, content)
+      body = strip(content)
+      fm   = "---\nname: #{slug(gem_name)}\ndescription: #{yaml_quote(description_for(gem_name, version, body))}\n---\n"
+      "#{fm}\n#{body}"
+    end
+
+    # True when content already begins with a YAML frontmatter block.
+    def present?(content)
+      content.to_s.lstrip.start_with?("---")
+    end
+
+    # Remove a leading frontmatter block (if any) and return the body.
+    def strip(content)
+      content.to_s.sub(/\A\s*---\s*\n.*?\n---\s*\n+/m, "").lstrip
+    end
+
+    # Gem name -> valid skill name. "ruby_llm" -> "ruby-llm", "TTY-Spinner" ->
+    # "tty-spinner". Falls back to "skill" if nothing usable remains.
+    def slug(gem_name)
+      s = gem_name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      s = "skill" if s.empty?
+      s[0, MAX_NAME_LENGTH].sub(/-+\z/, "")
+    end
+
+    # Derive a trigger-oriented description from the body's Overview section,
+    # appending the version for context. Sanitized for both assistants.
+    def description_for(gem_name, version, body)
+      overview = body[/^##\s+Overview\s*\n+(.+?)(?=\n\s*\n|\n##\s|\z)/m, 1]
+      text     = overview || "Ruby gem #{gem_name}. Use when working with #{gem_name} in Ruby code."
+      text     = text.gsub(/\s+/, " ").delete("<>").strip
+      text     = "#{text} (#{gem_name} v#{version})" unless text.include?(version.to_s)
+      text[0, MAX_DESCRIPTION_LENGTH].strip
+    end
+
+    # Quote a string as a YAML double-quoted scalar, escaping \ and ".
+    def yaml_quote(str)
+      %("#{str.gsub(/[\\"]/) { |c| "\\#{c}" }}")
+    end
+  end
+end

data/lib/gem/skill/generator.rb

@@ -73,6 +73,7 @@ module Gem::Skill
       raise Error, "No documentation found for #{gem_name} #{version}" if sources.empty?
 
       skill_content = block ? call_llm_streaming(sources, &block) : call_llm(sources)
+      skill_content = Frontmatter.build(gem_name, version, skill_content)
       Cache.store(gem_name, version, skill_content, { sources: sources.keys.map(&:to_s), model: model })
       skill_content
     rescue RubyLLM::Error => e

data/lib/gem/skill/linker.rb

@@ -3,12 +3,26 @@
 require "fileutils"
 
 module Gem::Skill
-  # Manages .claude/skills/ symlinks in a project, pointing to ~/.gem/skills cache.
+  # Manages per-project skill symlinks pointing into the ~/.gem/skills cache.
   # Each symlink is a directory link: <gem_name> -> ~/.gem/skills/<gem>/<version>/
-  # Claude Code discovers skills by reading SKILL.md inside each linked directory.
+  # The assistant discovers skills by reading SKILL.md inside each linked directory.
+  #
+  # The project-relative directory is configurable via GEMSKILL_PROJECT_DIR
+  # (default ".claude/skills" for Claude Code). Codex users might set it to
+  # ".agents" or ".codex"; see the configuration docs.
   module Linker
+    DEFAULT_PROJECT_DIR = ".claude/skills"
+
+    # Project-relative directory where skill symlinks are written. Read from the
+    # environment each call so a changed GEMSKILL_PROJECT_DIR takes effect without
+    # reloading.
+    def self.project_dir
+      value = ENV.fetch("GEMSKILL_PROJECT_DIR", DEFAULT_PROJECT_DIR).to_s.strip
+      value.empty? ? DEFAULT_PROJECT_DIR : value
+    end
+
     def self.skills_dir(project_root = Dir.pwd)
-      File.join(project_root, ".claude", "skills")
+      File.join(project_root, project_dir)
     end
 
     def self.link(gem_name, version, project_root = Dir.pwd)

data/lib/gem/skill/runner.rb

@@ -1,24 +1,84 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Gem::Skill
   # Core install logic shared by gem_command and bundle_command.
   # Callers are responsible for spinner.auto_spin and title setup before calling.
   module Runner
-    # Generate + cache + link one skill.
-    # Returns nil on success, error message string on failure.
-    def self.install_skill(gem_name, version, spinner, force:, model:)
+    # error:        nil on success, message string on failure
+    # verify_fixed: true when --verify ran and corrected the skill
+    Result = Data.define(:error, :verify_fixed) do
+      def ok? = error.nil?
+
+      def self.failure(message) = new(error: message, verify_fixed: false)
+      def self.success(verify_fixed: false) = new(error: nil, verify_fixed: verify_fixed)
+    end
+
+    # Generate + cache + link one skill, optionally verifying it against source.
+    # Returns a Runner::Result.
+    def self.install_skill(gem_name, version, spinner, force:, model:, verify: false)
       if Cache.cached?(gem_name, version) && !force
         Linker.link(gem_name, version)
-        spinner.success("already cached")
-        return nil
+        content = Cache.read(gem_name, version)
+        return finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "already cached")
       end
-      Generator.new(gem_name, version, model: model).generate(force: force)
+
+      content = Generator.new(gem_name, version, model: model).generate(force: force)
       Linker.link(gem_name, version)
-      spinner.success("done")
-      nil
+      finalize(gem_name, version, content, spinner, model: model, verify: verify, status: "done")
     rescue => e
       spinner.error("failed")
-      e.message
+      Result.failure(e.message)
+    end
+
+    # Run the optional verify pass and settle the spinner + metadata.
+    def self.finalize(gem_name, version, content, spinner, model:, verify:, status:)
+      unless verify
+        spinner.success(status)
+        return Result.success
+      end
+
+      result = Verifier.new(gem_name, version, model: model).verify(content)
+
+      unless result.verifiable
+        Cache.merge_metadata(gem_name, version, verification: {
+          verified:       false,
+          verified_at:    Time.now.iso8601,
+          model:          model,
+          skipped_reason: "no installed source available"
+        })
+        spinner.success("#{status} (no source to verify)")
+        return Result.success
+      end
+
+      Cache.write_skill(gem_name, version, result.content) if result.changed?
+      Cache.merge_metadata(gem_name, version, verification: verification_metadata(result))
+
+      if result.changed?
+        spinner.success("verified — fixed")
+        Result.success(verify_fixed: true)
+      else
+        spinner.success("verified — ok")
+        Result.success
+      end
+    rescue => e
+      spinner.error("verify failed")
+      Result.failure(e.message)
+    end
+    private_class_method :finalize
+
+    # Records that the skill was verified against real source and whether that
+    # verification changed anything. Intentionally minimal — the itemized list of
+    # what changed is not retained.
+    def self.verification_metadata(result)
+      {
+        verified:    true,
+        verified_at: Time.now.iso8601,
+        model:       result.model,
+        fixed:       result.changed?
+      }
     end
+    private_class_method :verification_metadata
   end
 end

data/lib/gem/skill/verifier.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Gem::Skill
+  # Second-pass quality gate for a generated SKILL.md.
+  #
+  # Generation synthesizes prose sources (README, changelog, examples) which are
+  # frequently wrong or stale 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.
+  #
+  # 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 callers
+  # can rely on #changed? for an exit code and a "fixed" flag.
+  class Verifier
+    BEGIN_MARK = "===BEGIN SKILL==="
+    END_MARK   = "===END SKILL==="
+
+    SYSTEM_INSTRUCTIONS = <<~SYSTEM
+      You verify a generated Claude Code SKILL.md for a Ruby gem against the gem's
+      ACTUAL SOURCE CODE. The source code is the only source of truth. READMEs,
+      changelogs, and docstrings are frequently stale or wrong; when the SKILL.md
+      disagrees with the source, the source always wins.
+
+      Check every concrete claim against the source: method signatures, default
+      argument values, keyword vs positional arguments, public/private/protected
+      visibility, return values, constant and class/module names, default option
+      values, and described runtime behavior (including what arguments a yielded
+      block actually receives). Correct anything the source contradicts.
+
+      Rules:
+      - Do NOT invent APIs, methods, or options that are absent from the source.
+      - Do NOT restructure, re-style, or "improve" content that is already correct.
+        Preserve correct text verbatim so the diff stays minimal.
+      - Only change what the source proves is wrong.
+    SYSTEM
+
+    PROMPT = <<~PROMPT
+      Verify the SKILL.md below for "%<gem_name>s" v%<version>s against the gem's
+      source code. Correct every claim the source contradicts.
+
+      Output ONLY the full corrected SKILL.md in raw Markdown (even if you change
+      nothing), wrapped exactly between these marker lines and with no other text:
+      %<begin_mark>s
+      <corrected SKILL.md here>
+      %<end_mark>s
+
+      ============================================================
+      CURRENT SKILL.md
+      ============================================================
+
+      %<skill>s
+
+      ============================================================
+      GEM SOURCE CODE (ground truth)
+      ============================================================
+
+      %<source>s
+    PROMPT
+
+    # content:    the (possibly corrected) skill markdown
+    # changed:    true iff content differs from the original (diff-based)
+    # verifiable: false when no source was available to check against
+    # model:      the model used for verification
+    Result = Data.define(:content, :changed, :verifiable, :model) do
+      def changed? = changed
+    end
+
+    attr_reader :gem_name, :version, :model
+
+    def initialize(gem_name, version, model: Generator::DEFAULT_MODEL)
+      @gem_name = gem_name
+      @version  = version
+      @model    = model
+    end
+
+    # Verify skill_content against the gem source. Returns a Result.
+    def verify(skill_content)
+      fetcher = Fetcher.new(gem_name, version)
+      source  = fetcher.source_code
+      if source.nil? || source.strip.empty?
+        return Result.new(content: skill_content, changed: false, verifiable: false, model: model)
+      end
+
+      raw       = build_chat.ask(format_prompt(skill_content, source)).content.to_s
+      # Re-apply frontmatter to both sides so the diff compares like-for-like and
+      # the stored skill always keeps valid frontmatter, even if the model dropped it.
+      original  = Frontmatter.build(gem_name, version, skill_content)
+      corrected = Frontmatter.build(gem_name, version, extract_skill(raw, skill_content))
+      changed   = normalize(corrected) != normalize(original)
+
+      Result.new(content: (changed ? corrected : skill_content), changed: changed,
+                 verifiable: true, model: model)
+    rescue RubyLLM::Error => e
+      raise Error, e.message
+    end
+
+    private
+
+    def build_chat
+      RubyLLM.chat(model: model).with_instructions(SYSTEM_INSTRUCTIONS)
+    end
+
+    def format_prompt(skill_content, source)
+      format(
+        PROMPT,
+        gem_name:   gem_name,
+        version:    version,
+        begin_mark: BEGIN_MARK,
+        end_mark:   END_MARK,
+        skill:      skill_content,
+        source:     source
+      )
+    end
+
+    # Pull the corrected skill out from between the markers. If the model didn't
+    # honor the protocol, fall back to the original so we never corrupt the cache.
+    def extract_skill(raw, fallback)
+      start = raw.index(BEGIN_MARK)
+      return fallback unless start
+
+      body = raw[(start + BEGIN_MARK.length)..]
+      stop = body.index(END_MARK)
+      body = body[0...stop] if stop
+
+      body = body.to_s.strip
+      body.empty? ? fallback : body
+    end
+
+    def normalize(text)
+      text.to_s.gsub(/[ \t]+$/, "").strip
+    end
+  end
+end

data/lib/gem/skill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gem::Skill
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/gem/skill.rb

@@ -3,7 +3,9 @@
 require_relative "skill/version"
 require_relative "skill/cache"
 require_relative "skill/fetcher"
+require_relative "skill/frontmatter"
 require_relative "skill/generator"
+require_relative "skill/verifier"
 require_relative "skill/linker"
 require_relative "skill/lockfile"
 require_relative "skill/runner"
@@ -11,6 +13,16 @@ require_relative "skill/runner"
 module Gem::Skill
   class Error < StandardError; end
 
+  # Exit status used when --verify found and corrected mistakes in a generated
+  # skill (grep-style: 0 = clean, 1 = error, 2 = verify applied fixes).
+  EXIT_VERIFY_FIXED = 2
+
+  # The bundled "router" skill that teaches assistants how to find cached gem
+  # skills in ~/.gem/skills. `gem skill setup` copies it into the assistants'
+  # default skill roots. Lives at the repo/gem root, beside README/CHANGELOG.
+  ROUTER_SKILL_NAME = "ruby-gem-skills"
+  ROUTER_SKILL_DIR  = File.expand_path("../../#{ROUTER_SKILL_NAME}", __dir__)
+
   ENV_KEY_MAP = {
     anthropic_api_key:  "ANTHROPIC_API_KEY",
     openai_api_key:     "OPENAI_API_KEY",

data/ruby-gem-skills/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ruby-gem-skills
+description: "Locate and load gem-skill's cached, version-specific SKILL.md for a Ruby gem. Use whenever working with, debugging, or writing Ruby code that uses a third-party gem (Bundler/Gemfile projects or installed gems) to get accurate, version-pinned API knowledge before relying on memory."
+---
+
+# ruby-gem-skills
+
+Detailed, version-specific knowledge for installed Ruby gems is generated by the
+`gem-skill` tool and cached on this machine at:
+
+```
+~/.gem/skills/<gem_name>/<version>/SKILL.md
+```
+
+(Use `$GEMSKILL_DIR` instead of `~/.gem/skills` if that variable is set.)
+
+Most assistants do not scan that directory by default, so follow this procedure
+to find and load a gem's skill before answering from memory.
+
+## When to use
+
+- Writing or debugging Ruby code that calls a third-party gem's API.
+- Verifying exact method signatures, options, defaults, or behavior for a
+  specific gem version.
+
+## How to load a gem's skill
+
+1. Determine the gem version in use:
+   - In a project with a `Gemfile.lock`, read the locked version for the gem.
+   - Otherwise run `gem list <gem_name>` (or `bundle show <gem_name>`) to find
+     the installed version.
+2. Read the cached skill for that exact version:
+   ```
+   ~/.gem/skills/<gem_name>/<version>/SKILL.md
+   ```
+3. If it exists, treat its contents as the authoritative, version-pinned
+   reference for that gem and prefer it over training memory. Skills are
+   version-specific — always match the version actually in use.
+
+## If the skill is missing
+
+Tell the user how to generate it:
+
+- One gem: `gem skill install <gem_name>`
+- Every gem in a project (from the project root): `bundle skill install`
+- Verify an existing skill against the gem's real source: `gem skill verify <gem_name>`
+
+## Notes
+
+- A `metadata.json` sits beside each `SKILL.md` with provenance (model, sources,
+  and verification status). It is for tooling and humans, not required reading.
+- A green checkmark next to a version in `gem skill list` means that skill was
+  verified against the gem's actual source code.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-skill
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -82,14 +82,17 @@ files:
 - lib/gem/skill/cli/bundle_command.rb
 - lib/gem/skill/cli/gem_command.rb
 - lib/gem/skill/fetcher.rb
+- lib/gem/skill/frontmatter.rb
 - lib/gem/skill/generator.rb
 - lib/gem/skill/linker.rb
 - lib/gem/skill/lockfile.rb
 - lib/gem/skill/runner.rb
+- lib/gem/skill/verifier.rb
 - lib/gem/skill/version.rb
 - lib/rubygems_plugin.rb
 - mkdocs.yml
 - plugins.rb
+- ruby-gem-skills/SKILL.md
 - scripts/e2e_test
 - sig/gem/skill.rbs
 homepage: https://github.com/madbomber/gem-skill